> This page is for Afterpay Online Developer, version Main (default).
> For other versions, use one of these documentation indexes:
> - Main (default): https://developers.afterpay.com/afterpay-online-developer/main/llms.txt
> - v1: https://developers.afterpay.com/afterpay-online-developer/v-1/llms.txt
> - Chinese: https://developers.afterpay.com/afterpay-online-developer/chinese/llms.txt
> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.afterpay.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.afterpay.com/_mcp/server.
### Schema (`response.body`)
```yaml
openapi: 3.1.0
info:
title: API
version: 1.0.0
paths:
/payment-auth-model-test:
get:
operationId: subpackageModels_get-payment-auth-model-test
summary: Get PaymentAuth Model Test
description: Payment (Auth) schema for authorized payments
tags:
- subpackage_models
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: >-
#/components/schemas/Models_get-payment-auth-model-test_Response_200
tags:
- name: subpackage_models
servers:
- url: https://global-api-sandbox.afterpay.com
description: Sandbox
- url: https://global-api.afterpay.com
description: Production
components:
schemas:
PaymentAuthStatus:
type: string
enum:
- APPROVED
- DECLINED
description: represents the status of the order
title: PaymentAuthStatus
MoneyCurrency:
type: string
enum:
- AUD
- NZD
- USD
- CAD
- GBP
description: >-
The currency in ISO 4217 format. The value provided must correspond to
the currency of the merchant account making the request.
title: MoneyCurrency
Money:
type: object
properties:
amount:
type: string
description: >-
The amount as a string representation of a decimal number, rounded
to 2 decimal places.
currency:
$ref: '#/components/schemas/MoneyCurrency'
description: >-
The currency in ISO 4217 format. The value provided must correspond
to the currency of the merchant account making the request.
required:
- amount
- currency
description: "Object containing amount and currency.\n\nWhere a Money object is included in an API request, it will be validated according to the specification above. Invalid Money objects will trigger a **422 Unprocessable Entity response**. The following is a list of common examples:\n\n|Example|\terrorCode|\tmessage|\n|---|---|---|\n|`amount` is omitted or null\t|invalid_object\t|{Money object}.amount Amount field required|\n|`amount` has more than 2 decimal places\t| invalid_object\tamount| must be a valid ISO 4217 format value|\n|`amount` includes a thousands separator comma, for example: \"1,000\"\t|invalid_amount\t|Amount must be a valid ISO 4217 format value|\n|`amount` is not a decimal number, for example: \"FREE\", \"$2\" or an empty string\t|invalid_object|\t{Money object}.amount Amount field must be a valid ISO 4217 format value|\n|`currency` is omitted or null\t|invalid_object|\t{Money object}.currency Currency field required|\n|`currency` is not a valid currency code, not all uppercase or an empty string\t|invalid_object|\t{Money object}.currency Currency not supported for this merchant|\n|`currency` is supported by Afterpay, but not valid for the Merchant account\t|unsupported_currency\t|An error occurred|"
title: Money
PaymentAuthPaymentState:
type: string
enum:
- AUTH_APPROVED
- AUTH_DECLINED
- PARTIALLY_CAPTURED
- CAPTURED
- CAPTURE_DECLINED
- VOIDED
description: is the current state for capturing payments
title: PaymentAuthPaymentState
Refund:
type: object
properties:
requestId:
type: string
description: Unique ID required for safe retries. Max length 64 (varchar).
amount:
$ref: '#/components/schemas/Money'
merchantReference:
type: string
description: >-
The merchant’s internal refund id/reference. This must be included
along with the `requestId` to utilise idempotency. Max length 85
(varchar).
refundMerchantReference:
type: string
maxLength: 128
description: >-
A unique reference for the individual refund event. Max length 128
(varchar).
refundId:
type: string
description: The unique, permanent, Afterpay-generated Refund ID.
refundedAt:
type: string
description: >
To guarantee safe retries, the merchant should offer their refund ID or
reference, aligning with their internal records
Unique values for the `requestID` and `merchantReference` are required
to guarantee safe retries. It is recommended that the merchant generates
a UUID for each unique refund request.
The `refundMerchantReference` is a unique reference that when provided,
will appear in the daily settlement file as "Payment Event Id". In most
cases, this would hold the same value as the `merchantReference`.
title: Refund
Consumer:
type: object
properties:
email:
type: string
format: email
maxLength: 128
givenNames:
type: string
maxLength: 128
description: The consumer's first name
surname:
type: string
maxLength: 128
description: The consumer's last name
phoneNumber:
type: string
maxLength: 32
required:
- email
description: >-
The consumer data model is used for gathering essential user
information. It captures details such as the individual's first name,
represented by `givenNames`, and their last name, captured under
`surname`. In addition, it stores the user's contact number under
`phoneNumber` and their email address under `email`. These fields
collectively provide indispensable contact and identification details
for a user.
title: Consumer
ContactCountryCode:
type: string
enum:
- AU
- NZ
- US
- CA
- GB
title: ContactCountryCode
Contact:
type: object
properties:
name:
type: string
maxLength: 255
line1:
type: string
maxLength: 128
description: First line of the address
line2:
type: string
maxLength: 128
description: 'Second line of the address '
area1:
type: string
maxLength: 128
description: |-
- AU: Suburb
- NZ: Town or City
- UK: Postal Town
- US: City
- Canada: City
area2:
type: string
maxLength: 128
description: |-
- NZ: suburb
- UK: village or local area.
region:
type: string
maxLength: 128
description: |-
- AU: State
- NZ: Region
- UK: County
- US: State
- CA: Province or Territory
postcode:
type: string
maxLength: 128
countryCode:
$ref: '#/components/schemas/ContactCountryCode'
phoneNumber:
type: string
description: >-
The phone number, in [E.123](https://en.wikipedia.org/wiki/E.123)
format.
required:
- name
- line1
- area1
- region
- postcode
- countryCode
description: >
This data model is used for storing an individual's contact information.
Mandatory fields such as **name**, **line1**, **area1**, **region**,
**postcode**, and **countryCode** help in capturing vital information
about a user's location.
The `line2` and `area2` fields provide additional space for extended
addresses, while `phoneNumber` can be used to store the user's contact
number.
The `area1`, `area2` and `region` properties feature localized terminology based on country. Refer to the property descriptions for insights on each country's specific usage
title: Contact
ShippingCourierPriority:
type: string
enum:
- STANDARD
- EXPRESS
description: The shipping priority.
title: ShippingCourierPriority
Shipping-Courier:
type: object
properties:
shippedAt:
type: string
format: date-time
description: The date and time when the order was shipped, in ISO 8601 format.
name:
type: string
maxLength: 128
description: 'The name of the courier. '
tracking:
type: string
maxLength: 128
description: The tracking number provided by the courier.
priority:
$ref: '#/components/schemas/ShippingCourierPriority'
description: The shipping priority.
description: >-
Essential information for tracking a shipment. The `shippedAt` key
represents the date and time when the item was shipped. This value
follows the ISO 8601 standard format for date and time representations.
The `name` field indicates the courier service employed to handle the
shipment (e.g. FEDEX, UPS). For orders that are picked up in-store (also
known as Buy-Online-Pickup-Instore), please use "INSTORE_PICKUP" as the
`name` field value.
The `tracking` key represents a unique tracking number provided by the
courier service to monitor the shipment's progress. It's a valuable tool
for customers and businesses to track and trace their packages.
The `priority` field tracks the shipping speed or service level
associated with the delivery.
title: Shipping-Courier
Item:
type: object
properties:
name:
type: string
maxLength: 255
description: Product name
sku:
type: string
description: Product SKU. Limited to 128 characters.
pageUrl:
type: string
maxLength: 2048
imageUrl:
type: string
maxLength: 2048
description: >-
A URL for a web-optimized photo of the item, suitable for use
directly as the src attribute of an img tag.
quantity:
type: integer
price:
$ref: '#/components/schemas/Money'
categories:
type: array
items:
type: array
items:
type: string
description: >-
An array of arrays to accommodate multiple categories that apply to
the item. Each array represents a hierarchical path to a category,
with the left-most category being the top-level parent category.
estimatedShipmentDate:
type: string
format: date
description: >-
The estimated date when the order will be shipped, in YYYY-MM or
YYYY-MM-DD format.
preorder:
type: boolean
default: false
description: >-
If this item is not expected to be fulfilled immediately, and
therefore should be marked as a preorder at checkout, set to `true`.
Set to `false` otherwise.
required:
- name
- quantity
- price
description: >
This data model is used to store crucial product details. The
`price.amount` field represents the unit price of the individual item.
The `quantity` field shows the number of units of the item. The `name`
field denotes the name of the product, while `sku` holds the Stock
Keeping Unit identifier. 100 is the maximum number of item objects in
the items array.
It is crucial that the `price.amount` represents the unit price of the individual item.
**Never** populate the `price.amount` by multiplying the quantity by the unit cost. Always enter the price for a single unit to maintain data accuracy.
title: Item
Discount:
type: object
properties:
displayName:
type: string
description: A display name for the discount. Limited to 128 characters.
amount:
$ref: '#/components/schemas/Money'
description: The discount amount.
description: A discount applied to an order.
title: Discount
Order-Details:
type: object
properties:
consumer:
$ref: '#/components/schemas/Consumer'
description: The customer who placed or is placing the order.
billing:
$ref: '#/components/schemas/Contact'
description: The customer's billing address.
courier:
$ref: '#/components/schemas/Shipping-Courier'
description: The customer's chosen shipping courier.
items:
type: array
items:
$ref: '#/components/schemas/Item'
description: An array of order items.
discounts:
type: array
items:
$ref: '#/components/schemas/Discount'
description: An array of discounts.
taxAmount:
$ref: '#/components/schemas/Money'
description: The included tax amount, after applying all discounts.
shippingAmount:
$ref: '#/components/schemas/Money'
description: The shipping price charged to the customer.
description: >-
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.
title: Order-Details
PaymentEventType:
type: string
enum:
- AUTH_APPROVED
- AUTH_DECLINED
- CAPTURED
- CAPTURE_DECLINED
- VOIDED
- EXPIRED
- REVERSED
title: PaymentEventType
Payment-Event:
type: object
properties:
id:
type: string
created:
type: string
expires:
type: string
type:
$ref: '#/components/schemas/PaymentEventType'
amount:
$ref: '#/components/schemas/Money'
paymentEventMerchantReference:
type: string
description: >-
Each payment event has a unique ID, creation timestamp, and type (e.g.,
"AUTH_APPROVED", "AUTH_DECLINED"). For "AUTH_APPROVED" events, an
expiration timestamp is provided. The "payment event merchant reference"
field, which can be used for payment capture events.
title: Payment-Event
BillingAgreementResponseType:
type: string
enum:
- BILLING
description: Type of agreement
title: BillingAgreementResponseType
BillingAgreementResponseStatus:
type: string
enum:
- ACTIVE
- CANCELLED
- EXPIRED
- PENDING_RENEWAL
- PENDING_RENEWAL_EXPIRED
description: Current status of the agreement
title: BillingAgreementResponseStatus
AgreementEventResponseType:
type: string
enum:
- CAPTURE
- VOID
description: Type of event
title: AgreementEventResponseType
AgreementEventResponseStatus:
type: string
enum:
- APPROVED
- DECLINED
description: Status of the agreement at the time of the event
title: AgreementEventResponseStatus
AgreementEventResponse:
type: object
properties:
type:
$ref: '#/components/schemas/AgreementEventResponseType'
description: Type of event
created:
type: string
format: date-time
description: Timestamp when the event occurred
amount:
$ref: '#/components/schemas/Money'
description: Amount associated with the event
status:
$ref: '#/components/schemas/AgreementEventResponseStatus'
description: Status of the agreement at the time of the event
merchantReference:
type:
- string
- 'null'
description: Merchant's reference associated with this event
orderId:
type: number
format: double
description: Order ID associated with this event
description: Response type for agreement events
title: AgreementEventResponse
BillingAgreementResponse:
type: object
properties:
token:
type: string
description: Unique token identifying the agreement
type:
$ref: '#/components/schemas/BillingAgreementResponseType'
description: Type of agreement
status:
$ref: '#/components/schemas/BillingAgreementResponseStatus'
description: Current status of the agreement
merchantReference:
type:
- string
- 'null'
description: Merchant's reference for this agreement
created:
type: string
format: date-time
description: Timestamp when the agreement was created
cancelled:
type: string
format: date-time
description: If present, indicates when the agreement was cancelled
expires:
type: string
format: date-time
description: >-
If present, indicates when the agreement's status will become
EXPIRED, preventing a client from using it to create payments
events:
type: array
items:
$ref: '#/components/schemas/AgreementEventResponse'
description: List of events associated with this agreement
requestId:
type:
- string
- 'null'
description: Unique identifier for the request
consumerReference:
type:
- string
- 'null'
description: Reference identifier for the consumer
email:
type:
- string
- 'null'
description: Masked email address of the consumer
required:
- token
- type
- status
- created
description: Response type for billing agreements
title: BillingAgreementResponse
PaymentAuth:
type: object
properties:
id:
type: string
description: The unique, permanent, Afterpay generated Order ID.
token:
type: string
description: The token obtained from the checkout call
status:
$ref: '#/components/schemas/PaymentAuthStatus'
description: represents the status of the order
created:
type: string
description: ' is the UTC timestamp of when the payment was completed.'
originalAmount:
$ref: '#/components/schemas/Money'
openToCaptureAmount:
$ref: '#/components/schemas/Money'
paymentState:
$ref: '#/components/schemas/PaymentAuthPaymentState'
description: is the current state for capturing payments
merchantReference:
type: string
description: >-
is the merchant's order id/reference that the payment corresponds
to.
refunds:
type: array
items:
$ref: '#/components/schemas/Refund'
orderDetails:
$ref: '#/components/schemas/Order-Details'
events:
type: array
items:
$ref: '#/components/schemas/Payment-Event'
agreements:
type: array
items:
$ref: '#/components/schemas/BillingAgreementResponse'
description: >-
List of billing agreements utilized or created if any (field omitted
if empty)
description: Describes the schema for a (read-only) payment object
title: PaymentAuth
Models_get-payment-auth-model-test_Response_200:
type: object
properties:
payment_auth:
$ref: '#/components/schemas/PaymentAuth'
required:
- payment_auth
title: Models_get-payment-auth-model-test_Response_200
```
**`Example`**
```json Example
{
"id": "300000016189",
"token": "002.6bjbsaowxvfqam2nw4u3xudppheuh4gsuat3n2w3f6t44euzgy",
"status": "APPROVED",
"created": "2024-03-11T20:11:42.487Z",
"originalAmount": {
"amount": "37.00",
"currency": "USD"
},
"openToCaptureAmount": {
"amount": "0.00",
"currency": "USD"
},
"paymentState": "AUTH_APPROVED",
"merchantReference": "updated-k6-reference-utaddnpx",
"refunds": [],
"orderDetails": {
"consumer": {},
"billing": {
"name": "Joe Customer",
"line1": "1004 New Avenue",
"postcode": "94121",
"countrycode": "US",
"phoneNumber": "2120000000"
},
"shipping": {
"name": "Joe Customer",
"line1": "1004 New Avenue",
"postcode": "94121",
"countrycode": "US",
"phoneNumber": "2120000000"
},
"courier": {
"shippedAt": "2024-01-01T08:00:00Z",
"name": "FedEx",
"tracking": "000 000 000 000",
"priority": "STANDARD"
},
"items": {
"name": "Blue Carabiner",
"sku": "12341234",
"quantity": 1,
"price": {
"amount": "40.00",
"currency": "USD"
}
},
"categories": {
"name": "Jeans",
"sku": "123412345",
"quantity": 1,
"price": {
"amount": "20.00",
"currency": "USD"
},
"categories": null
}
},
"discounts": [],
"shippingAmount": {
"amount": "10.00",
"currency": "USD"
},
"taxAmount": {
"amount": "0.00",
"currency": "USD"
},
"events": {
"id": "2dYbLXpOtEPQbg1DT7x9D8R4oCY",
"created": "2024-03-11T20:11:43.897Z",
"expires": null,
"type": "CAPTURED",
"amount": {
"amount": "37.00",
"currency": "USD"
},
"paymentEventMerchantReference": "k6-gsrdqspusf"
}
}
```