> This page is for version v2 (default). > For other versions, use one of these documentation indexes: > - v2 (default): https://developers.clearpay.co.uk/v-2/llms.txt > - v1: https://developers.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.clearpay.co.uk/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.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 `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. 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 | | :---------------------------- | :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- | | **400** Bad Request | `invalid_request` | Invalid request format or missing required fields. | | **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.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. ## Response ### 201 Create Checkout Response - `token` (string, required) — The checkout token used to redirect consumers to the Clearpay checkout flow. - `expires` (string, required) — The expiration date and time for the checkout token in ISO 8601 format. - `redirectCheckoutUrl` (string, required) — The URL to redirect consumers to complete the Clearpay checkout process. ## Errors ### 400 Bad Request Error Bad Request - Invalid request format or missing required fields - `errorCode` (string, optional) - `errorId` (string, optional) - `message` (string, optional) - `httpStatusCode` (integer, optional) ### 422 Unprocessable Entity Error Unprocessable Entity - Business logic validation errors - `errorCode` (enum, optional) - Allowed values: `invalid_object`, `unsupported_payment_type`, `unsupported_currency` - `errorId` (string, optional) - `message` (string, optional) - `httpStatusCode` (integer, optional) ## 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) — The URL location from which Clearpay is initiated (required for express checkout). Optional for standard checkout when a `redirectConfirmURL` is provided. - `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" } ``` **Response** ```json { "token": "002.ejh49ovam0acussgg4c6slpqqtn1ntqt3m4efqdh4qe0u8qk", "expires": "2023-08-29T00:57:25.754Z", "redirectCheckoutUrl": "https://portal.eu-sandbox.afterpay.com/uk/checkout/?token=002.ejh49ovam0acussgg4c6slpqqtn1ntqt3m4efqdh4qe0u8qk" } ``` **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() ```