WePay

The /checkout API calls

The "checkout" object represents a single payment and defines the amount, the destination account, the application fee, etc. The following calls let you create, view, and modify "checkout" objects on WePay:

Checkout States

The "checkout" object has the following states and the following possible state transitions (you can receive callback notifications when the checkout changes state, please read our IPN Tutorial for more details):

new
The checkout was created by the application.
authorized
The payer entered their payment info and confirmed the payment on WePay. WePay has successfully charged the card. WePay's risk analysis may still be in progress.
reserved
The payment has been reserved from the payer.
captured
The payment has been credited to the payee account.
cancelled
The payment has been cancelled by the payer, payee, or application.
refunded
The payment was captured and then refunded by the payer, payee, or application. The payment has been debited from the payee account.
charged back
The payment has been charged back by the payer and the payment has been debited from the payee account.
failed
The payment has failed.
expired
Checkouts get expired if they are still in state new after 30 minutes (ie they have been abandoned).

API Checkout State Diagram

Partial refunds and chargebacks

If you do a partial refund for a checkout or there is a partial chargeback from the payer, then the checkout will stay in state "captured" until the whole amount is refunded or charged back. You will however, have the amount_refunded and amount_charged_back response parameters to tell you if a partial refund or chargeback have taken place, and if so how much has been refunded or charged back.

/checkout

This call allows you to lookup the details of a specific checkout on WePay using the checkout_id. Response parameters marked "if available" will only show up if they have values.

Arguments:

Parameter Required Type Description
checkout_id Yes Integer (64 bits) The unique ID of the checkout you want to look up.

Example:

{
  "checkout_id":12345
}

Response:

Response Type Description
checkout_id Integer (64 bits) The unique ID of the checkout.
account_id Integer (64 bits) The unique ID of the account that the money will go into.
preapproval_id Integer (64 bits) The unique ID of the preapproval associated with the checkout (if applicable).
create_time Integer (64 bits) The unixtime when the checkout was created (always UTC).
state String (255 chars) The state the checkout is in. See the checkout states section for a listing of all states.
soft_descriptor String (255 chars) The payment description that will show up on payer's credit card statement.
short_description String (255 chars) The short description of the checkout. Max 255 chars.
long_description String (2047 chars) The long description of the checkout (if available). Max 2047 chars.
currency String (255 chars) The currency used, default "USD" ("USD" for now).
amount Decimal (64 bits) The dollar amount of the checkout object (ex. 3.20). This will always be the amount you passed in /checkout/create.
shipping_fee Decimal (64 bits) The amount that you want to charge for shipping.
fee Decimal (64 bits) The dollar amount of the WePay fee.
gross Decimal (64 bits) The total dollar amount paid by the payer.
app_fee Decimal (64 bits) The dollar amount that the application received in fees. App fees go into the API application's WePay account.
amount_refunded Decimal (64 bits) If this checkout has been fully or partially refunded, this has the amount that has been refunded so far.
amount_charged_back Decimal (64 bits) If this checkout has been fully or partially charged back, this has the amount that has been charged back so far.
fee_payer String (255 chars) Who is paying the fee (either "payer" for the person paying, "payee" for the person receiving the money, "payer_from_app" if payer is paying for app fee and the app is paying WePay fees, or "payee_from_app" if payee is paying for app fee and app is paying for WePay fees).
reference_id String (255 chars) The unique reference_id passed by the application (if available).
redirect_uri String (2083 chars) The uri the payer will be redirected to after payment (if available).
callback_uri String (2083 chars) The uri which instant payment notifications will be sent to.
dispute_uri String (2083 chars) The uri that payers can visit to open a dispute for this checkout. Do not store the returned URI on your side as it can change.
payer_email String (255 chars) The email address of the person paying (only returned if a payment has been made).
payer_name String (255 chars) The name of the person paying (only returned if a payment has been made).
cancel_reason String (255 chars) If the payment was canceled, the reason why.
refund_reason String (255 chars) If the payment was refunded the reason why.
auto_capture Boolean Default is true. If set to false then the payment will not automatically be released to the account and will be held by WePay in payment state 'reserved'. To release funds to the account you must call /checkout/capture
require_shipping Boolean Default is false. If set to true then the payer will be required to enter their shipping address when paying.
shipping_address Shipping Address Structure If 'require_shipping' was set to true and the payment was made, this will be the shipping shipping address structure (a JSON object, not a JSON serialized string) that the payer entered.
mode String (255 chars) The mode that the checkout was displayed in.

Example:

{
  "checkout_id":12345,
  "account_id":54321,
  "state":"captured",
  "soft_descriptor": "WPY*Test2",
  "short_description":"Donation to Smith Cancer Fund",
  "long_description":"This is a donation to help Bob Smith get treatment",
  "currency":"USD",
  "amount":"100",
  "fee":":"3.2",
  "gross":"108.2",
  "app_fee":"5"
  "shipping_fee": 5,
  "fee_payer":"payer",
  "reference_id":"abc123",
  "redirect_uri":"http://example.com/callback/donation_success/1531"
  "callback_uri":"http://example.com/callback/status/1531",
  "payer_email":"api@wepay.com",
  "payer_name":"Bill Clerico",
  "auto_capture":true
}

/checkout/find

This call allows you to search for checkouts associated with an account. Returns an array of matching checkouts.

Arguments:

Parameter Required Type Description
account_id Yes Integer (64 bits) The unique ID of the account whose checkouts you are searching.
start No Integer (64 bits) The start position for your search (default 0).
limit No Integer (64 bits) The maximum number of returned entries (default 50).
reference_id No String (255 chars) The unique reference id of the checkout (set by the application in /checkout/create).
state No String (255 chars) What state the checkout is in (see the checkout states section reference for details).
preapproval_id No Integer (64 bits) The ID of the preapproval that was used to create the checkout. Useful if you want to look up all of the payments for an auto_recurring preapproval.
start_time No Integer (64 bits) or String (255 chars) All checkouts after given start time. Can be a unix_timestamp or a valid, parse-able date-time.
end_time No Integer (64 bits) or String (255 chars) All checkouts before given end time. Can be a unix_timestamp or a valid, parse-able date-time.
sort_order No String (255 chars) Sort the results of the search by time created. Use 'DESC' for most recent to least recent. Use 'ASC' for least recent to most recent. Defaults to 'DESC'.
shipping_fee No Decimal (64 bits) All checkouts that have the given shipping fee.

Example:

{
  "account_id":54321,
  "start":10,
  "limit":20,
  "reference_id":"123abc",
  "state":"captured"
}

Response:

An array of checkouts matching the search parameters. Each element of the array will include the same data as returned from the /checkout call.

Example:

[
   {
     "checkout_id":12345,
     "account_id":54321,
     "state":"captured",
     "soft_descriptor": "WPY*Test2",
     "short_description":"Donation to Smith Cancer Fund",
     "long_description":"This is a donation to help Bob Smith get treatment",
     "currency":"USD",
     "amount":"100",
     "fee":":"3.2",
     "gross":"108.2",
     "app_fee":"5",
     "shipping_fee": 5,
     "fee_payer":"payer",
     "reference_id":"abc123",
     "redirect_uri":"http://example.com/callback/donation_success/1531"
     "callback_uri":"http://example.com/callback/status/1531",
     "payer_email":"api@wepay.com",
     "payer_name":"Bill Clerico",
     "auto_capture":true,
   },
   {
     "checkout_id":555112,
     "account_id":54321,
     "state":"captured",
     "soft_descriptor": "WPY*Test2",
     "short_description":"Donation to Smith Cancer Fund",
     "long_description":"This is a donation to help Bob Smith get treatment",
     "currency":"USD",
     "amount":"200",
     "fee":":"7",
     "gross":"217",
     "app_fee":"10",
     "shipping_fee": 5,
     "fee_payer":"payer",
     "reference_id":"def456",
     "redirect_uri":"http://example.com/callback/donation_success/1531"
     "callback_uri":"http://example.com/callback/status/1531",
     "payer_email":"support@wepay.com",
     "payer_name":"Sophie Monroe",
     "auto_capture":true
   }
]

/checkout/create

Creates a checkout for an account. The application can send a user to the checkout_uri so the user can pay the account for the amount specified.

Checkouts expire 30 minutes after they are created if there is no activity on them (e.g. they were abandoned after creation).

Arguments:

Parameter Required Type Description
account_id Yes Integer (64 bits) The unique ID of the account you want to create a checkout for.
short_description Yes String (255 chars) A short description of what is being paid for. Max 255 chars.
type Yes String (255 chars) The the checkout type (one of the following: GOODS, SERVICE, DONATION, EVENT or PERSONAL)
amount Yes Decimal (64 bits) The amount that the payer will pay.
currency No String (3 chars) The currency used, default "USD" ("USD" for now).
long_description No String (2047 chars) A long description of what is being paid for. Max 2047 chars.
payer_email_message No String (65535 chars) A short message that will be included in the payment confirmation email to the payer.
payee_email_message No String (65535 chars) A short message that will be included in the payment confirmation email to the payee.
reference_id No String (255 chars) A customer-supplied reference id.
app_fee No Decimal (64 bits) The dollar amount that the application will receive in fees. App fees go into the API applications WePay account. Limited to 20% of the checkout amount.
fee_payer No String (255 chars)

Who will pay the fees (WePay's fees and any app fees).

Set to "payer" (case-sensitive) to charge fees to the person paying (Payer will pay amount + fees, and payee will receive amount).

Set to "payee" to charge fees to the person receiving money (Payer will pay amount, and payee will receive amount - fees).

Set to "payer_from_app" so that payer will be charged app fee (if there is one) and API application will be charged WePay fee.

Set to "payee_from_app" so that payee will be charged the app fee (if there is one) and the API application will be charged the WePay fee. Note that for the xxx_from_app calls: if the application's account goes negative, WePay will recover funds from bank account.

Defaults to "payer".

redirect_uri No String (2083 chars) The uri the payer will be redirected to after paying. If you do not pass a redirect_uri, the user will see a payment confirmation page (and if you are using the iframe we will send a postMessage to the parent window indicating that the payment is complete).
callback_uri No String (2083 chars) The uri that will receive any instant payment notifications sent. Needs to be a full uri (ex https://www.wepay.com ) and must NOT be localhost or 127.0.0.1 or include wepay.com.
fallback_uri No String (2083 chars) The uri that the payer will be redirected to if cookies cannot be set in the iframe; will only work if mode is iframe.
auto_capture No Boolean A boolean value (true or false) default is true. If set to false then the payment will not automatically be released to the account and will be held by WePay in payment state 'reserved'. To release funds to the account you must call /checkout/capture. If you do not capture the funds within 14 days then the payment will be automatically cancelled or refunded. This is a JSON boolean so you can pass "auto_capture":false (no quotes). We will also accept "auto_capture":0
require_shipping No Boolean A boolean value (true or false) default is false. If set to true then the payer will be asked to enter a shipping address when they pay. After payment you can retrieve this shipping address by calling /checkout
shipping_fee No Decimal (64 bits) The amount that you want to charge for shipping.
mode No String (255 chars) What mode the checkout will be displayed in. The options are 'iframe' or 'regular'. Choose 'iframe' if this is an iframe checkout. Mode defaults to 'regular'.
preapproval_id No Integer (64 bits) The ID of a preapproval object. If you include a valid preapproval_id the checkout will be executed immediately, and the payer will be charged without having to go to the checkout_uri. You should not have to send the payer to the checkout_uri.
prefill_info No Prefill_Info Structure Information to pre fill certain fields in the checkout flow (a JSON object, not a JSON serialized string).
funding_sources No String (255 chars) What funding sources you want to accept for this checkout. Options are: "bank,cc" to accept both bank and cc payments, "cc" to accept just credit card payments, and "bank" to accept just bank payments.
payment_method_id No Integer (64 bits) If you are using credit card tokenization use the credit_card_id you received from the /credit_card/create call.
payment_method_type No String (255 chars) Set to 'credit_card' for tokenization.
unique_id No String (255 chars) Customer-generated unique_id. WePay will only process a single call with a given unique_id. Platforms can use this to prevent duplicates, e.g. when retrying if a call times out.

Example:

{
  "account_id":54321,
  "short_description":"Donation to Smith Cancer Fund",
  "long_description":"This is a donation to help Bob Smith get the treatment",
  "type":"DONATION",
  "reference_id":"abc123",
  "amount":"100.75",
  "currency":"USD",
  "app_fee":"5.5",
  "fee_payer":"payee",
  "redirect_uri":"http://example.com/callback/donation_success/1531",
  "callback_uri":"http://example.com/callback/status/1531",
  "auto_capture":false,
  "mode":"iframe"
}

Response:

This call will return the same response as the /checkout call.

/checkout/cancel

Cancels the payment associated with the checkout created by the application. Checkout must be in "authorized" or "reserved" state.

Arguments:

Parameter Required Type Description
checkout_id Yes Integer (64 bits) The unique ID of the checkout to be canceled.
cancel_reason Yes String (255 chars) The reason the payment is being cancelled.

Example:

{
  "checkout_id":12345,
  "cancel_reason":"Product was defective. Do not want."
}

Response:

Response Type Description
checkout_id Integer (64 bits) The unique ID of the checkout that was successfully cancelled.
state String (255 chars) The state the payment is in. See the checkout states section for a list of payment states.

Example:

{
  "checkout_id":12345,
  "state":"cancelled"
}

/checkout/refund

Refunds the payment associated with the checkout created by the application. Checkout must be in "captured" state.

Arguments:

Parameter Required Type Description
checkout_id Yes Integer (64 bits) The unique ID of the checkout to be refunded.
refund_reason Yes String (255 chars) The reason the payment is being refunded.
amount No Decimal (64 bits) The total amount that will be refunded back to the payer. Note that this amount must be less than the 'net' of the transaction. To perform a full refund, do not pass the amount parameter.
app_fee No Decimal (64 bits) The portion of the 'amount' that will be refunded as an app_fee refund. For example, if 'amount' is 100.00 and 'app_fee' is 10.00, then the payer will receive a refund of 100.00, where 90.00 is the net refund from the payment account, and 10.00 is the app_fee refund. Note that this value must be less than the remaining balance of the app fee.
payer_email_message No String (65535 chars) A short message that will be included in the payment refund email to the payer.
payee_email_message No String (65535 chars) A short message that will be included in the payment refund email to the payee.

Example:

{
  "checkout_id":12345,
  "refund_reason":"Product was defective. Do not want."
}

Response:

Response Type Description
checkout_id Integer (64 bits) The unique ID of the checkout that was successfully refunded.
state String (255 chars) The state the payment is in. See the checkout states section for a list of payment states.

Example:

{
  "checkout_id":12345,
  "state":"refunded"
}

/checkout/capture

If auto_capture was set to false when the checkout was created, you will need to make this call to release funds to the account. Until you make this call the money will be held by WePay and if you do not capture the funds within 14 days then the payment will be automatically cancelled or refunded. You can only make this call if the checkout is in state 'reserved'.

Arguments:

Parameter Required Type Description
checkout_id Yes Integer (64 bits) The unique ID of the checkout to be captured.

Example:

{
  "checkout_id":12345
}

Response:

Response Type Description
checkout_id Integer (64 bits) The unique ID of the checkout that was successfully captured.
state String (255 chars) The state the payment is in. See the checkout states section for a list of payment states.

Example:

{
  "checkout_id":12345,
  "state":"captured"
}

/checkout/modify

This call allows you to modify the callback_uri of a checkout.

Arguments:

Parameter Required Type Description
checkout_id Yes Integer (64 bits) The unique ID of the checkout you want to modify.
callback_uri No String (2083 chars) The uri that will receive any instant payment notifications sent. Needs to be a full uri (ex https://www.wepay.com ) and must NOT be localhost or 127.0.0.1 or include wepay.com.

Example:

{
  "checkout_id":12345,
  "callback_uri":"https://www.example.com/ipn/12345"
}

Response:

This call will return the same response as the /checkout call.