> This page is for version v2 (default). > For other versions, use one of these documentation indexes: > - v2 (default): https://developers-beta.clearpay.co.uk/v-2/llms.txt > - v1: https://developers-beta.clearpay.co.uk/v-1/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers-beta.clearpay.co.uk/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers-beta.clearpay.co.uk/_mcp/server. # Create Checkout POST https://global-api-sandbox.afterpay.com/v2/checkouts Content-Type: application/json 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. 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. 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. ## 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). | 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). ## 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** 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](/api-reference/online-api/configuration/get-configuration). | | **422** Unprocessable Entity | `unsupported_currency` | One or more [Money](/money-object) objects may have contained a currency that differs from the merchant's account currency. | Reference: https://developers-beta.clearpay.co.uk/api-reference/create-checkout ## Authentication - `Authorization` header (basic auth, required) — Basic authentication of the form `Basic `. ## Request ### Headers - `Accept` (string, optional, default: application/json) ### Body (application/json) This endpoint expects an object. - `purchaseCountry` (string, required) — 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. - `amount` (V2CheckoutsPostRequestBodyContentApplicationJsonSchemaAmount, required) — Total amount for order to be charged to consumer. - `consumer` (V2CheckoutsPostRequestBodyContentApplicationJsonSchemaConsumer, required) — The customer (consumer) requesting the order. - `items` (list of V2CheckoutsPostRequestBodyContentApplicationJsonSchemaItemsItems, required) — This data model is used to store crucial product details. - `merchantReference` (string, required) — The merchant’s id/reference that this order corresponds to. - `billing` (V2CheckoutsPostRequestBodyContentApplicationJsonSchemaBilling, optional) — Billing address. - `shipping` (V2CheckoutsPostRequestBodyContentApplicationJsonSchemaShipping, optional) — Shipping address. Recipient of the goods, not the person making the purchase. - `courier` (V2CheckoutsPostRequestBodyContentApplicationJsonSchemaCourier, optional) — Shipping Courier details. - `description` (string, optional) — _Deprecated:_ A description of the order. - `discounts` (list of V2CheckoutsPostRequestBodyContentApplicationJsonSchemaDiscountsItems, optional) — An array of discounts. - `merchant` (V2CheckoutsPostRequestBodyContentApplicationJsonSchemaMerchant, optional) - `taxAmount` (V2CheckoutsPostRequestBodyContentApplicationJsonSchemaTaxAmount, optional) — The included tax amount after applying all discounts. - `shippingAmount` (V2CheckoutsPostRequestBodyContentApplicationJsonSchemaShippingAmount, optional) — The shipping amount. - `shippingOptions` (V2CheckoutsPostRequestBodyContentApplicationJsonSchemaShippingOptions, optional) — 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. ## Types ### V2CheckoutsPostRequestBodyContentApplicationJsonSchemaAmount Total amount for order to be charged to consumer. - `amount` (string, required, default: 0.00) — The amount as a string representation of a decimal number, rounded to 2 decimal places. - `currency` (string, required, default: GBP) — The currency in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. ### V2CheckoutsPostRequestBodyContentApplicationJsonSchemaConsumer The customer (consumer) requesting the order. - `givenNames` (string, required, default: Joe) — The consumer’s first name and any middle names. Limited to 128 characters. - `surname` (string, required, default: Consumer) — The consumer’s last name. Limited to 128 characters. - `email` (string, required, default: test@example.com) — The consumer’s email address. Limited to 128 characters. - `phoneNumber` (string, optional) — The consumer’s phone number. Limited to 32 characters. ### V2CheckoutsPostRequestBodyContentApplicationJsonSchemaItemsItems - `name` (string, required) — Product name. Limited to 255 characters. - `quantity` (integer, required) — The quantity of the item, stored as a signed 32-bit integer. - `sku` (string, optional) — Product SKU. Limited to 128 characters. - `pageUrl` (string, optional) — The canonical URL for the item's Product Detail Page. Limited to 2048 characters. - `imageUrl` (string, optional) — A URL for a web-optimised photo of the item, suitable for use directly as the `src` attribute of an `img` tag. Limited to 2048 characters. - `price` (V2CheckoutsPostRequestBodyContentApplicationJsonSchemaItemsItemsPrice, optional) — The unit price of the individual item. Must be a positive value. - `categories` (string, optional) — An array of arrays to accommodate multiple categories that apply to the item. Each array represents a hierarchical path to a category, with the left-most category being the top-level parent category. - `estimatedShipmentDate` (string, optional) — The estimated date when the order will be shipped, in `YYYY-MM` or `YYYY-MM-DD` format. ### V2CheckoutsPostRequestBodyContentApplicationJsonSchemaBilling Billing address. - `name` (string, required, default: Joe Consumer) — Full name of contact. Limited to 255 characters. - `line1` (string, required, default: 123 Fake Street) — First line of the address. Limited to 128 characters. - `area1` (string, required) — UK postal town or EU Suburb or Town. Limited to 128 characters. - `region` (string, required) — UK county, EU region. Limited to 128 characters. - `postcode` (string, required, default: AA99 9AA) — [Postal code](https://en.wikipedia.org/wiki/Postal_code). Limited to 128 characters. - `countryCode` (string, required, default: GB) — The two-character [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code. - `line2` (string, optional) — Second line of the address. Limited to 128 characters. - `area2` (string, optional) — UK village or local area, EU Province. Limited to 128 characters. - `phoneNumber` (string, optional) — The phone number, in [E.123](https://en.wikipedia.org/wiki/E.123) format. Limited to 32 characters. ### V2CheckoutsPostRequestBodyContentApplicationJsonSchemaShipping Shipping address. Recipient of the goods, not the person making the purchase. - `name` (string, required, default: Joe Consumer) — Full name of contact. Limited to 255 characters. - `line1` (string, required, default: 123 Fake Street) — First line of the address. Limited to 128 characters. - `area1` (string, required) — UK postal town or EU Suburb or Town. Limited to 128 characters. - `region` (string, required) — UK county, EU region. Limited to 128 characters. - `postcode` (string, required, default: AA99 9AA) — [Postal code](https://en.wikipedia.org/wiki/Postal_code). Limited to 128 characters. - `countryCode` (string, required, default: GB) — The two-character [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code. - `line2` (string, optional) — Second line of the address. Limited to 128 characters. - `area2` (string, optional) — UK village or local area, EU Province. Limited to 128 characters. - `phoneNumber` (string, optional) — The phone number, in [E.123](https://en.wikipedia.org/wiki/E.123) format. Limited to 32 characters. ### V2CheckoutsPostRequestBodyContentApplicationJsonSchemaCourier Shipping Courier details. - `shippedAt` (string, optional) — The time at which the order was shipped, in [ISO 8601](http://www.iso.org/iso/home/standards/iso8601.htm) format. - `name` (string, optional) — The name of the courier. Limited to 128 characters. - `tracking` (string, optional) — The tracking number provided by the courier. Limited to 128 characters. - `priority` (string, optional) — The shipping priority. If provided, must be either "STANDARD" or "EXPRESS". ### V2CheckoutsPostRequestBodyContentApplicationJsonSchemaDiscountsItems - `displayName` (string, required) — A display name for the discount. Limited to 128 characters. - `amount` (V2CheckoutsPostRequestBodyContentApplicationJsonSchemaDiscountsItemsAmount, optional) — The discount amount. ### V2CheckoutsPostRequestBodyContentApplicationJsonSchemaMerchant - `redirectConfirmUrl` (string, required, default: https://example.com/checkout/confirm) — The consumer is redirected to this URL on confirmation. - `redirectCancelUrl` (string, required, default: https://example.com/checkout/cancel) — The consumer to redirected to this URL if the payment process is cancelled. - `popupOriginUrl` (string, optional, default: https://example.com/cart) — Optional: if the redirectConfirmURL is there. Unlike standard checkout, only amount, merchant, and mode are required for the Create Checkout API call. - `name` (string, optional) — The merchant name displayed in the Clearpay checkout flow, confirmation & refund emails, and the consumer portal ### V2CheckoutsPostRequestBodyContentApplicationJsonSchemaTaxAmount The included tax amount after applying all discounts. - `amount` (string, required, default: 0.00) — The amount as a string representation of a decimal number, rounded to 2 decimal places. - `currency` (string, required, default: GBP) — The currency in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. ### V2CheckoutsPostRequestBodyContentApplicationJsonSchemaShippingAmount The shipping amount. - `amount` (string, required, default: 0.00) — The amount as a string representation of a decimal number, rounded to 2 decimal places. - `currency` (string, required, default: GBP) — The currency in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. ### V2CheckoutsPostRequestBodyContentApplicationJsonSchemaShippingOptions 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. - `shippingCountry` (string, optional) — Default shipping country in ISO 3166-1 country code. Limited to 2 characters - `supportedShippingCountries` (string, optional) — An array of supported shipping address countries (in ISO 3166-1 alpha-2 country code format) ### V2CheckoutsPostRequestBodyContentApplicationJsonSchemaItemsItemsPrice The unit price of the individual item. Must be a positive value. - `amount` (string, required, default: 0.00) — The amount as a string representation of a decimal number, rounded to 2 decimal places. - `currency` (string, required, default: GBP) — The currency in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. ### V2CheckoutsPostRequestBodyContentApplicationJsonSchemaDiscountsItemsAmount The discount amount. - `amount` (string, required, default: 0.00) — The amount as a string representation of a decimal number, rounded to 2 decimal places. - `currency` (string, required, default: GBP) — The currency in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. ## Examples **Request** ```json { "purchaseCountry": "string", "amount": { "amount": "0.00", "currency": "GBP" }, "consumer": { "givenNames": "Joe", "surname": "Consumer", "email": "test@example.com" }, "items": [ { "name": "string", "quantity": 1 } ], "merchantReference": "string" } ``` **SDK Code** ```python import requests url = "https://global-api-sandbox.afterpay.com/v2/checkouts" payload = { "purchaseCountry": "string", "amount": { "amount": "0.00", "currency": "GBP" }, "consumer": { "givenNames": "Joe", "surname": "Consumer", "email": "test@example.com" }, "items": [ { "name": "string", "quantity": 1 } ], "merchantReference": "string" } headers = { "User-Agent": "User-Agent" "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, auth=("", "")) print(response.json()) ``` ```javascript const url = 'https://global-api-sandbox.afterpay.com/v2/checkouts'; const credentials = btoa(":"); const options = { method: 'POST', headers: { 'User-Agent': 'User-Agent', Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json' }, body: '{"purchaseCountry":"string","amount":{"amount":"0.00","currency":"GBP"},"consumer":{"givenNames":"Joe","surname":"Consumer","email":"test@example.com"},"items":[{"name":"string","quantity":1}],"merchantReference":"string"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://global-api-sandbox.afterpay.com/v2/checkouts" payload := strings.NewReader("{\n \"purchaseCountry\": \"string\",\n \"amount\": {\n \"amount\": \"0.00\",\n \"currency\": \"GBP\"\n },\n \"consumer\": {\n \"givenNames\": \"Joe\",\n \"surname\": \"Consumer\",\n \"email\": \"test@example.com\"\n },\n \"items\": [\n {\n \"name\": \"string\",\n \"quantity\": 1\n }\n ],\n \"merchantReference\": \"string\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("User-Agent", "User-Agent") req.SetBasicAuth("", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://global-api-sandbox.afterpay.com/v2/checkouts") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["User-Agent"] = 'User-Agent' request.basic_auth("", "") request["Content-Type"] = 'application/json' request.body = "{\n \"purchaseCountry\": \"string\",\n \"amount\": {\n \"amount\": \"0.00\",\n \"currency\": \"GBP\"\n },\n \"consumer\": {\n \"givenNames\": \"Joe\",\n \"surname\": \"Consumer\",\n \"email\": \"test@example.com\"\n },\n \"items\": [\n {\n \"name\": \"string\",\n \"quantity\": 1\n }\n ],\n \"merchantReference\": \"string\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/checkouts") .header("User-Agent", "User-Agent") .basicAuth("", "") .header("Content-Type", "application/json") .body("{\n \"purchaseCountry\": \"string\",\n \"amount\": {\n \"amount\": \"0.00\",\n \"currency\": \"GBP\"\n },\n \"consumer\": {\n \"givenNames\": \"Joe\",\n \"surname\": \"Consumer\",\n \"email\": \"test@example.com\"\n },\n \"items\": [\n {\n \"name\": \"string\",\n \"quantity\": 1\n }\n ],\n \"merchantReference\": \"string\"\n}") .asString(); ``` ```php request('POST', 'https://global-api-sandbox.afterpay.com/v2/checkouts', [ 'body' => '{ "purchaseCountry": "string", "amount": { "amount": "0.00", "currency": "GBP" }, "consumer": { "givenNames": "Joe", "surname": "Consumer", "email": "test@example.com" }, "items": [ { "name": "string", "quantity": 1 } ], "merchantReference": "string" }', 'headers' => [ 'Content-Type' => 'application/json', 'User-Agent' => 'User-Agent', ], 'auth' => ['', ''], ]); echo $response->getBody(); ``` ```csharp using RestSharp; using RestSharp.Authenticators; var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/checkouts"); client.Authenticator = new HttpBasicAuthenticator("", ""); var request = new RestRequest(Method.POST); request.AddHeader("User-Agent", "User-Agent"); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"purchaseCountry\": \"string\",\n \"amount\": {\n \"amount\": \"0.00\",\n \"currency\": \"GBP\"\n },\n \"consumer\": {\n \"givenNames\": \"Joe\",\n \"surname\": \"Consumer\",\n \"email\": \"test@example.com\"\n },\n \"items\": [\n {\n \"name\": \"string\",\n \"quantity\": 1\n }\n ],\n \"merchantReference\": \"string\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let credentials = Data(":".utf8).base64EncodedString() let headers = [ "User-Agent": "User-Agent", "Authorization": "Basic \(credentials)", "Content-Type": "application/json" ] let parameters = [ "purchaseCountry": "string", "amount": [ "amount": "0.00", "currency": "GBP" ], "consumer": [ "givenNames": "Joe", "surname": "Consumer", "email": "test@example.com" ], "items": [ [ "name": "string", "quantity": 1 ] ], "merchantReference": "string" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/checkouts")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```