Create Checkout | Clearpay Documentation

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.

Warning

The Readme API Simulator includes form elements for both required and optional Body Params. If not populated with values, Readme will send empty strings to the Clearpay Online API. Any optional parameter that is validated against a Model will need to have all of its required sub-params populated with non-empty values.

Therefore, to avoid receiving unexpected “400” responses from Clearpay, please fill out all fields of the simulation form with valid values. This is particularly important for the amount and currency sub-params of the amount, taxAmount and shippingAmount params.

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.

Successful Response (201)

Returns a token, expiry date/time and checkout URL if successful.

Attribute	Type	Description
`token`	string	Checkout token to be used to complete payment.
`expires`	string	The UTC timestamp of when the checkout token will expire, in ISO 8601 format.
`redirectCheckoutUrl`	string	A URL that can be used to redirect the consumer to the Clearpay screenflow directly from the merchant backend. This can be used as an alternative to implementing the JavaScript afterpay.js.

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

Timeout	Time (Seconds)
Open	10
Read	20

Errors

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

HTTP Status Code	errorCode	Description
422 Unprocessable Entity	`invalid_object`	One or more required fields were missing or invalid.
422 Unprocessable Entity	`unsupported_payment_type`	The `amount` is outside of the merchant’s payment limits, as returned by Get Configuration.
422 Unprocessable Entity	`unsupported_currency`	One or more Money objects may have contained a currency that differs from the merchant’s account currency.

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. <Warning title="Warning"> The Readme API Simulator includes form elements for both required and optional Body Params. If not populated with values, Readme will send empty strings to the Clearpay Online API. Any optional parameter that is validated against a Model will need to have all of its required sub-params populated with non-empty values. Therefore, to avoid receiving unexpected "400" responses from Clearpay, please fill out all fields of the simulation form with valid values. This is particularly important for the `amount` and `currency` sub-params of the `amount`, `taxAmount` and `shippingAmount` params. </Warning> <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> ## Successful Response (201) Returns a token, expiry date/time and checkout URL if successful. | Attribute | Type | Description | | :-------------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `token` | string | Checkout token to be used to complete payment. | | `expires` | string | The UTC timestamp of when the checkout token will expire, in [ISO 8601](http://www.iso.org/iso/home/standards/iso8601.htm) format. | | `redirectCheckoutUrl` | string | A URL that can be used to redirect the consumer to the Clearpay screenflow directly from the merchant backend. This can be used as an alternative to implementing the [JavaScript afterpay.js](/javascript-afterpayjs). | <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 | | :-- | :-- | :-- | | **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. |

Authentication

AuthorizationBasic

Basic authentication of the form Basic <username:password>.

Request

This endpoint expects an object.

purchaseCountrystringRequired

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

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.

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.

Warning

Note

Successful Response (201)

Returns a token, expiry date/time and checkout URL if successful.

Attribute	Type	Description
`token`	string	Checkout token to be used to complete payment.
`expires`	string	The UTC timestamp of when the checkout token will expire, in ISO 8601 format.
`redirectCheckoutUrl`	string	A URL that can be used to redirect the consumer to the Clearpay screenflow directly from the merchant backend. This can be used as an alternative to implementing the JavaScript afterpay.js.

Note

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

Connection Timeouts

Timeout	Time (Seconds)
Open	10
Read	20

Errors

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

HTTP Status Code	errorCode	Description
422 Unprocessable Entity	`invalid_object`	One or more required fields were missing or invalid.
422 Unprocessable Entity	`unsupported_payment_type`	The `amount` is outside of the merchant’s payment limits, as returned by Get Configuration.
422 Unprocessable Entity	`unsupported_currency`	One or more Money objects may have contained a currency that differs from the merchant’s account currency.

1	curl -X POST https://global-api-sandbox.afterpay.com/v2/checkouts \
2	-H "User-Agent: User-Agent" \
3	-H "Content-Type: application/json" \
4	-u "<username>:<password>" \
5	-d '{
6	"purchaseCountry": "string",
7	"amount": {
8	"amount": "0.00",
9	"currency": "GBP"
10	},
11	"consumer": {
12	"givenNames": "Joe",
13	"surname": "Consumer",
14	"email": "test@example.com"
15	},
16	"items": [
17	{
18	"name": "string",
19	"quantity": 1
20	}
21	],
22	"merchantReference": "string"
23	}'

Warning

Note

Successful Response (201)

Note

Connection Timeouts

Errors

Authentication

Headers

Request

Warning

Note

Successful Response (201)

Note

Connection Timeouts

Errors