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 2016-05-18 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).

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":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 Response 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.
npo_information Non Profit Information Structure If the payee is a non profit entity, this contains information about non profit organization, null otherwise.
in_review Boolean In case the payment related to this checkout is under risk review, this value is true, false otherwise
payment_error Payment Error Structure If there is an error regarding the payment and we have additional information to pass back, this will contain that information. At present, only Pay With Bank (ACH) transactions may have additional information.

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
  },
  "npo_information":{
	"legal_name": "org name",
	"ein": "343644743"
  },
  "in_review": false,
  "payment_error": 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
    },
    "npo_information": null,
	"in_review": false,
    "payment_error": 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
      },
      "npo_information": null,
	  "in_review": false,
      "payment_error": 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.

  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 like "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.

/checkout/cancel

Cancels the payment associated with the checkout created by the application. Checkout must be in "authorized" or "reserved" state. The /checkout/cancel call cannot be used on Pay With Bank (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 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.