For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
HomeGuidesAPI Reference
HomeGuidesAPI Reference
  • Foundations
    • Introduction
    • Request Headers
    • User-Agent Header
    • Authentication
    • Errors
    • Data Requirements
  • Online API
    • Immediate Payment Flow
    • Deferred Payment Flow
  • Upgrading to the Clearpay Express Checkout
    • Express Checkout Overview
    • How to Integrate
    • Security
LogoLogo
On this page
  • Environments
  • Production
  • Sandbox
  • Pagination
  • Request parameters
  • Response
  • Example request
  • Example response
Foundations

Clearpay API Introduction

Was this page helpful?

Request Headers

Next
Built with

The Clearpay API is organized around REST. The API uses predictable, resource-oriented URLs and uses HTTP status codes to indicate errors.

  • All communication must use TLS 1.2 or higher.
  • The Clearpay API supports idempotency, which guarantees that if a request is retried, the operation is performed only once. This is especially important for partial refunds.
  • API call response times can vary, especially when requests rely on downstream banking networks. All idempotent resources can be safely retried if a timeout occurs.
  • All dates are represented in ISO 8601 format, and are stored and returned in UTC. You can provide dates in UTC (e.g. 2025-01-01T13:25:00Z) or with a time zone offset (e.g. 2025-01-01T23:25:00+00:00 for GMT).
Idempotency Best Practices

Clearpay recommends using UUIDs as requestId values. For most endpoints, requests with the same requestId will return the same response for up to 24 hours. Refund requests are an exception — they support idempotency for longer than 24 hours.

If an idempotent request returns an HTTP 409, it means the original request is still being processed. Retry the request with the same requestId until a different response is returned.

Environments

Production

  • Supported regions: UK, EU
  • Base URL: https://global-api.afterpay.com

Sandbox

  • Supported regions: UK, EU
  • Base URL: https://global-api-sandbox.afterpay.com
Legacy Endpoints

Existing merchants using region-specific endpoints (e.g. https://api.uk.clearpay.co.uk), can continue using them for their current region.

Pagination

The List Payment endpoint supports pagination using the includeNextLink query parameter.

Request parameters

NameTypeDescription
includeNextLinkbooleanReturn a modified pagination object which includes a url to return the next page. The default value is false.

Response

FieldTypeDescription
limitintegerThe number of results that this page was limited to.
totalResultsintegerThe total number of results matching the query. If greater than limit, one or more results were excluded from this page.
nextPageUrlstringA URL to return the next page (empty if there are no more results).
resultsarrayA page of matching results (may be a subset of the total).

Example request

1curl https://global-api-sandbox.afterpay.com/v2/payments?includeNextLink=true \
2  -H 'Authorization: Basic <Base64EncodedCredentials>' \
3  -H 'User-Agent: <MyUserAgent>' \
4  -H 'Accept: application/json'

Example response

1{
2  "totalResults": 210,
3  "limit": 20,
4  "nextPageUrl": "https://global-api-sandbox.afterpay.com/v2/payments?cursor=MjAyMTExMDlUMDUzNTI1LjI1Nlo%3D%3AMDAxLjVuNDhzbm1qNTh0ZzFkZmcwMzR2cGV2ZG1zY2ZiaTllZmVqMzRkMjl1c25mbDVnbg%3D%3D&includeNextLink=true", 
5  "results": [
6    ...
7  ]
8}