Upgrade to new version
You are viewing old calls for version 2015-11-18. 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:
Older version?
You can view the older version 2014-01-08 here.
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":649945633
}
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. |
| type | String (255 chars) | The checkout type (one of the following: goods, service, donation, event or personal). |
| 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. |
| callback_uri | String (2083 chars) | The uri which instant payment notifications will be sent to. |
| 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 (3 chars) | The currency used. Possible values: USD, CAD |
| 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. |
| fee | Fee Response Structure | Object that specifies whether an app fee was collected and who (the app or customer) paid for it. |
| gross | Decimal (64 bits) | The total dollar amount paid by the payer. |
| auto_capture | 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. |
| chargeback | Chargeback Structure | Object that specifies amount chargebacked and dispute url. |
| reference_id | String (255 chars) | The unique reference_id passed by the application (if available). |
| refund | Refund Structure | Object that specifies amount refunded and reason for refund. |
| payment_method | Payment Method Structure | Object that specifies the payment method used for the checkout. |
| hosted_checkout | Hosted Checkout Response Structure | Object that specifies checkout_uri, redirect_uri, shipping information, and mode (whether the checkout was displayed in an iframe or not). |
| payer | Payer Structure | Payer information (their name, email, and address) (returned if a payment was made). |
| delivery_type | String | Delivery type for checkout. Possible values: none, fully_delivered, point_of_sale, shipping, donation, subscription, partial_prepayment, full_prepayment. Must be in lower case. |
Example:
{
"checkout_id": 649945633,
"account_id": 1548718026,
"type": "donation",
"short_description": "test",
"currency": "USD",
"amount": 20,
"state": "new",
"soft_descriptor": "WPY*Wolverine",
"auto_capture": true,
"create_time": 1439582388,
"delivery_type": "point_of_sale",
"long_description": "test",
"callback_uri": "http://www.test.com",
"reference_id": null,
"fee": {
"app_fee": 1,
"fee_payer": "payer",
"processing_fee": 0
},
"gross": 0,
"chargeback": {
"amount_charged_back": 0,
"dispute_uri": null
},
"refund": {
"amount_refunded": 0,
"refund_reason": null
},
"hosted_checkout": {
"checkout_uri": "http://wepay.com/api/iframe/649945633/51e59317/api_checkout?iframe=1",
"redirect_uri": "http://www.test.com",
"shipping_fee": 2,
"require_shipping": true,
"shipping_address": null,
"theme_object": {
"theme_id": 96914023,
"name": "test",
"primary_color": "ffffff",
"secondary_color": "000000",
"background_color": "ffffff",
"button_color": "000000"
},
"mode": "iframe"
},
"payer": {
"name": null,
"email": null,
"home_address": null
}
}
/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":1548718026,
"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": 513220415,
"account_id": 1548718026,
"type": "donation",
"short_description": "test payment",
"currency": "USD",
"amount": 20,
"state": "captured",
"soft_descriptor": "WPY*Wolverine",
"auto_capture": true,
"create_time": 1439582902,
"delivery_type": "point_of_sale",
"gross": 23.96,
"long_description": "This is a test payment.",
"reference_id": "123abc",
"callback_uri": "http://www.example.com",
"fee": {
"app_fee": 1,
"fee_payer": "payer",
"processing_fee": 0.96
},
"chargeback": {
"amount_charged_back": 0,
"dispute_uri": "http://wepay.com/dispute/payer_create/148/81bdda6feea880d5d586"
},
"refund": {
"amount_refunded": 0,
"refund_reason": null
},
"hosted_checkout": {
"checkout_uri": "http://wepay.com/api/iframe/513220415/8a8d959e/api_checkout?iframe=1",
"redirect_uri": "http://www.test.com",
"shipping_fee": 2,
"require_shipping": true,
"shipping_address": {
"name": "Test Smith",
"address1": "Main Street",
"address2": "",
"city": "Sunnyvale",
"country": "US",
"state": "CA",
"zip": "94085"
},
"theme_object": {
"theme_id": 21146702,
"name": "test",
"primary_color": "ffffff",
"secondary_color": "000000",
"background_color": "ffffff",
"button_color": "000000"
},
"mode": "iframe"
},
"payer": {
"email": "test@test.com",
"name": "Test Smith",
"home_address": null
}
},
{
"checkout_id": 734762390,
"account_id": 1548718026,
"type": "donation",
"short_description": "test payment",
"currency": "USD",
"amount": 20,
"state": "captured",
"soft_descriptor": "WPY*Vasusen",
"auto_capture": true,
"create_time": 1439335332,
"delivery_type": "shipping",
"gross": 21.9,
"long_description": "This is a test payment.",
"reference_id": "123abc",
"callback_uri": "http://www.example.com",
"fee": {
"app_fee": 1,
"fee_payer": "payer",
"processing_fee": 0.9
},
"chargeback": {
"amount_charged_back": 0,
"dispute_uri": null
},
"refund": {
"amount_refunded": 0,
"refund_reason": null
},
"payment_method": {
"type": "credit_card",
"credit_card": {
"id": 2291714459
}
},
"payer": {
"email": "test@gmail.com",
"name": "test smith",
"home_address": null
}
}
]
/checkout/create
Creates a checkout for an account. There are two ways to have your customers make a payment. You can have the checkout url hosted by WePay or you can use a previously acquired payment method, such as a preapproval or a credit card.
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). Must be in lowercase. |
| amount | Yes | Decimal (64 bits) | The amount that the payer will pay. |
| currency | Yes | String (3 chars) | The currency used. Possible values: USD, CAD |
| long_description | No | String (2047 chars) | A long description of what is being paid for. Max 2047 chars. |
| email_message | No | Email Message Structure | Specifies a short message to send to the payee and payer when a checkout is successful. |
| fee | No | Fee Structure | Specify whether an app fee will be collected and who should pay the app fee. For EMV transactions, this parameter must be present. |
| 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. |
| 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 |
| reference_id | No | String (255 chars) | Partner supplied reference id for this checkout. |
| 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. |
| hosted_checkout | No | Hosted Checkout Structure |
Use this to have payers enter payment information on a WePay hosted checkout URL.
Send either hosted_checkout or payment_method parameter. Do not send both parameters at the same time. If neither parameter is specified, default behavior will be hosted_checkout. |
| payment_method | No | Payment Method Structure |
Use this to pay using previously acquired payment information, such as a
preapproval or a credit card.
Send either hosted_checkout or payment_method parameter. Do not send both parameters at the same time. If neither parameter is specified, default behavior will be hosted_checkout. |
| delivery_type | No | String (255 chars) | Delivery type for checkout. Possible values: none, fully_delivered, point_of_sale, shipping, donation, subscription, partial_prepayment, full_prepayment. Must be in lower case. |
Example:
{
"account_id": 1548718026,
"amount": 20,
"type": "donation",
"currency": "USD",
"short_description": "test payment",
"long_description": "This is a test payment",
"email_message": {
"to_payer": "Please contact us at 555-555-555 if you need assistance.",
"to_payee": "Please note that we cover all shipping costs."
},
"delivery_type": "point_of_sale",
"fee": {
"app_fee": 1,
"fee_payer": "payer"
},
"callback_uri": "http://www.example.com",
"auto_capture": true,
"hosted_checkout": {
"redirect_uri": "http://www.example.com",
"fallback_uri": "http://www.example.com",
"shipping_fee": 2,
"mode": "iframe",
"require_shipping": true,
"prefill_info": {
"address": "main street",
"zip": "94085",
"country": "US"
},
"theme_object": {
"name": "test",
"primary_color": "ffffff",
"background_color": "ffffff",
"button_color": "000000",
"secondary_color": "000000"
},
"funding_sources": ["credit_card"]
}
}
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.