The /checkout API calls

The checkout object represents a single payment and defines the amount, the destination account, the application fee, etc. Use the following calls to 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 Instant Payment Notification (IPN) Tutorial for more details):

new The checkout was created by the application. This state typically indicates that checkouts created in WePay's hosted checkout flow are waiting for the payer to submit their information. If a checkout with a tokenized payment method returns in a state of new, treat this as a retry-able (with unique ID) failure and escalate to WePay if the state does not move to authorized
authorized The payer entered their payment info and confirmed the payment on WePay. WePay has successfully charged the card.
captured The payment has been reserved from the payer.
released The payment has been credited to the payee account. Note that the released state may be active although there are active partial refunds or partial chargebacks.
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 expire if they remain in the new state for more than 30 minutes (e.g., they have been abandoned).

Checkout State Diagram

Tip

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.

Version: v2 2019-04-03

POST Endpoint

 https://wepayapi.com/v2/checkout

/checkout

Use this call to lookup the details of a specific checkout on WePay using the checkout_id. Not all response parameters appear in the JSON response: those which do not appear have no associated 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.

Possible values: goods, service, donation, event, and personal.
create_time Integer (64 bits) The Unix timestamp (UTC) when the checkout was created.
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.

Note: This parameter is set based on the name provided in /account.
callback_uri String (2083 chars) The URI to which IPNs are sent.
short_description String (255 chars) A short description of the checkout.
long_description String (2047 chars) A longer, more detailed, description of the checkout (if available).
currency String (3 chars) The currency used.

Possible values: USD, CAD.
amount Decimal (64 bits) The dollar amount of the checkout object (e.g., 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_release Boolean If set to false then the payment will not automatically be released to the account and will be held by WePay in payment state captured. To release funds to the account you must call /checkout/release. If you do not release the funds within 14 days, then the payment will be automatically cancelled or refunded.

Default: true

Note: Permission is only required if auto_release is set to false.
in_review boolean If true the checkout is under review by the WePay risk team.
chargeback Chargeback Response Structure Object that specifies the amount charged back and the dispute URL.
reference_id String (255 chars) The unique ID passed by the application (if available).
refund Refund Response Structure Object that specifies the amount refunded and the reason for refund.
payment_method Payment Method Response Structure Object that specifies the payment method used for the checkout. Note that only one of either payment_method or hosted_checkout may be present.
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). Note that only one of either payment_method or hosted_checkout may be present.
payer Payer Response Structure Payer information: name, email, and home_address. Note that home_address will return as null even if the information was provided, so checkout requests cannot be used to look up billing or shipping information.
delivery_type String (255 chars) Delivery type for checkout.

Possible values: none, fully_delivered, point_of_sale. shipping, donation, subscription, partial_prepayment, and full_prepayment.
npo_information Non Profit Information Structure If the payee is a non profit entity, the structure contains information about non profit organization. Otherwise, this is null.
payment_error Payment Error Structure If there is an error regarding the payment and WePay has additional information to pass back, this will contain that information. At present, only Pay With Bank (ACH) transactions may have additional information.
payment_rbit_ids Array Array of rbit ids associated with the checkout payer.
transaction_rbit_ids Array Array of rbit ids associated with the checkout transaction.
initiated_by Enum Indicates who initiated the checkout. Possible values include:
  • customer
  • merchant
  • none
Note: initiated_by will default to none for all /checkout/create calls. However, if a card is on file initiated_by defaults to customer.

Example

{
    "checkout_id": 649945633,
    "account_id": 1548718026,
    "type": "donation",
    "short_description": "test checkout",
    "currency": "USD",
    "amount": 20,
    "state": "authorized",
    "soft_descriptor": "WPY*Wolverine",
    "auto_release": true,
    "create_time": 1463589958,
    "gross": 20.88,
    "reference_id": null,
    "callback_uri": null,
    "long_description": null,
    "delivery_type": null,
    "initiated_by": "merchant",
    "in_review": false,
    "fee": {
        "app_fee": 0,
        "processing_fee": 0.88,
        "fee_payer": "payer"
    },
    "chargeback": {
        "amount_charged_back": 0,
        "dispute_uri": null
    },
    "refund": {
        "amount_refunded": 0,
        "refund_reason": null
    },
    "payment_method": {
        "type": "credit_card",
        "credit_card": {
            "id": 1684847614,
            "data": {
                "emv_receipt": null,
                "signature_url": null
            },
            "auto_release": false
        }
    },
    "hosted_checkout": null,
    "payer": {
        "email": "test@example.com",
        "name": "Mr Smith",
        "home_address": null
    },
    "npo_information": null,
    "payment_error": null
}

/checkout/find

Use this call to search for checkouts associated with an account. This call returns an array of checkouts associated with account_id. Each element of the array will include the same data as returned from the /checkout call.

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 ID of the checkout (set by the application in /checkout/create).
state No String (255 chars) The current state of the checkout. see the checkout states section, above, for more information.
preapproval_id No Integer (64 bits) The unique ID for the preapproval used to create this checkout.

Note: Useful if you want to look up all the payments for a recurring preapproval (using the auto_recur parameter).
start_time No Integer (64 bits) or String (255 chars) All checkouts after given start time. Can be a Unix timestamp (UTC) or a valid, parseable date-time. If no timezone is included with the parseable datetime, the API will convert your date-time into UTC.
end_time No Integer (64 bits) or String (255 chars) All checkouts before given end time. Can be a Unix timestamp (UTC) or a valid, parseable date-time. If no timezone is included with the parseable datetime, the API will convert your date-time into UTC.
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. Note that these enums must be capitalized.

Default: DESC
shipping_fee No Decimal (64 bits) All checkouts that have the given shipping fee.

Example

{
    "account_id": 1548718026,
    "start": 10,
    "limit": 20,
    "state": "released"
}

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.

Possible values: goods, service, donation, event, and personal.
create_time Integer (64 bits) The Unix timestamp (UTC) when the checkout was created.
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.

Note: This parameter is set based on the name provided in /account.
callback_uri String (2083 chars) The URI to which IPNs are sent.
short_description String (255 chars) A short description of the checkout.
long_description String (2047 chars) A longer, more detailed, description of the checkout (if available).
currency String (3 chars) The currency used.

Possible values: USD, CAD.
amount Decimal (64 bits) The dollar amount of the checkout object (e.g., 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_release Boolean If set to false then the payment will not automatically be released to the account and will be held by WePay in payment state captured. To release funds to the account you must call /checkout/release. If you do not release the funds within 14 days, then the payment will be automatically cancelled or refunded.

Default: true

Note: Permission is only required if auto_release is set to false.
in_review boolean If true the checkout is under review by the WePay risk team.
chargeback Chargeback Response Structure Object that specifies the amount charged back and the dispute URL.
reference_id String (255 chars) The unique ID passed by the application (if available).
refund Refund Response Structure Object that specifies the amount refunded and the reason for refund.
payment_method Payment Method Response Structure Object that specifies the payment method used for the checkout. Note that only one of either payment_method or hosted_checkout may be present.
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). Note that only one of either payment_method or hosted_checkout may be present.
payer Payer Response Structure Payer information: name, email, and home_address. Note that home_address will return as null even if the information was provided, so checkout requests cannot be used to look up billing or shipping information.
delivery_type String (255 chars) Delivery type for checkout.

Possible values: none, fully_delivered, point_of_sale. shipping, donation, subscription, partial_prepayment, and full_prepayment.
npo_information Non Profit Information Structure If the payee is a non profit entity, the structure contains information about non profit organization. Otherwise, this is null.
payment_error Payment Error Structure If there is an error regarding the payment and WePay has additional information to pass back, this will contain that information. At present, only Pay With Bank (ACH) transactions may have additional information.
payment_rbit_ids Array Array of rbit ids associated with the checkout payer.
transaction_rbit_ids Array Array of rbit ids associated with the checkout transaction.
initiated_by Enum Indicates who initiated the checkout. Possible values include:
  • customer
  • merchant
  • none
Note: initiated_by will default to none for all /checkout/create calls. However, if a card is on file initiated_by defaults to customer.

Example

[
    {
        "checkout_id": 817745451,
        "account_id": 1548718026,
        "type": "donation",
        "short_description": "Donation for the Derek Zoolander Center For Children Who Can't Read Good",
        "currency": "USD",
        "amount": 52.34,
        "state": "released",
        "soft_descriptor": "WPY*Foo Bar",
        "create_time": 1475876799,
        "gross": 54.15,
        "reference_id": null,
        "callback_uri": null,
        "long_description": null,
        "delivery_type": null,
        "initiated_by": "none",
        "fee": {
            "app_fee": 0,
            "processing_fee": 1.81,
            "fee_payer": "payer"
        },
        "chargeback": {
            "amount_charged_back": 0,
            "dispute_uri": "http://www.wepay.com/dispute/payer_create/5/81563c38673ed1491a6d"
        },
        "refund": {
            "amount_refunded": 0,
            "refund_reason": null
        },
        "hosted_checkout": {
            "checkout_uri": "http://www.wepay.com/api/checkout/817745451/b54363f3",
            "redirect_uri": null,
            "shipping_fee": 0,
            "require_shipping": false,
            "shipping_address": null,
            "theme_object": null,
            "mode": "regular",
            "auto_capture": true
        },
        "payment_method": null,
        "payer": {
            "email": "hansel@example.com",
            "name": "Hansel McDonald",
            "home_address": null
        },
        "npo_information": null,
        "payment_error": null,
        "in_review": false,
        "auto_release": true
    },
    {
        "checkout_id": 1273451676,
        "account_id": 1548718026,
        "type": "donation",
        "short_description": "Donation for the Derek Zoolander Center For Children Who Can't Read Good",
        "currency": "USD",
        "amount": 100,
        "state": "released",
        "soft_descriptor": "WPY*Foo Bar",
        "create_time": 1475876687,
        "gross": 103.2,
        "reference_id": null,
        "callback_uri": null,
        "long_description": null,
        "delivery_type": null,
        "initiated_by": "none",
        "fee": {
            "app_fee": 0,
            "processing_fee": 3.2,
            "fee_payer": "payer"
        },
        "chargeback": {
            "amount_charged_back": 0,
            "dispute_uri": "http://www.wepay.com/dispute/payer_create/4/bbc241163edbac82a578"
        },
        "refund": {
            "amount_refunded": 0,
            "refund_reason": null
        },
        "hosted_checkout": {
            "checkout_uri": "http://www.wepay.com/api/checkout/1273451676/6843f23f",
            "redirect_uri": null,
            "shipping_fee": 0,
            "require_shipping": false,
            "shipping_address": null,
            "theme_object": null,
            "mode": "regular",
            "auto_capture": true
        },
        "payment_method": null,
        "payer": {
            "email": "derekzoolander@example.com",
            "name": "Derek Zoolander",
            "home_address": null
        },
        "npo_information": null,
        "payment_error": null,
        "in_review": false,
        "auto_release": true
    }
]

/checkout/create

Use this call to create 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. This call will return the same response as the /checkout call.

WePay highly recommends using unique_id to manage timeouts on /checkout/create. 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.

  1. 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.
  2. If your call receives a 1008 error code and an error message (there was an unknown error - please contact api@wepay.com for support), the request should be resubmitted with the same unique_id.
  3. If your call receives any other error, you will need a new unique_id when you fix and resubmit the request.

Read more about the best practices when it comes to Unique Id here.

Tip

Your platform must use a new unique ID if you are retrying with the same credit card ID. However, when a credit card is declined by the card issuer, it goes into a decline state, and should not be retried.

Tip

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

Note

Supplying rbits helps improve your experience and the experience of your users. You may be contractually required to include rbit information in your requests (despite being optional at the API level). Please see our Risk Certification guide.

Arguments

Parameter Required Type Description
account_id Yes Integer (64 bits) The unique ID of the account for which you want to create a checkout.
short_description Yes String (255 chars) A short description of what is being paid for.
type Yes String (255 chars) The checkout type.

Possible values:, goods, service, donation, event, andpersonal.
amount Yes Decimal (64 bits) The nominal amount of the transaction (not including any processing fees or application fees).
currency Yes String (3 chars) The currency used.

Possible values: USD, CAD.
long_description No String (2047 chars) A more detailed description of the purchased goods or services.
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 Specifies whether an app fee will be collected and who should pay the app fee. Note that for EMV (chip type cards) transactions, this parameter must be present. For in-depth information on how to structure your fees, see the Fees section of our Best Practices article.
callback_uri No String (2083 chars) The URI that will receive any instant payment notifications sent. Needs to be a full URI (e.g., https://www.example.com ) and must not be localhost or 127.0.0.1, nor may it include wepay.com.

Note: Your platform may test using ports in staging but ports are not allowed in production.
auto_release No Boolean If set to false then the payment will not automatically be released to the account and will be held by WePay in payment state captured. To release funds to the account you must call /checkout/release. If you do not release the funds within 14 days, then the payment will be automatically cancelled or refunded.

Default: true

Note: Permission is only required if auto_release is set to false.
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).

Note: Your platform must use a new unique ID if you are retrying with the same credit card ID. However, when a credit card is declined by the card issuer, it goes into a decline state, and should not be retried.
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.

Default: hosted_checkout

Note: If your platform is using hosted_checkout, we highly recommend including a fallback_uri so that browsers that don't support 3rd party cookies can still access the checkout.
payment_method No Payment Method Structure Use this to pay with information your platform acquired through preapproval, credit card, payment_bank, or inline_credit_card. Send either hosted_checkout or payment_method parameter. Do not send both parameters at the same time.

Default: hosted_checkout

Note: inline_credit_card requires permission.
delivery_type No String (255 chars) Delivery type for checkout.

Possible values: fully_delivered, point_of_sale, shipping, donation, subscription, partial_prepayment, and full_prepayment.
payer_rbits No Rbit Structure Risk information related to payer.
transaction_rbits No Rbit Structure Risk information related to transaction.
initiated_by No Enum Indicates who initiated the checkout. Possible values include:
  • customer
  • merchant

Defaults to none if no value is provided.

USD 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_release": true,
    "hosted_checkout": {
        "redirect_uri": "http://www.example.com",
        "fallback_uri": "http://www.example.com",
        "shipping_fee": 2,
        "mode": "regular",
        "require_shipping": true,
        "prefill_info": {
            "address1": "666 Main Street",
            "address2": "Ste. 150",
            "city": "Redwood City",
            "postal_code": "94002",
            "country": "US"
        },
        "theme_object": {
            "name": "test",
            "primary_color": "ffffff",
            "background_color": "ffffff",
            "button_color": "000000",
            "secondary_color": "000000"
        },
        "funding_sources": [
            "credit_card"
        ]
    }
}

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.

Possible values: goods, service, donation, event, and personal.
create_time Integer (64 bits) The Unix timestamp (UTC) when the checkout was created.
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.

Note: This parameter is set based on the name provided in /account.
callback_uri String (2083 chars) The URI to which IPNs are sent.
short_description String (255 chars) A short description of the checkout.
long_description String (2047 chars) A longer, more detailed, description of the checkout (if available).
currency String (3 chars) The currency used.

Possible values: USD, CAD.
amount Decimal (64 bits) The dollar amount of the checkout object (e.g., 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_release Boolean If set to false then the payment will not automatically be released to the account and will be held by WePay in payment state captured. To release funds to the account you must call /checkout/release. If you do not release the funds within 14 days, then the payment will be automatically cancelled or refunded.

Default: true

Note: Permission is only required if auto_release is set to false.
in_review boolean If true the checkout is under review by the WePay risk team.
chargeback Chargeback Response Structure Object that specifies the amount charged back and the dispute URL.
reference_id String (255 chars) The unique ID passed by the application (if available).
refund Refund Response Structure Object that specifies the amount refunded and the reason for refund.
payment_method Payment Method Response Structure Object that specifies the payment method used for the checkout. Note that only one of either payment_method or hosted_checkout may be present.
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). Note that only one of either payment_method or hosted_checkout may be present.
payer Payer Response Structure Payer information: name, email, and home_address. Note that home_address will return as null even if the information was provided, so checkout requests cannot be used to look up billing or shipping information.
delivery_type String (255 chars) Delivery type for checkout.

Possible values: none, fully_delivered, point_of_sale. shipping, donation, subscription, partial_prepayment, and full_prepayment.
npo_information Non Profit Information Structure If the payee is a non profit entity, the structure contains information about non profit organization. Otherwise, this is null.
payment_error Payment Error Structure If there is an error regarding the payment and WePay has additional information to pass back, this will contain that information. At present, only Pay With Bank (ACH) transactions may have additional information.
payment_rbit_ids Array Array of rbit ids associated with the checkout payer.
transaction_rbit_ids Array Array of rbit ids associated with the checkout transaction.
initiated_by Enum Indicates who initiated the checkout. Possible values include:
  • customer
  • merchant
  • none
Note: initiated_by will default to none for all /checkout/create calls. However, if a card is on file initiated_by defaults to customer.
transaction_type No Enum Use one of the following enumeration values:
  • recurring - indicates that this transaction is the first in a series (i.e. subscription)
  • card_on_file - indicates that the payment method being used in this transaction will be stored with the payer's login credentials on your platform application and can be used again in the future.
  • none

USD Example

{
    "checkout_id": 649945633,
    "account_id": 1548718026,
    "type": "donation",
    "short_description": "test checkout",
    "currency": "USD",
    "amount": 20,
    "state": "authorized",
    "soft_descriptor": "WPY*Wolverine",
    "auto_release": true,
    "create_time": 1463589958,
    "gross": 20.88,
    "reference_id": null,
    "callback_uri": null,
    "long_description": null,
    "delivery_type": null,
    "initiated_by": "none",
    "in_review": false,
    "fee": {
        "app_fee": 0,
        "processing_fee": 0.88,
        "fee_payer": "payer"
    },
    "chargeback": {
        "amount_charged_back": 0,
        "dispute_uri": null
    },
    "refund": {
        "amount_refunded": 0,
        "refund_reason": null
    },
    "payment_method": {
        "type": "credit_card",
        "credit_card": {
            "id": 1684847614,
            "data": {
                "emv_receipt": null,
                "signature_url": null
            },
            "auto_release": false
        }
    },
    "hosted_checkout": null,
    "payer": {
        "email": "test@example.com",
        "name": "Mr Smith",
        "home_address": null
    },
    "npo_information": null,
    "payment_error": null
}

/checkout/cancel

Use this call to cancel a payment associated with the checkout created by the application. Checkout must be in authorized or captured state. The /checkout/cancel call cannot be used to cancel Pay With Bank (ACH) payments. Please use the /checkout/release call and then the /checkout/refund call to cancel ACH payments.

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 canceled.

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 canceled.
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

Use this call to refund the payment associated with the checkout created by the application. Checkout must be in released state. Learn more about issuing refunds in our Issue a Refund article.

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 for a credit card based payment method was set to false when the checkout was created, you will need to make this call to capture funds. Until you make this call, the credit card will not be charged and if you do not capture the funds within 7 days then the payment will be automatically cancelled. You can only make this call if the checkout is in state authorized.

Read more about delayed and partial capture.

Arguments

Parameter Required Type Description
checkout_id Yes Integer (64 bits) The unique ID of the checkout to be captured.
amounts No Object If using partial capture, use the amounts structure to capture less than the original `amount` and `app_fee` values.
transaction_rbits No Object If using partial capture, send new rbits to reflect the amounts being captured.

Example

{
    "checkout_id": 12345,
    "amounts": {
        "amount": 100,
        "app_fee": 10
    },
    "transaction_rbits": [
        {
            "receive_time": 1367950000,
            "type": "transaction_details",
            "source": "user",
            "properties": {
                "sales_tax_amount": "5",
                "freight_amount": "0",
                "duty_amount": "0",
                "itemized_receipt": {
                    "description": "Website maintenance for 2 hours",
                    "item_price": "100",
                    "quantity": "1",
                    "amount": "100",
                    "currency": "USD",
                    "product_code": "MX1000",
                    "item_commodity_code": "MX1100COM",
                    "tax_amount": "5",
                    "tax_rate": "5",
                    "discount_amount": "0"
                }
            }
        }
    ]
}

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.

Possible values: goods, service, donation, event, and personal.
create_time Integer (64 bits) The Unix timestamp (UTC) when the checkout was created.
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.

Note: This parameter is set based on the name provided in /account.
callback_uri String (2083 chars) The URI to which IPNs are sent.
short_description String (255 chars) A short description of the checkout.
long_description String (2047 chars) A longer, more detailed, description of the checkout (if available).
currency String (3 chars) The currency used.

Possible values: USD, CAD.
amount Decimal (64 bits) The dollar amount of the checkout object (e.g., 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_release Boolean If set to false then the payment will not automatically be released to the account and will be held by WePay in payment state captured. To release funds to the account you must call /checkout/release. If you do not release the funds within 14 days, then the payment will be automatically cancelled or refunded.

Default: true

Note: Permission is only required if auto_release is set to false.
in_review boolean If true the checkout is under review by the WePay risk team.
chargeback Chargeback Response Structure Object that specifies the amount charged back and the dispute URL.
reference_id String (255 chars) The unique ID passed by the application (if available).
refund Refund Response Structure Object that specifies the amount refunded and the reason for refund.
payment_method Payment Method Response Structure Object that specifies the payment method used for the checkout. Note that only one of either payment_method or hosted_checkout may be present.
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). Note that only one of either payment_method or hosted_checkout may be present.
payer Payer Response Structure Payer information: name, email, and home_address. Note that home_address will return as null even if the information was provided, so checkout requests cannot be used to look up billing or shipping information.
delivery_type String (255 chars) Delivery type for checkout.

Possible values: none, fully_delivered, point_of_sale. shipping, donation, subscription, partial_prepayment, and full_prepayment.
npo_information Non Profit Information Structure If the payee is a non profit entity, the structure contains information about non profit organization. Otherwise, this is null.
payment_error Payment Error Structure If there is an error regarding the payment and WePay has additional information to pass back, this will contain that information. At present, only Pay With Bank (ACH) transactions may have additional information.
payment_rbit_ids Array Array of rbit ids associated with the checkout payer.
transaction_rbit_ids Array Array of rbit ids associated with the checkout transaction.
initiated_by Enum Indicates who initiated the checkout. Possible values include:
  • customer
  • merchant
  • none
Note: initiated_by will default to none for all /checkout/create calls. However, if a card is on file initiated_by defaults to customer.

Example

{
    "checkout_id": 649945633,
    "account_id": 1548718026,
    "type": "donation",
    "short_description": "test checkout",
    "currency": "USD",
    "amount": 20,
    "state": "authorized",
    "soft_descriptor": "WPY*Wolverine",
    "auto_release": true,
    "create_time": 1463589958,
    "gross": 20.88,
    "reference_id": null,
    "callback_uri": null,
    "long_description": null,
    "delivery_type": null,
    "initiated_by": "merchant",
    "in_review": false,
    "fee": {
        "app_fee": 0,
        "processing_fee": 0.88,
        "fee_payer": "payer"
    },
    "chargeback": {
        "amount_charged_back": 0,
        "dispute_uri": null
    },
    "refund": {
        "amount_refunded": 0,
        "refund_reason": null
    },
    "payment_method": {
        "type": "credit_card",
        "credit_card": {
            "id": 1684847614,
            "data": {
                "emv_receipt": null,
                "signature_url": null
            },
            "auto_release": false
        }
    },
    "hosted_checkout": null,
    "payer": {
        "email": "test@example.com",
        "name": "Mr Smith",
        "home_address": null
    },
    "npo_information": null,
    "payment_error": null
}

/checkout/modify

Use this call to modify the callback_uri of a checkout. This call will return the same response as the /checkout call.

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.example.com ) and must not be localhost or 127.0.0.1 or include wepay.com.

Note: Your platform may test using ports in staging but ports are not allowed in production.

Example

{
    "checkout_id": 12345,
    "callback_uri": "https://www.example.com/ipn/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.
type String (255 chars) The checkout type.

Possible values: goods, service, donation, event, and personal.
create_time Integer (64 bits) The Unix timestamp (UTC) when the checkout was created.
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.

Note: This parameter is set based on the name provided in /account.
callback_uri String (2083 chars) The URI to which IPNs are sent.
short_description String (255 chars) A short description of the checkout.
long_description String (2047 chars) A longer, more detailed, description of the checkout (if available).
currency String (3 chars) The currency used.

Possible values: USD, CAD.
amount Decimal (64 bits) The dollar amount of the checkout object (e.g., 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_release Boolean If set to false then the payment will not automatically be released to the account and will be held by WePay in payment state captured. To release funds to the account you must call /checkout/release. If you do not release the funds within 14 days, then the payment will be automatically cancelled or refunded.

Default: true

Note: Permission is only required if auto_release is set to false.
in_review boolean If true the checkout is under review by the WePay risk team.
chargeback Chargeback Response Structure Object that specifies the amount charged back and the dispute URL.
reference_id String (255 chars) The unique ID passed by the application (if available).
refund Refund Response Structure Object that specifies the amount refunded and the reason for refund.
payment_method Payment Method Response Structure Object that specifies the payment method used for the checkout. Note that only one of either payment_method or hosted_checkout may be present.
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). Note that only one of either payment_method or hosted_checkout may be present.
payer Payer Response Structure Payer information: name, email, and home_address. Note that home_address will return as null even if the information was provided, so checkout requests cannot be used to look up billing or shipping information.
delivery_type String (255 chars) Delivery type for checkout.

Possible values: none, fully_delivered, point_of_sale. shipping, donation, subscription, partial_prepayment, and full_prepayment.
npo_information Non Profit Information Structure If the payee is a non profit entity, the structure contains information about non profit organization. Otherwise, this is null.
payment_error Payment Error Structure If there is an error regarding the payment and WePay has additional information to pass back, this will contain that information. At present, only Pay With Bank (ACH) transactions may have additional information.
payment_rbit_ids Array Array of rbit ids associated with the checkout payer.
transaction_rbit_ids Array Array of rbit ids associated with the checkout transaction.
initiated_by Enum Indicates who initiated the checkout. Possible values include:
  • customer
  • merchant
  • none
Note: initiated_by will default to none for all /checkout/create calls. However, if a card is on file initiated_by defaults to customer.

Example

{
    "checkout_id": 649945633,
    "account_id": 1548718026,
    "type": "donation",
    "short_description": "test checkout",
    "currency": "USD",
    "amount": 20,
    "state": "authorized",
    "soft_descriptor": "WPY*Wolverine",
    "auto_release": true,
    "create_time": 1463589958,
    "gross": 20.88,
    "reference_id": null,
    "callback_uri": null,
    "long_description": null,
    "delivery_type": null,
    "initiated_by": "merchant",
    "in_review": false,
    "fee": {
        "app_fee": 0,
        "processing_fee": 0.88,
        "fee_payer": "payer"
    },
    "chargeback": {
        "amount_charged_back": 0,
        "dispute_uri": null
    },
    "refund": {
        "amount_refunded": 0,
        "refund_reason": null
    },
    "payment_method": {
        "type": "credit_card",
        "credit_card": {
            "id": 1684847614,
            "data": {
                "emv_receipt": null,
                "signature_url": null
            },
            "auto_release": false
        }
    },
    "hosted_checkout": null,
    "payer": {
        "email": "test@example.com",
        "name": "Mr Smith",
        "home_address": null
    },
    "npo_information": null,
    "payment_error": null
}

/checkout/release

If auto_release 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 release 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 captured.

Arguments

Parameter Required Type Description
checkout_id Yes Integer (64 bits) or String (256 chars) The unique ID of the checkout for which funds are to be released.

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.
type String (255 chars) The checkout type.

Possible values: goods, service, donation, event, and personal.
create_time Integer (64 bits) The Unix timestamp (UTC) when the checkout was created.
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.

Note: This parameter is set based on the name provided in /account.
callback_uri String (2083 chars) The URI to which IPNs are sent.
short_description String (255 chars) A short description of the checkout.
long_description String (2047 chars) A longer, more detailed, description of the checkout (if available).
currency String (3 chars) The currency used.

Possible values: USD, CAD.
amount Decimal (64 bits) The dollar amount of the checkout object (e.g., 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_release Boolean If set to false then the payment will not automatically be released to the account and will be held by WePay in payment state captured. To release funds to the account you must call /checkout/release. If you do not release the funds within 14 days, then the payment will be automatically cancelled or refunded.

Default: true

Note: Permission is only required if auto_release is set to false.
in_review boolean If true the checkout is under review by the WePay risk team.
chargeback Chargeback Response Structure Object that specifies the amount charged back and the dispute URL.
reference_id String (255 chars) The unique ID passed by the application (if available).
refund Refund Response Structure Object that specifies the amount refunded and the reason for refund.
payment_method Payment Method Response Structure Object that specifies the payment method used for the checkout. Note that only one of either payment_method or hosted_checkout may be present.
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). Note that only one of either payment_method or hosted_checkout may be present.
payer Payer Response Structure Payer information: name, email, and home_address. Note that home_address will return as null even if the information was provided, so checkout requests cannot be used to look up billing or shipping information.
delivery_type String (255 chars) Delivery type for checkout.

Possible values: none, fully_delivered, point_of_sale. shipping, donation, subscription, partial_prepayment, and full_prepayment.
npo_information Non Profit Information Structure If the payee is a non profit entity, the structure contains information about non profit organization. Otherwise, this is null.
payment_error Payment Error Structure If there is an error regarding the payment and WePay has additional information to pass back, this will contain that information. At present, only Pay With Bank (ACH) transactions may have additional information.
payment_rbit_ids Array Array of rbit ids associated with the checkout payer.
transaction_rbit_ids Array Array of rbit ids associated with the checkout transaction.
initiated_by Enum Indicates who initiated the checkout. Possible values include:
  • customer
  • merchant
  • none
Note: initiated_by will default to none for all /checkout/create calls. However, if a card is on file initiated_by defaults to customer.

Example

{
    "checkout_id": 649945633,
    "account_id": 1548718026,
    "type": "donation",
    "short_description": "test checkout",
    "currency": "USD",
    "amount": 20,
    "state": "authorized",
    "soft_descriptor": "WPY*Wolverine",
    "auto_release": true,
    "create_time": 1463589958,
    "gross": 20.88,
    "reference_id": null,
    "callback_uri": null,
    "long_description": null,
    "delivery_type": null,
    "initiated_by": "merchant",
    "in_review": false,
    "fee": {
        "app_fee": 0,
        "processing_fee": 0.88,
        "fee_payer": "payer"
    },
    "chargeback": {
        "amount_charged_back": 0,
        "dispute_uri": null
    },
    "refund": {
        "amount_refunded": 0,
        "refund_reason": null
    },
    "payment_method": {
        "type": "credit_card",
        "credit_card": {
            "id": 1684847614,
            "data": {
                "emv_receipt": null,
                "signature_url": null
            },
            "auto_release": false
        }
    },
    "hosted_checkout": null,
    "payer": {
        "email": "test@example.com",
        "name": "Mr Smith",
        "home_address": null
    },
    "npo_information": null,
    "payment_error": null
}