Auth | Welcome to Afterpay Documentation

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.

The consumer’s payment plan will begin 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 your only option is to use the v2/checkouts endpoint to create a new order.

Connection Timeouts

Timeout	Time (Seconds)
Open	10
Read	70

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 performed once. The consumer's payment plan will begin 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 your only option is to use the v2/checkouts endpoint to create a new order. **Connection Timeouts** | Timeout | Time (Seconds) | |---------|----------------| | Open | 10 | | Read | 70 |

Authentication

AuthorizationBasic

Basic authentication of the form Basic <username:password>.

Request

This endpoint expects an object.

tokenstringRequired

requestidstringOptionalformat: "uuid"

A unique request ID, required for idempotent retries. It is recommended that the merchant generate a 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 will update 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.

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

Additional enrichment data for the payment.

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 or null

The unique, permanent, Afterpay generated Order ID.

tokenstring or null

The token obtained from the checkout call

statusenum or null

represents the status of the order

Allowed values:

createdstring or null

is the UTC timestamp of when the payment was completed.

originalAmountobject or null

Object containing amount and currency.

Where 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:

Example	errorCode	message
`amount` is omitted or null	invalid_object	{Money object}.amount Amount field required
`amount` has more than 2 decimal places	invalid_object amount	must be a valid ISO 4217 format value
`amount` includes a thousands separator comma, for example: “1,000”	invalid_amount	Amount must be a valid ISO 4217 format value
`amount` is not a decimal number, for example: “FREE”, “$2” or an empty string	invalid_object	{Money object}.amount Amount field must be a valid ISO 4217 format value
`currency` is omitted or null	invalid_object	{Money object}.currency Currency field required
`currency` is not a valid currency code, not all uppercase or an empty string	invalid_object	{Money object}.currency Currency not supported for this merchant
`currency` is supported by Afterpay, but not valid for the Merchant account	unsupported_currency	An error occurred

Object containing amount and currency. Where 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: |Example| errorCode| message| |---|---|---| |`amount` is omitted or null |invalid_object |{Money object}.amount Amount field required| |`amount` has more than 2 decimal places | invalid_object amount| must be a valid ISO 4217 format value| |`amount` includes a thousands separator comma, for example: "1,000" |invalid_amount |Amount must be a valid ISO 4217 format value| |`amount` is not a decimal number, for example: "FREE", "$2" or an empty string |invalid_object| {Money object}.amount Amount field must be a valid ISO 4217 format value| |`currency` is omitted or null |invalid_object| {Money object}.currency Currency field required| |`currency` is not a valid currency code, not all uppercase or an empty string |invalid_object| {Money object}.currency Currency not supported for this merchant| |`currency` is supported by Afterpay, but not valid for the Merchant account |unsupported_currency |An error occurred|

openToCaptureAmountobject or null

Object containing amount and currency.

Example	errorCode	message
`amount` is omitted or null	invalid_object	{Money object}.amount Amount field required
`amount` has more than 2 decimal places	invalid_object amount	must be a valid ISO 4217 format value
`amount` includes a thousands separator comma, for example: “1,000”	invalid_amount	Amount must be a valid ISO 4217 format value
`amount` is not a decimal number, for example: “FREE”, “$2” or an empty string	invalid_object	{Money object}.amount Amount field must be a valid ISO 4217 format value
`currency` is omitted or null	invalid_object	{Money object}.currency Currency field required
`currency` is not a valid currency code, not all uppercase or an empty string	invalid_object	{Money object}.currency Currency not supported for this merchant
`currency` is supported by Afterpay, but not valid for the Merchant account	unsupported_currency	An error occurred

paymentStateenum or null

is the current state for capturing payments

merchantReferencestring or null

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

refundslist of objects or null

orderDetailsobject or null

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 or null

agreementslist of objects or null

List of billing agreements utilized or created if any (field omitted if empty)

Errors

Object containing amount and currency.

Example	errorCode	message
`amount` is omitted or null	invalid_object	{Money object}.amount Amount field required
`amount` has more than 2 decimal places	invalid_object amount	must be a valid ISO 4217 format value
`amount` includes a thousands separator comma, for example: “1,000”	invalid_amount	Amount must be a valid ISO 4217 format value
`amount` is not a decimal number, for example: “FREE”, “$2” or an empty string	invalid_object	{Money object}.amount Amount field must be a valid ISO 4217 format value
`currency` is omitted or null	invalid_object	{Money object}.currency Currency field required
`currency` is not a valid currency code, not all uppercase or an empty string	invalid_object	{Money object}.currency Currency not supported for this merchant
`currency` is supported by Afterpay, but not valid for the Merchant account	unsupported_currency	An error occurred

1	import requests
2
3	url = "https://global-api-sandbox.afterpay.com/v2/payments/auth"
4
5	payload = {
6	"token": "005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2",
7	"requestid": "d22f5305-05f3-48a0-9131-a4e6e5f58b9a",
8	"merchantReference": "merchant-order-123",
9	"amount": {
10	"amount": "100.00",
11	"currency": "AUD"
12	},
13	"isCheckoutAdjusted": True,
14	"paymentScheduleChecksum": "string",
15	"items": [None],
16	"shipping": {
17	"name": "Joe Consumer",
18	"line1": "Level 5",
19	"area1": "Melbourne",
20	"region": "VIC",
21	"postcode": "3000",
22	"countryCode": "AU",
23	"line2": "390 Collins Street",
24	"phoneNumber": "0400 000 000"
25	},
26	"enrichments": { "initiation": { "actor": "MERCHANT" } }
27	}
28	headers = {
29	"User-Agent": "User-Agent",
30	"Authorization": "Basic <username>:<password>",
31	"Content-Type": "application/json"
32	}
33
34	response = requests.post(url, json=payload, headers=headers)
35
36	print(response.json())

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	}

Authentication

Headers

Request

Response

Errors