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
      • POSTAuth
      • Express Checkout Payload (auth)
      • POSTCapture Payment
      • POSTVoid
  • Upgrading to the Clearpay Express Checkout
    • Express Checkout Overview
    • How to Integrate
    • Security
LogoLogo
Online APIDeferred Payment Flow

Auth

POST
https://global-api-sandbox.afterpay.com/v2/payments/auth
POST
/v2/payments/auth
$curl -X POST https://global-api-sandbox.afterpay.com/v2/payments/auth \
>     -H "User-Agent: User-Agent" \
>     -H "Content-Type: application/json" \
>     -u "<username>:<password>" \
>     -d '{
>  "token": "string"
>}'
This endpoint requests a payment auth, which determines the order approval status. If approved, the auth will have an expiration date and time, which is returned in the events list for the "AUTH_APPROVED" payment event. <Note title="Note"> This operation is [idempotent](/idempotent-requests) based on the `requestId` (if provided), which allows for the safe retry of multiple requests, guaranteeing the payment operation is only performed once. </Note> <Note title="Note"> The consumer's payment plan begins at the time of auth approval. </Note> <Warning title="Beware"> Authorisation expires after 13 days and then the transaction is automatically voided. Voided transactions are frozen and cannot be reopened or changed in any way. In this case your only option is to use the v2/checkouts endpoint to create a new order. </Warning> ## Approved Response (201) If payment is approved by Clearpay, returns a [Payment object](/payment-object) in response, with a `status` of "APPROVED" and a `paymentState` of "AUTH_APPROVED". ## Declined Response (402) If payment is declined by Clearpay, for example, if invalid card details were entered, returns a [Payment object](/payment-object) in response, with a `status` of "DECLINED" and a `paymentState` of "AUTH_DECLINED". Please advise the consumer to contact the Clearpay Customer Service team for more information. ## Connection Timeouts | Timeout | Time (Seconds) | | :------ | :------------- | | Open | 10 | | Read | 70 | ## Errors In addition to the [PUT/POST Errors](/put-post-errors) applicable to all POST endpoints, the following errors are specific to Auth: | HTTP Status Code | errorCode | Description | | :-- | :-- | :-- | | **402** <br />Payment Required | `invalid_token` | The checkout token is invalid, expired, or does not exist. | | **412** <br />Precondition Failed | `invalid_order_transaction_status` | The Consumer has not confirmed their payment for the order associated with this token. | | **422** <br />Unprocessable Entity | `invalid_object` | The checkout token was missing or empty. |
Was this page helpful?
Previous

Express Checkout Payload (Auth)

Next
Built with

This endpoint requests a payment auth, which determines the order approval status. If approved, the auth will have an expiration date and time, which is returned in the events list for the “AUTH_APPROVED” payment event.

Note

This operation is idempotent based on the requestId (if provided), which allows for the safe retry of multiple requests, guaranteeing the payment operation is only performed once.

Note

The consumer’s payment plan begins at the time of auth approval.

Beware

Authorisation expires after 13 days and then the transaction is automatically voided. Voided transactions are frozen and cannot be reopened or changed in any way. In this case your only option is to use the v2/checkouts endpoint to create a new order.

Approved Response (201)

If payment is approved by Clearpay, returns a Payment object in response, with a status of “APPROVED” and a paymentState of “AUTH_APPROVED”.

Declined Response (402)

If payment is declined by Clearpay, for example, if invalid card details were entered, returns a Payment object in response, with a status of “DECLINED” and a paymentState of “AUTH_DECLINED”.

Please advise the consumer to contact the Clearpay Customer Service team for more information.

Connection Timeouts

TimeoutTime (Seconds)
Open10
Read70

Errors

In addition to the PUT/POST Errors applicable to all POST endpoints, the following errors are specific to Auth:

HTTP Status CodeerrorCodeDescription
402
Payment Required		invalid_tokenThe checkout token is invalid, expired, or does not exist.
412
Precondition Failed		invalid_order_transaction_statusThe Consumer has not confirmed their payment for the order associated with this token.
422
Unprocessable Entity		invalid_objectThe checkout token was missing or empty.

Authentication

AuthorizationBasic

Basic authentication of the form Basic <base64(username:password)>.

Headers

User-AgentstringRequired
AcceptstringOptionalDefaults to application/json

Request

This endpoint expects an object.
tokenstringRequired

The token returned in the Create Checkout request.

requestIdstringOptional
A unique request ID, required for idempotent retries. It is recommended that the merchant generate a UUID for each unique request.
merchantReferencestringOptional

The merchant’s order id/reference that this payment corresponds to. This will update any value previously provided in the Create Checkout request.