For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
HomeGuidesAPI Reference
HomeGuidesAPI Reference
  • Foundations
    • Introduction
    • Request Headers
    • User-Agent Header
    • Authentication
    • Errors
    • Data Requirements
  • Online API
      • POSTCreate Checkout
      • Express Checkout Payload (Create Checkout)
      • GETGet Checkout
    • Immediate Payment Flow
    • Deferred Payment Flow
  • Upgrading to the Clearpay Express Checkout
    • Express Checkout Overview
    • How to Integrate
    • Security
LogoLogo
Online APICheckouts

Create Checkout

POST
https://global-api-sandbox.afterpay.com/v2/checkouts
POST
/v2/checkouts
$curl -X POST https://global-api-sandbox.afterpay.com/v2/checkouts \
>     -H "User-Agent: User-Agent" \
>     -H "Content-Type: application/json" \
>     -u "<username>:<password>" \
>     -d '{
>  "purchaseCountry": "string",
>  "amount": {
>    "amount": "0.00",
>    "currency": "GBP"
>  },
>  "consumer": {
>    "givenNames": "Joe",
>    "surname": "Consumer",
>    "email": "test@example.com"
>  },
>  "items": [
>    {
>      "name": "string",
>      "quantity": 1
>    }
>  ],
>  "merchantReference": "string"
>}'
1{
2  "token": "002.ejh49ovam0acussgg4c6slpqqtn1ntqt3m4efqdh4qe0u8qk",
3  "expires": "2023-08-29T00:57:25.754Z",
4  "redirectCheckoutUrl": "https://portal.eu-sandbox.afterpay.com/uk/checkout/?token=002.ejh49ovam0acussgg4c6slpqqtn1ntqt3m4efqdh4qe0u8qk"
5}
This endpoint creates a checkout used to start the Clearpay payment process. Clearpay uses the information in the order request to assist with the customer’s pre-approval process. <Note title="Note"> The `popupOriginUrl` is optional if using the `redirectConfirmURL` and is found under the `merchant` object. However, this method is used by most new merchants. You can see how the method is used for [Express Checkout](/express-checkout-payload-create-checkout) and read more about the Popup method under our [Standard Checkout](/standard-checkout) page. </Note> <Note title="Note"> It is not possible to update the checkout information (including `amount`) after the token is generated. If the consumer's cart changes on the merchant side after a token is generated, please discard this token. Use the current checkout information to generate a new checkout token. Use the new token to send the consumer through the Clearpay screenflow before attempting to call [Auth](/deferred-payment-flow/auth) or [Capture Full Payment](/immediate-payment-flow/capture-full-payment). </Note> ## Connection Timeouts | Timeout | Time (Seconds) | | :------ | :------------- | | Open | 10 | | Read | 20 | ## Errors In addition to the [PUT/POST Errors](/put-post-errors) applicable to all POST endpoints, the following errors are specific to Create Checkout: | HTTP Status Code | errorCode | Description | | :-- | :-- | :-- | | **400** <br />Bad Request | `invalid_request` | Invalid request format or missing required fields. | | **422** <br />Unprocessable Entity | `invalid_object` | One or more required fields were missing or invalid. | | **422** <br />Unprocessable Entity | `unsupported_payment_type` | The `amount` is outside of the merchant's payment limits, as returned by [Get Configuration](/api-reference/online-api/configuration/get-configuration). | | **422** <br />Unprocessable Entity | `unsupported_currency` | One or more [Money](/money-object) objects may have contained a currency that differs from the merchant's account currency. |
Was this page helpful?
Previous

Express Checkout Payload (Create Checkout)

Next
Built with

This endpoint creates a checkout used to start the Clearpay payment process. Clearpay uses the information in the order request to assist with the customer’s pre-approval process.

Note

The popupOriginUrl is optional if using the redirectConfirmURL and is found under the merchant object. However, this method is used by most new merchants. You can see how the method is used for Express Checkout and read more about the Popup method under our Standard Checkout page.

Note

It is not possible to update the checkout information (including amount) after the token is generated.

If the consumer’s cart changes on the merchant side after a token is generated, please discard this token. Use the current checkout information to generate a new checkout token. Use the new token to send the consumer through the Clearpay screenflow before attempting to call Auth or Capture Full Payment.

Connection Timeouts

TimeoutTime (Seconds)
Open10
Read20

Errors

In addition to the PUT/POST Errors applicable to all POST endpoints, the following errors are specific to Create Checkout:

HTTP Status CodeerrorCodeDescription
400
Bad Request		invalid_requestInvalid request format or missing required fields.
422
Unprocessable Entity		invalid_objectOne or more required fields were missing or invalid.
422
Unprocessable Entity		unsupported_payment_typeThe amount is outside of the merchant’s payment limits, as returned by Get Configuration.
422
Unprocessable Entity		unsupported_currencyOne or more Money objects may have contained a currency that differs from the merchant’s account currency.

Authentication

AuthorizationBasic

Basic authentication of the form Basic <base64(username:password)>.

Headers

User-AgentstringRequired
AcceptstringOptionalDefaults to application/json

Request

This endpoint expects an object.
purchaseCountrystringRequired
The Merchant's store front country. The two-character [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code. Required for EU Countries.
amountobjectRequired
Total amount for order to be charged to consumer.
consumerobjectRequired

The customer (consumer) requesting the order.

itemslist of objectsRequired
This data model is used to store crucial product details.
merchantReferencestringRequired

The merchant’s id/reference that this order corresponds to.

billingobjectOptional
Billing address.
shippingobjectOptional
Shipping address. Recipient of the goods, not the person making the purchase.
courierobjectOptional
Shipping Courier details.
descriptionstringOptional

Deprecated: A description of the order.

discountslist of objectsOptional
An array of discounts.
merchantobjectOptional
taxAmountobjectOptional
The included tax amount after applying all discounts.
shippingAmountobjectOptional
The shipping amount.
shippingOptionsobjectOptional

The shipping options to be applied if a merchant wishes to support shipping to addresses outside of the Afterpay/Clearpay region the customer belongs to.

Response

Create Checkout Response
tokenstring
The checkout token used to redirect consumers to the Clearpay checkout flow.
expiresstring
The expiration date and time for the checkout token in ISO 8601 format.
redirectCheckoutUrlstring
The URL to redirect consumers to complete the Clearpay checkout process.

Errors

400
Bad Request Error
422
Unprocessable Entity Error

The Merchant’s store front country. The two-character ISO 3166-1 country code. Required for EU Countries.