Authorize Recurring Payment | Welcome to Afterpay Documentation

Authorizes a recurring payment using a billing agreement token. This endpoint performs authorization only, requiring a separate capture step.

Deprecated. For new integrations, see Grants.

Authorizes a recurring payment using a billing agreement token. This endpoint performs authorization only, requiring a separate capture step. *Deprecated. For new integrations, see [Grants](https://afterpay.docs.buildwithfern.com/afterpay-online-developer/api-reference/reference/grants/start-grant-approval).*

Authentication

AuthorizationBasic

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

Request

The request containing the payment details to authorize

requestIdstringRequiredformat: "uuid"<=64 characters

A unique identifier for the request, used for idempotency

paymentMethodobjectRequired

amountobjectRequired

The total amount of the payment

consumerobjectOptional

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.

billingobjectOptional

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.

Important Note

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

shippingobjectOptional

The line2 and area2 fields provide additional space for extended addresses, while phoneNumber can be used to store the user’s contact number.

Important Note

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

courierobjectOptional

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.

itemslist of objectsOptional

discountslist of objectsOptional

descriptionstringOptional<=256 characters

merchantobjectOptional

merchantReferencestringOptional<=128 characters

The reference/order ID in the merchant’s system

shippingAmountobjectOptional

The shipping cost amount

taxAmountobjectOptional

The tax amount

custommap from strings to anyOptional

Custom key-value pairs for merchant use

paymentScheduleChecksumstringOptional

Payment schedule validation checksum

enrichmentsobjectOptional

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.

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

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

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

agreementslist of objects

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

Errors

402

Payment Required Error

412

Precondition Failed Error

415

Unsupported Media Type Error

422

Unprocessable Entity Error

1	curl -X POST https://global-api-sandbox.afterpay.com/v2/recurring-payments/auth \
2	-H "User-Agent: User-Agent" \
3	-H "Content-Type: application/json" \
4	-u "<username>:<password>" \
5	-d '{
6	"requestId": "123e4567-e89b-12d3-a456-426614174000",
7	"paymentMethod": {
8	"token": "005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2",
9	"type": "BILLING_AGREEMENT"
10	},
11	"amount": {
12	"amount": "100.00",
13	"currency": "AUD"
14	}
15	}'

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	"type": "CAPTURED",
71	"amount": {
72	"amount": "37.00",
73	"currency": "USD"
74	},
75	"paymentEventMerchantReference": "k6-gsrdqspusf"
76	}
77	],
78	"discounts": [],
79	"shippingAmount": {
80	"amount": "10.00",
81	"currency": "USD"
82	},
83	"taxAmount": {
84	"amount": "0.00",
85	"currency": "USD"
86	}
87	}

Authentication

Headers

Request

Important Note

Important Note

Response

Errors