Upgrade to new version
You are viewing old calls for version 2014-01-08. Please upgrade checkout object calls to the latest version to stay up-to-date.
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).
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. |
| payment_method_id | Integer (64 bits) | The ID of the credit card if tokenization was used. |
| payment_method_type | String (255 chars) | This is set to 'credit_card' if tokenization was used. |
| 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 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. See below for tips on handling errors. |
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.
How to safely handle timeouts on /checkout/create
We highly recommend using unique_id to manage timeouts. The unique_id is used to prevent accidental duplicate calls in the case of an unsuccessful call. If a unique_id is repeated and the /checkout/create call appears to be duplicate (the amount, account_id, and client_id are identical to the prior call), we will return the response of the prior /checkout/create call. Otherwise, we will return an error.
- If your call times out, you can safely call it any number of times with the same unique_id, and we will only process it once.
- If your call receives a 1008 error code and an error message like "there was an unknown error - please contact api@wepay.com for support", the request should be resubmitted with the same unique_id.
- If your call receives any other error, you will need a new unique_id when you fix and resubmit the request.
/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.