Foundations

Clearpay API Introduction

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}