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 only exists for checkouts created in WePay's hosted checkout flow.
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). This state only exists for checkouts created in WePay's hosted checkout flow.

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 2016-08-10

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.
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, and GBP.
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
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 (returned if a payment was made).
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.

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,
   "auto_release": true,
   "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,
   "in_review": false
}

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

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.
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, and GBP.
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
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 (returned if a payment was made).
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.

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

Tip

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 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, and GBP.
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.
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.
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
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).
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
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.

Default: 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, and full_prepayment.

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": "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"]
   },
   "npo_information": null,
   "payment_error": null
}

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.
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, and GBP.
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
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 (returned if a payment was made).
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.

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,
   "auto_release": true,
   "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,
   "in_review": false
}

/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 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

Use this call to refund the payment associated with the checkout created by the application. Checkout must be in released 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 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.

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.
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.
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, and GBP.
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
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 (returned if a payment was made).
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.

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,
   "auto_release": true,
   "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,
   "in_review": false
}

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

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.
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, and GBP.
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
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 (returned if a payment was made).
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.

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,
   "auto_release": true,
   "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,
   "in_review": false
}

/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.
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, and GBP.
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
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 (returned if a payment was made).
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.

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,
   "auto_release": true,
   "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,
   "in_review": false
}