> This page is for Afterpay Online Developer, version Main (default). > For other versions, use one of these documentation indexes: > - Main (default): https://developers.afterpay.com/afterpay-online-developer/main/llms.txt > - v1: https://developers.afterpay.com/afterpay-online-developer/v-1/llms.txt > - Chinese: https://developers.afterpay.com/afterpay-online-developer/chinese/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.afterpay.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.afterpay.com/_mcp/server. # Create Checkout POST https://global-api-sandbox.afterpay.com/v2/checkouts Content-Type: application/json The `checkouts` endpoint is responsible for creating a new checkout and returning the associated checkout token Reference: https://developers.afterpay.com/afterpay-online-developer/api-reference/reference/checkouts/create-checkout-1 ## Authentication - `Authorization` header (basic auth, required) — Basic authentication of the form `Basic `. ## Servers - `https://global-api-sandbox.afterpay.com` (Sandbox, default) - `https://global-api.afterpay.com` (Production) ## Request ### Headers - `Accept` (string, optional, default: application/json) ### Body (application/json) This endpoint expects a Checkout-Request. - `amount` (Money, required) — Object containing amount and currency. Where a Money object is included in an API request, it will be validated according to the specification above. Invalid Money objects will trigger a **422 Unprocessable Entity response**. The following is a list of common examples: | Example | errorCode | message | | ------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------- | | `amount` is omitted or null | invalid\_object | \{Money object}.amount Amount field required | | `amount` has more than 2 decimal places | invalid\_object amount | must be a valid ISO 4217 format value | | `amount` includes a thousands separator comma, for example: "1,000" | invalid\_amount | Amount must be a valid ISO 4217 format value | | `amount` is not a decimal number, for example: "FREE", "\$2" or an empty string | invalid\_object | \{Money object}.amount Amount field must be a valid ISO 4217 format value | | `currency` is omitted or null | invalid\_object | \{Money object}.currency Currency field required | | `currency` is not a valid currency code, not all uppercase or an empty string | invalid\_object | \{Money object}.currency Currency not supported for this merchant | | `currency` is supported by Afterpay, but not valid for the Merchant account | unsupported\_currency | An error occurred | - `consumer` (Consumer, required) — The consumer data model is used for gathering essential user information. It captures details such as the individual's first name, represented by `givenNames`, and their last name, captured under `surname`. In addition, it stores the user's contact number under `phoneNumber` and their email address under `email`. These fields collectively provide indispensable contact and identification details for a user. - `merchantReference` (string, optional) - `billing` (Contact, optional) — This data model is used for storing an individual's contact information. Mandatory fields such as **name**, **line1**, **area1**, **region**, **postcode**, and **countryCode** help in capturing vital information about a user's location. The `line2` and `area2` fields provide additional space for extended addresses, while `phoneNumber` can be used to store the user's contact number. The `area1`, `area2` and `region` properties feature localized terminology based on country. Refer to the property descriptions for insights on each country's specific usage - `shipping` (Contact, optional) — This data model is used for storing an individual's contact information. Mandatory fields such as **name**, **line1**, **area1**, **region**, **postcode**, and **countryCode** help in capturing vital information about a user's location. The `line2` and `area2` fields provide additional space for extended addresses, while `phoneNumber` can be used to store the user's contact number. The `area1`, `area2` and `region` properties feature localized terminology based on country. Refer to the property descriptions for insights on each country's specific usage - `merchant` (CheckoutRequestMerchant, optional) - `items` (list of Item, optional) - `courier` (Shipping-Courier, optional) — Essential information for tracking a shipment. The `shippedAt` key represents the date and time when the item was shipped. This value follows the ISO 8601 standard format for date and time representations. The `name` field indicates the courier service employed to handle the shipment (e.g. FEDEX, UPS). For orders that are picked up in-store (also known as Buy-Online-Pickup-Instore), please use "INSTORE_PICKUP" as the `name` field value. The `tracking` key represents a unique tracking number provided by the courier service to monitor the shipment's progress. It's a valuable tool for customers and businesses to track and trace their packages. The `priority` field tracks the shipping speed or service level associated with the delivery. - `taxAmount` (Money, optional) — Object containing amount and currency. Where a Money object is included in an API request, it will be validated according to the specification above. Invalid Money objects will trigger a **422 Unprocessable Entity response**. The following is a list of common examples: | Example | errorCode | message | | ------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------- | | `amount` is omitted or null | invalid\_object | \{Money object}.amount Amount field required | | `amount` has more than 2 decimal places | invalid\_object amount | must be a valid ISO 4217 format value | | `amount` includes a thousands separator comma, for example: "1,000" | invalid\_amount | Amount must be a valid ISO 4217 format value | | `amount` is not a decimal number, for example: "FREE", "\$2" or an empty string | invalid\_object | \{Money object}.amount Amount field must be a valid ISO 4217 format value | | `currency` is omitted or null | invalid\_object | \{Money object}.currency Currency field required | | `currency` is not a valid currency code, not all uppercase or an empty string | invalid\_object | \{Money object}.currency Currency not supported for this merchant | | `currency` is supported by Afterpay, but not valid for the Merchant account | unsupported\_currency | An error occurred | - `shippingAmount` (Money, optional) — Object containing amount and currency. Where a Money object is included in an API request, it will be validated according to the specification above. Invalid Money objects will trigger a **422 Unprocessable Entity response**. The following is a list of common examples: | Example | errorCode | message | | ------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------- | | `amount` is omitted or null | invalid\_object | \{Money object}.amount Amount field required | | `amount` has more than 2 decimal places | invalid\_object amount | must be a valid ISO 4217 format value | | `amount` includes a thousands separator comma, for example: "1,000" | invalid\_amount | Amount must be a valid ISO 4217 format value | | `amount` is not a decimal number, for example: "FREE", "\$2" or an empty string | invalid\_object | \{Money object}.amount Amount field must be a valid ISO 4217 format value | | `currency` is omitted or null | invalid\_object | \{Money object}.currency Currency field required | | `currency` is not a valid currency code, not all uppercase or an empty string | invalid\_object | \{Money object}.currency Currency not supported for this merchant | | `currency` is supported by Afterpay, but not valid for the Merchant account | unsupported\_currency | An error occurred | - `discounts` (list of Discount, optional) - `agreements` (list of Agreement, optional) — List of agreements - `custom` (CheckoutRequestCustom, optional) — Additional data depending on the goods and services you provide to customers. - `mode` (enum, optional, default: standard) — Must be set to `express` to enable express checkout. - Allowed values: `express`, `standard` - `description` (string, optional, deprecated) ## Response ### 201 Create Checkout Response - `token` (string, optional) - `expires` (string, optional) - `redirectCheckoutUrl` (string, optional) ## Errors ### 400 Bad Request Error Bad Request - `any` ### 422 Unprocessable Entity Error | errorCode | Description | | --- | --- | | invalid_object | One or more required fields were missing or invalid. | | unsupported_payment_type | The `amount` is outside of the merchant's payment limits, as returned by GET Configuration. | | unsupported_currency | Money is not supported by the merchant. | - `any` ## Types ### Money Object containing amount and currency. Where a Money object is included in an API request, it will be validated according to the specification above. Invalid Money objects will trigger a **422 Unprocessable Entity response**. The following is a list of common examples: | Example | errorCode | message | | ------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------- | | `amount` is omitted or null | invalid\_object | \{Money object}.amount Amount field required | | `amount` has more than 2 decimal places | invalid\_object amount | must be a valid ISO 4217 format value | | `amount` includes a thousands separator comma, for example: "1,000" | invalid\_amount | Amount must be a valid ISO 4217 format value | | `amount` is not a decimal number, for example: "FREE", "\$2" or an empty string | invalid\_object | \{Money object}.amount Amount field must be a valid ISO 4217 format value | | `currency` is omitted or null | invalid\_object | \{Money object}.currency Currency field required | | `currency` is not a valid currency code, not all uppercase or an empty string | invalid\_object | \{Money object}.currency Currency not supported for this merchant | | `currency` is supported by Afterpay, but not valid for the Merchant account | unsupported\_currency | An error occurred | - `amount` (string, required) — The amount as a string representation of a decimal number, rounded to 2 decimal places. - `currency` (enum, required) — The currency in ISO 4217 format. The value provided must correspond to the currency of the merchant account making the request. - Allowed values: `AUD`, `NZD`, `USD`, `CAD`, `GBP` ### Consumer The consumer data model is used for gathering essential user information. It captures details such as the individual's first name, represented by `givenNames`, and their last name, captured under `surname`. In addition, it stores the user's contact number under `phoneNumber` and their email address under `email`. These fields collectively provide indispensable contact and identification details for a user. - `email` (string, required) - `givenNames` (string, optional) — The consumer's first name - `surname` (string, optional) — The consumer's last name - `phoneNumber` (string, optional) ### Contact This data model is used for storing an individual's contact information. Mandatory fields such as **name**, **line1**, **area1**, **region**, **postcode**, and **countryCode** help in capturing vital information about a user's location. The `line2` and `area2` fields provide additional space for extended addresses, while `phoneNumber` can be used to store the user's contact number. The `area1`, `area2` and `region` properties feature localized terminology based on country. Refer to the property descriptions for insights on each country's specific usage - `name` (string, required) - `line1` (string, required) — First line of the address - `area1` (string, required) — - AU: Suburb - NZ: Town or City - UK: Postal Town - US: City - Canada: City - `region` (string, required) — - AU: State - NZ: Region - UK: County - US: State - CA: Province or Territory - `postcode` (string, required) - `countryCode` (enum, required) - Allowed values: `AU`, `NZ`, `US`, `CA`, `GB` - `line2` (string, optional) — Second line of the address - `area2` (string, optional) — - NZ: suburb - UK: village or local area. - `phoneNumber` (string, optional) — The phone number, in [E.123](https://en.wikipedia.org/wiki/E.123) format. ### CheckoutRequestMerchant - `redirectConfirmUrl` (string, required) - `redirectCancelUrl` (string, required) - `popupOriginUrl` (string, optional) — The URL location from which Afterpay is initiated (required for express checkout). Optional for standard checkout when a `redirectConfirmURL` is provided. - `name` (string, optional) — The merchant name displayed in the Afterpay checkout flow, confirmation & refund emails, and the consumer portal ### Item This data model is used to store crucial product details. The `price.amount` field represents the unit price of the individual item. The `quantity` field shows the number of units of the item. The `name` field denotes the name of the product, while `sku` holds the Stock Keeping Unit identifier. 100 is the maximum number of item objects in the items array. It is crucial that the `price.amount` represents the unit price of the individual item. **Never** populate the `price.amount` by multiplying the quantity by the unit cost. Always enter the price for a single unit to maintain data accuracy. - `name` (string, required) — Product name - `quantity` (integer, required) - `price` (Money, required) — Object containing amount and currency. Where a Money object is included in an API request, it will be validated according to the specification above. Invalid Money objects will trigger a **422 Unprocessable Entity response**. The following is a list of common examples: | Example | errorCode | message | | ------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------- | | `amount` is omitted or null | invalid\_object | \{Money object}.amount Amount field required | | `amount` has more than 2 decimal places | invalid\_object amount | must be a valid ISO 4217 format value | | `amount` includes a thousands separator comma, for example: "1,000" | invalid\_amount | Amount must be a valid ISO 4217 format value | | `amount` is not a decimal number, for example: "FREE", "\$2" or an empty string | invalid\_object | \{Money object}.amount Amount field must be a valid ISO 4217 format value | | `currency` is omitted or null | invalid\_object | \{Money object}.currency Currency field required | | `currency` is not a valid currency code, not all uppercase or an empty string | invalid\_object | \{Money object}.currency Currency not supported for this merchant | | `currency` is supported by Afterpay, but not valid for the Merchant account | unsupported\_currency | An error occurred | - `sku` (string, optional) — Product SKU. Limited to 128 characters. - `pageUrl` (string, optional) - `imageUrl` (string, optional) — A URL for a web-optimized photo of the item, suitable for use directly as the src attribute of an img tag. - `categories` (list of list of 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. - `preorder` (boolean, optional, default: false) — If this item is not expected to be fulfilled immediately, and therefore should be marked as a preorder at checkout, set to `true`. Set to `false` otherwise. ### Shipping-Courier Essential information for tracking a shipment. The `shippedAt` key represents the date and time when the item was shipped. This value follows the ISO 8601 standard format for date and time representations. The `name` field indicates the courier service employed to handle the shipment (e.g. FEDEX, UPS). For orders that are picked up in-store (also known as Buy-Online-Pickup-Instore), please use "INSTORE_PICKUP" as the `name` field value. The `tracking` key represents a unique tracking number provided by the courier service to monitor the shipment's progress. It's a valuable tool for customers and businesses to track and trace their packages. The `priority` field tracks the shipping speed or service level associated with the delivery. - `shippedAt` (string, optional) — The date and time when the order was shipped, in ISO 8601 format. - `name` (string, optional) — The name of the courier. - `tracking` (string, optional) — The tracking number provided by the courier. - `priority` (enum, optional) — The shipping priority. - Allowed values: `STANDARD`, `EXPRESS` ### Discount A discount applied to an order. - `displayName` (string, optional) — A display name for the discount. Limited to 128 characters. - `amount` (Money, optional) — The discount amount. ### Agreement List of agreements to create at checkout - `type` (enum, required) — The type of agreement. Currently supports "BILLING". - Allowed values: `BILLING` - `merchantReference` (string, optional, nullable) — A merchant-provided reference for the agreement. ### CheckoutRequestCustom Additional data depending on the goods and services you provide to customers. ## Examples **Request** ```json { "amount": { "amount": "100.00", "currency": "AUD" }, "consumer": { "email": "test@example.com", "givenNames": "Joe", "surname": "Consumer", "phoneNumber": "0400 000 000" } } ``` **Response** ```json { "token": "002.ejh49ovam0acussgg4c6slpqqtn1ntqt3m4efqdh4qe0u8qk", "expires": "2023-08-29T00:57:25.754Z", "redirectCheckoutUrl": "https://portal.sandbox.afterpay.com/us/checkout/?token=002.ejh49ovam0acussgg4c6slpqqtn1ntqt3m4efqdh4qe0u8qk" } ``` **SDK Code** ```python Example 1 import requests url = "https://global-api-sandbox.afterpay.com/v2/checkouts" payload = { "amount": { "amount": "100.00", "currency": "AUD" }, "consumer": { "email": "test@example.com", "givenNames": "Joe", "surname": "Consumer", "phoneNumber": "0400 000 000" } } headers = { "User-Agent": "User-Agent" "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, auth=("", "")) print(response.json()) ``` ```javascript Example 1 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: '{"amount":{"amount":"100.00","currency":"AUD"},"consumer":{"email":"test@example.com","givenNames":"Joe","surname":"Consumer","phoneNumber":"0400 000 000"}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Example 1 package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://global-api-sandbox.afterpay.com/v2/checkouts" payload := strings.NewReader("{\n \"amount\": {\n \"amount\": \"100.00\",\n \"currency\": \"AUD\"\n },\n \"consumer\": {\n \"email\": \"test@example.com\",\n \"givenNames\": \"Joe\",\n \"surname\": \"Consumer\",\n \"phoneNumber\": \"0400 000 000\"\n }\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 Example 1 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 \"amount\": {\n \"amount\": \"100.00\",\n \"currency\": \"AUD\"\n },\n \"consumer\": {\n \"email\": \"test@example.com\",\n \"givenNames\": \"Joe\",\n \"surname\": \"Consumer\",\n \"phoneNumber\": \"0400 000 000\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java Example 1 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 \"amount\": {\n \"amount\": \"100.00\",\n \"currency\": \"AUD\"\n },\n \"consumer\": {\n \"email\": \"test@example.com\",\n \"givenNames\": \"Joe\",\n \"surname\": \"Consumer\",\n \"phoneNumber\": \"0400 000 000\"\n }\n}") .asString(); ``` ```php Example 1 request('POST', 'https://global-api-sandbox.afterpay.com/v2/checkouts', [ 'body' => '{ "amount": { "amount": "100.00", "currency": "AUD" }, "consumer": { "email": "test@example.com", "givenNames": "Joe", "surname": "Consumer", "phoneNumber": "0400 000 000" } }', 'headers' => [ 'Content-Type' => 'application/json', 'User-Agent' => 'User-Agent', ], 'auth' => ['', ''], ]); echo $response->getBody(); ``` ```csharp Example 1 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 \"amount\": {\n \"amount\": \"100.00\",\n \"currency\": \"AUD\"\n },\n \"consumer\": {\n \"email\": \"test@example.com\",\n \"givenNames\": \"Joe\",\n \"surname\": \"Consumer\",\n \"phoneNumber\": \"0400 000 000\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Example 1 import Foundation let credentials = Data(":".utf8).base64EncodedString() let headers = [ "User-Agent": "User-Agent", "Authorization": "Basic \(credentials)", "Content-Type": "application/json" ] let parameters = [ "amount": [ "amount": "100.00", "currency": "AUD" ], "consumer": [ "email": "test@example.com", "givenNames": "Joe", "surname": "Consumer", "phoneNumber": "0400 000 000" ] ] 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() ```