> 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.

# Express Checkout Reference Information

## Happy Path Sequence Diagram

The Clearpay Express Checkout will have some similar behaviour across both deferred and integrated shipping. The  sequence diagram below shows a high-level checkout sequence for a customer using the integrated shipping feature.

1. A customer chooses *Checkout with Clearpay Express* from the shopping cart or product.
2. The merchant calls the *Create Order* or *Create Checkout* endpoint, passing an option to enable dynamic pricing in the Express Checkout.
3. The merchant uses the token in combination with the Javascript `afterpay.js` to direct the customer through the Clearpay Express checkout flow using the popup method. See the [Setup](/ec-setup) page.
4. The customer enters Express Checkout and selects the shipping address they want from their existing Clearpay details.
5. Clearpay calls the `onShippingAddressChange()` callback function on the merchant site to retrieve all shipping options and taxes for the chosen address.
6. The customer selects the shipping method and the order total, including the payment schedule, is updated to include the relevant shipping and taxes.
7. The customer confirms their Clearpay order and Clearpay notifies the merchant using the `onComplete()` callback function.
8. The merchant verifies the transaction by fetching the Order from Clearpay and comparing it to their own records.
9. The merchant shows the customer a confirmation page (optional).
10. The customer confirms their order. The merchant calls Clearpay to capture the payment, passing the calculated order amount for verification.

```json
AfterPay.initializeForPopup({
  countryCode: 'AU',
  onCommenceCheckout: function(actions) {
    /* retrieve clearpay token from your server */
    /* then call `actions.resolve(token)` */
  },
  onShippingAddressChange: function (data, actions) {
    /* required for Integrated Shipping  */
    /* address in `data` */
    /* calc options, then call `actions.resolve(options)` */
  },
  onShippingOptionChange: function (data) {
    /* optional - chosen option in `data` */
  },
  onComplete: function (data) {
    /* handle success/failure of checkout */
  },
  target: '#afterpay-express-button',
  buyNow: false,
  pickup: false,
  shippingOptionRequired: true
})
```

> **Note**
>
> Integrated Shipping is enabled by default for Express orders. To disable it, set `shippingoptionRequired` to False.

### Feature Variant Combinations

**InitializeForPopup Only**

addressMode: `ADDRESS_WITH_SHIPPING_OPTIONS` - no widget needed.

This is the default configuration.

Within the Clearpay Checkout flow, the customer can:

* Select a shipping address from within their Clearpay account.
* View shipping options from the merchant and select one.
* Complete the order

The merchant must:

* Listen to the `onShippingAddressChange` and provide the relevant shipping options.

**Recommended:** for orders that need to be shipped to the customer’s address and have up to five simple shipping options

---

addressMode: `PICKUP_FROM_ORDER_ADDRESS` - no widget needed.

Within the Clearpay Checkout flow, the customer can:

* See their pickup address (previously selected on the merchant site), but not change it
* View pickup options from the merchant and select one
* Complete the order

The merchant must:

* Send pickup address when creating an order token

* Listen to the `onShippingAddressChange` and provide the relevant pickup options

**Recommended** for orders picked up at a specific location (e.g. your physical store)

---

addressMode: `SHIP_TO_ORDER_ADDRESS` - no widget needed.

Within the Clearpay Checkout flow, the customer can:

* See their chosen order address from the merchant site (but not change it)

* View shipping options from the merchant and select one\
  Complete the order

The merchant must:

* Send shipping address when creating an order token

* Listen to the `onShippingAddressChange` and provide the relevant shipping options

**Recommended** for orders to be shipped to the customer’s address chosen on your site (before launching Express Checkout). In this case, the address displayed within the Clearpay checkout flow is locked and customers cannot change it.

---

**initializeForPopup or initializeForRedirect**

addressMode: `NO_ADDRESS` - no widget needed.

Within the Clearpay Checkout flow, the customer can:

* Complete the order

Customers cannot do the following actions within the Clearpay checkout flow

* View a shipping or pickup address
* View shipping options from the merchant and select one

**Recommended** for when there is no shipping or pickup needed (eg.digital goods or services).

---

addressMode: `SHIP_TO_ORDER_ADDRESS_WITHOUT_SHIPPING_OPTIONS` - no widget needed.

Within the Clearpay Checkout flow, the customer can:

* See their chosen order address from the merchant site (but not change it)
* Complete the order

Customer cannot do the following actions within the Clearpay checkout flow:

* View shipping options from the merchant and select a shipping option

The merchant must:

* Send the shipping address when creating an order token

**Recommended** for orders that must be shipped to the customer’s address chosen on your site (before launching Express Checkout), and there are no shipping options available for customers to choose from.

---

## Instructions

This section describes the key steps for Integrated Shipping and Deferred Shipping.

### Integrated Shipping

| Setting  | Type  | Address                                      |
| -------- | ----- | -------------------------------------------- |
| Settings | Popup | addressMode: ‘ADDRESS_WITH_SHIPPING_OPTIONS’ |

A full-featured Clearpay Express checkout where the customer makes all their decisions within Clearpay, including the delivery method. When they click **Buy Now**, you capture immediately and show a confirmation page.

Follow these steps:

1. How to use Express Checkout > Creating an Clearpay Order Token.
2. How to use Express Checkout > Showing the Express Checkout button.
3. Features > Integrated Shipping.
4. Features > Buy Now (Immediate capture).
5. How to use Express Checkout > Capturing payment.

### Deferred Shipping

| Setting  | Type               | Address                                       |
| -------- | ------------------ | --------------------------------------------- |
| Settings | Popup, or redirect | addressMode: ADDRESS_WITHOUT_SHIPPING_OPTIONS |

A short Clearpay Express checkout where the customer chooses only an address and payment method before returning to your site to finish their order. On your site they may choose a shipping method and adjust their order.

Follow these steps:

1. How to use Express Checkout > Creating an Clearpay Order Token.
2. How to use Express Checkout > Showing the Express Checkout button.
3. How to use Express Checkout > Finalising the order.
4. Features > Checkout widget.
5. How to use Express Checkout > Capturing payment.