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.
GuidesAPI Reference
GuidesAPI Reference
  • Reference
    • Introduction
      • GETList Payments
      • POSTAuth
      • POSTCapture Full Payment
      • GETGet Payment By Order ID
      • PUTUpdate Payment by Order ID
      • POSTCapture Payment
      • PUTUpdate Shipping Courier
      • POSTCreate Refund
      • POSTVoid
      • GETGet Payment By Token
      • POSTReverse Payment By Token
LogoLogo
ReferencePayments

Auth

POST
/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": "005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2",
>  "requestid": "d22f5305-05f3-48a0-9131-a4e6e5f58b9a",
>  "merchantReference": "merchant-order-123",
>  "amount": {
>    "amount": "100.00",
>    "currency": "AUD"
>  },
>  "isCheckoutAdjusted": true,
>  "paymentScheduleChecksum": "string",
>  "items": [
>    null
>  ],
>  "shipping": {
>    "name": "Joe Consumer",
>    "line1": "Level 5",
>    "area1": "Melbourne",
>    "region": "VIC",
>    "postcode": "3000",
>    "countryCode": "AU",
>    "line2": "390 Collins Street",
>    "phoneNumber": "0400 000 000"
>  },
>  "enrichments": {
>    "initiation": {
>      "actor": "MERCHANT"
>    }
>  }
>}'
1{
2  "id": "300000016189",
3  "token": "002.6bjbsaowxvfqam2nw4u3xudppheuh4gsuat3n2w3f6t44euzgy",
4  "status": "APPROVED",
5  "created": "2024-03-11T20:11:42.487Z",
6  "originalAmount": {
7    "amount": "37.00",
8    "currency": "USD"
9  },
10  "openToCaptureAmount": {
11    "amount": "0.00",
12    "currency": "USD"
13  },
14  "paymentState": "AUTH_APPROVED",
15  "merchantReference": "updated-k6-reference-utaddnpx",
16  "refunds": [],
17  "orderDetails": {
18    "consumer": {
19      "email": "test@example.com"
20    },
21    "billing": {
22      "name": "Joe Customer",
23      "line1": "1004 New Avenue",
24      "area1": "Melbourne",
25      "region": "VIC",
26      "postcode": "94121",
27      "countryCode": "AU",
28      "phoneNumber": "2120000000",
29      "countrycode": "US"
30    },
31    "courier": {
32      "shippedAt": "2024-01-01T08:00:00Z",
33      "name": "FedEx",
34      "tracking": "000 000 000 000",
35      "priority": "STANDARD"
36    },
37    "items": [
38      {
39        "name": "Blue Carabiner",
40        "quantity": 1,
41        "price": {
42          "amount": "40.00",
43          "currency": "USD"
44        },
45        "sku": "12341234"
46      }
47    ],
48    "shipping": {
49      "name": "Joe Customer",
50      "line1": "1004 New Avenue",
51      "postcode": "94121",
52      "countrycode": "US",
53      "phoneNumber": "2120000000"
54    },
55    "categories": {
56      "name": "Jeans",
57      "sku": "123412345",
58      "quantity": 1,
59      "price": {
60        "amount": "20.00",
61        "currency": "USD"
62      },
63      "categories": null
64    }
65  },
66  "events": [
67    {
68      "id": "2dYbLXpOtEPQbg1DT7x9D8R4oCY",
69      "created": "2024-03-11T20:11:43.897Z",
70      "expires": {},
71      "type": "CAPTURED",
72      "amount": {
73        "amount": "37.00",
74        "currency": "USD"
75      },
76      "paymentEventMerchantReference": "k6-gsrdqspusf"
77    }
78  ],
79  "discounts": [],
80  "shippingAmount": {
81    "amount": "10.00",
82    "currency": "USD"
83  },
84  "taxAmount": {
85    "amount": "0.00",
86    "currency": "USD"
87  }
88}
This endpoint requests a payment auth, which determines the order approval status. If approved, the auth has an expiration date and time, which is returned in the events list for the "AUTH_APPROVED" payment event. Authorization expires after 13 days. 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 made once. The customer's payment plan starts at the time of auth approval. **Note:** Authorization 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, use the `v2/checkouts` endpoint to create a new order. **Connection Timeouts** | Timeout | Time (Seconds) | |---------|----------------| | Open | 10 | | Read | 70 |
Was this page helpful?
Previous

Capture Full Payment

Next
Built with

This endpoint requests a payment auth, which determines the order approval status. If approved, the auth has an expiration date and time, which is returned in the events list for the “AUTH_APPROVED” payment event. Authorization expires after 13 days.

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

The customer’s payment plan starts at the time of auth approval.

Note: Authorization 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, use the v2/checkouts endpoint to create a new order.

Connection Timeouts

TimeoutTime (Seconds)
Open10
Read70

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
requestidstringOptionalformat: "uuid"

A unique request ID, required for idempotent retries. We recommend that merchants generate a Universally Unique Identifier (UUID) for each unique request.

merchantReferencestringOptional

The reference/order ID that this payment corresponds to in the merchant’s system.

Note: Providing a new value updates any value previously set in the Create Checkout request.

amountobjectOptional

Required for express checkout only. Amount to be checked against the value in the create checkout request. If the amounts do not match, then the request is rejected and an error specific to this scenario is returned.

isCheckoutAdjustedbooleanOptional

Express checkout only. The isCheckoutAdjusted field can be used to allow the order amount to be changed after the checkout flow. Used for express checkout.

paymentScheduleChecksumstringOptional

Express checkout only. A unique value representing the payment schedule that must be provided when there has been changes since the initial order creation (retrieved from checkout widget).

itemslist of anyOptional

Express checkout only. An array of order items that have been updated to be provided if it has changed since the initial order creation.

shippingobjectOptional

Express checkout only. The shipping address if it has changed since the initial order creation.

enrichmentsobjectOptional
grantIdstringOptional

The Afterpay or Cash App Pay on-file grant ID. Required when processing a payment using a previously stored on-file grant.

Response

If the payment is approved by Afterpay, a Payment object is returned with a status of APPROVED and a paymentState of AUTH_APPROVED.

idstring
The unique, permanent, Afterpay generated Order ID.
tokenstring
The token obtained from the checkout call
statusenum
represents the status of the order
Allowed values:
createdstring
is the UTC timestamp of when the payment was completed.
originalAmountobject
Object containing amount and currency
openToCaptureAmountobject
Object containing amount and currency
paymentStateenumRead-only
is the current state for capturing payments
merchantReferencestring

is the merchant’s order id/reference that the payment corresponds to.

refundslist of objects
orderDetailsobject
This comprehensive schema is designed to store an entire transaction's detail, covering crucial aspects like consumer information, billing and shipping details, courier particulars, item list, discounts, tax, and shipping amount.
eventslist of objects

Errors

402
Payment Required Error
412
Precondition Failed Error
422
Unprocessable Entity Error