> 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 a Checkout

> Learn how to create a Clearpay checkout and launch the customer payment flow

There are three steps to create a Clearpay checkout:

1. Call [Get Configuration](/api-reference/get-configuration) to retrieve your order limits
2. Call [Create Checkout](/api-reference/create-checkout) to generate a checkout token
3. Launch the Clearpay checkout flow using a redirect or a popup window

| **Action**                                            | **Endpoint**        | **Purpose**                                          |
| ----------------------------------------------------- | ------------------- | ---------------------------------------------------- |
| [Get Configuration](/api-reference/get-configuration) | `/v2/configuration` | Retrieve Clearpay order limits (min/max values).     |
| [Create Checkout](/api-reference/create-checkout)     | `/v2/checkouts`     | Provide order details and generate a checkout token. |

## Retrieve your order limits

Call the [Get Configuration](/api-reference/get-configuration) endpoint to retrieve your minimum and maximum Clearpay order amounts.

We recommend calling this endpoint once a day as part of a scheduled background process, and storing the `minimumAmount` and `maximumAmount` values on your server.

Use these values to determine:

1. The correct [Clearpay Messaging](/clearpay-messaging/getting-started) to show on the Product Detail pages
2. Whether Clearpay should be presented as an available payment method

A request to create a checkout will be declined if the order grand total is less than the minimum or more than the maximum Clearpay amount. To change your minimum and maximum order values, contact Clearpay.

```mermaid
%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'primaryColor': '#FFF',
      'primaryTextColor': '#000',
      'primaryBorderColor': '#000',
      'lineColor': '#000',
      'secondaryColor': '#fff',
      'tertiaryColor': '#fff',
      'noteBkgColor': '#fff',
      'noteBorderColor': '#000'
    }  
  }
}%%
sequenceDiagram
    Merchant Website ->> Clearpay: GET/v2/configuration
    Clearpay -->> Merchant Website: Configuration
```

## Create a checkout

Call the [Create Checkout](/api-reference/create-checkout) endpoint to communicate the order details to Clearpay. Your request should include:

1. Customer information
2. Order details
3. Order total
4. Shipping details
5. Redirect URLs

> **Note**
>
> Clearpay uses the order total value to calculate the installment plan and to assist with the customer's pre-approval process.

Clearpay responds with a token used to identify this checkout.
For example, `002.5lmerr3k945d00c7htvcrdff83q36kp10a247m212fjpa5ju`. This token is used to launch the Clearpay checkout flow using Afterpay.js.

#### Afterpay.js

| **Environment** | **URL**                                           |
| --------------- | ------------------------------------------------- |
| Sandbox         | `https://portal.sandbox.afterpay.com/afterpay.js` |
| Production      | `https://portal.afterpay.com/afterpay.js`         |

```mermaid
%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'primaryColor': '#FFF',
      'primaryTextColor': '#000',
      'primaryBorderColor': '#000',
      'lineColor': '#000',
      'secondaryColor': '#fff',
      'tertiaryColor': '#fff',
      'noteBkgColor': '#fff',
      'noteBorderColor': '#000'
    }  
  }
}%%
sequenceDiagram
    Merchant Website ->> Clearpay: POST/v2/checkouts
    Clearpay -->> Merchant Website: Token
```

## Set up your checkout experience

As part of your integration, decide how customers will complete the Clearpay checkout flow. There are two options:

* **Redirect method:** Customers are redirected from your website to Clearpay to complete their payment. At the end of the Clearpay checkout flow, the customer is redirected back to your website. Most merchants use this method.
* **Popup method:** The Clearpay checkout flow opens in a popup window on top of your site. For windowed applications, your website is dimmed with a semi-transparent overlay. For full-screen applications (such as mobile interfaces), the flow opens in a new tab. At the end of the Clearpay checkout flow, the popup closes.

### Implement the redirect method

To use the redirect method, call the following two JavaScript functions, in order:

1. `Afterpay.initialize`: Prepares the JavaScript to start the Clearpay screenflow in the appropriate geographical region.
   * Accepts an object with a required `countryCode` (use "GB" for United Kingdom)
2. `Afterpay.redirect`: Redirects the customer's browser from your website to Clearpay.
   * Accepts an object with a required `token` (the checkout token returned by the Create Checkout API call)

```js
<html>
<head>
 <script onload="initAfterpay()" src="https://portal.sandbox.afterpay.com/afterpay.js"></script>
</head>
<body>
 <p>Your HTML here</p>
 <script>
 function initAfterpay () {
   Afterpay.initialize({countryCode: "GB"});
   Afterpay.redirect({token: "YOUR_TOKEN"});
 }
 </script>
</body>
</html>
```

If the customer successfully completes the checkout flow, they're returned to your `redirectConfirmUrl` with a checkout token and a `SUCCESS` status appended as HTTP query parameters: `www.merchant-example.com/confirm?&status=SUCCESS&orderToken=002.5lmerr3k945d00c7htvcrdff83q36kp10a247m212fjpa5ju`

If the customer cancels the checkout, they're returned to your `redirectCancelUrl` with a checkout token and a `CANCELLED` status appended as HTTP query parameters: `www.merchant-example.com/confirm?&status=CANCELLED&orderToken=002.5lmerr3k945d00c7htvcrdff83q36kp10a247m212fjpa5ju`

### Implement the popup method

To use the popup method, call the following JavaScript functions, in order:

1. `Afterpay.initialize`: Prepares the JavaScript to start the Clearpay screenflow in the appropriate geographical region.
2. `Afterpay.open`: Opens the Clearpay popup window, launching the checkout flow for the customer.
3. `Afterpay.onComplete`: Defines a callback function. It checks whether the customer successfully completes the checkout flow and handles successful payments and cancellations.
4. `Afterpay.transfer`: Sends the checkout token to Clearpay, finalizing the payment process.

When a customer's payment is complete, Clearpay uses `postMessage` to call a JavaScript method on your front end system.

> **Note**
>
> The popup method doesn't redirect customers to the `redirectConfirmUrl` or `redirectCancelUrl`, but these fields are still required for the Create Checkout call. These fields are used for context on `postMessage`.

```js
<html>
<head>
 <script type="text/javascript" src="https://portal.sandbox.afterpay.com/afterpay.js"></script>
</head>
<body>
 <button id="clearpay-button">
   Pay with Clearpay
 </button>
 <script type="text/javascript">
   document.getElementById("clearpay-button").addEventListener("click", function() {
     Afterpay.initialize({countryCode: "GB"});
     // To avoid triggering browser anti-popup rules, the Afterpay.open()
     // function must be directly called inside the click event listener
     Afterpay.open();
     // If you don't already have a checkout token at this point, you can
     // AJAX to your backend to retrieve one here. The spinning animation
     // will continue until `Afterpay.transfer` is called.
     // If you fail to get a token you can call Afterpay.close()
     Afterpay.onComplete = function(event) {
       if (event.data.status == "SUCCESS") {
         // The customer confirmed the payment schedule.
         // The token is now ready to be captured from your server backend.
       } else {
         // The customer cancelled the payment or closed the popup window.
       }
     }
     Afterpay.transfer({token: "YOUR_TOKEN"});
   });
 </script>
</body>
</html>
```

If the customer successfully completes the checkout flow, Clearpay calls the `onComplete` method on your website. Clearpay passes the checkout token and a `SUCCESS` status as properties of a data object. The popup closes.

If the customer cancels the checkout, Clearpay calls the `onComplete` method on your website. Clearpay passes the checkout token and a `CANCELLED` status as properties of a data object. The popup closes.

> **Note**
>
> At the end of the checkout flow, if the protocol, host, and port of the opening window don't match those provided in Create Checkout, the customer's browser won't dispatch the JavaScript event for security reasons.