Draft Authorise Recurring Payment (Deferred Capture)

Once a recurring payment has been created, it must be authorised. The authorisation uses a Billing Agreement as the payment method. This endpoint determines the order approval status.

If the order is approved, the Auth (authorisation) has an expiration date and time. This information is returned in the events list for the AUTH_APPROVED payment event.

The process starts with this post:

POST /v2/recurring-payments/auth

Sample Request

1 POST https://api-sandbox.afterpay.com/v2/recurring-payments/auth HTTP/1.1
2 Host: api-sandbox.afterpay.com
3 Content-Type: application/json
4 Accept: application/json

Request Parameters

Name	In	Type	Required	Description
body	body	RecurringPaymentRequest	No

Example Request Body

1 {
2   "requestId": "259380f5-a9ac-4607-b987-d9c4baa34f83",
3   "paymentMethod": {
4     "type": "BILLING_AGREEMENT",
5     "token": "_7IgXzApNiRoxpEb04LbAFQShsvdE_H3"
6   },
7   "amount": {
8     "amount": "16.00",
9     "currency": "GBP"
10   },
11   "consumer": {
12     "phoneNumber": "0400 000 000",
13     "givenNames": "Joe",
14     "surname": "Customer",
15     "email": "test@example.com"
16   },
17   "billing": {
18     "name": "Joe Customer",
19     "line1": "Flat 5",
20     "line2": "46 Collins Street",
21     "area1": "Some-Town-Somewhere",
22     "region": "Suffolk",
23     "postcode": "AB1 2XY",
24     "countryCode": "UK",
25     "phoneNumber": "0400 000 000"
26   },
27   "shipping": {
28     "name": "Joe Customer",
29     "line1": "Flat 5",
30     "line2": "46 Collins Street",
31     "area1": "Some-Town-Somewhere",
32     "region": "Suffolk",
33     "postcode": "Ab1 2XY",
34     "countryCode": "UK",
35     "phoneNumber": "0400 000 000"
36   },
37   "courier": {
38     "shippedAt": "2019-01-01T00:00:00+10:00",
39     "name": "UK Fast",
40     "tracking": "AA0000000000000",
41     "priority": "STANDARD"
42   },
43   "description": null,
44   "items": null,
45     "subscriptions": [
46     {
47       "name": "VIP Membership Renewal",
48       "merchantReference": "vip-1234",
49       "pageUrl": "https://merchant.example.com/vip.html",
50       "imageUrl": "https://merchant.example.com/vip.jpg",
51       "price": {
52         "amount": "16.00",
53         "currency": "GBP"
54       },
55       "recurringBilling": {
56         "unit": "MONTH",
57         "count": 1
58       }
59     }
60   ],
61   "discounts": [],
62   "merchantReference": "merchantOrder-1234",
63   "taxAmount": {
64     "amount": "1.45",
65     "currency": "GBP"
66   },
67   "shippingAmount": null
68 }

Responses

Status	Meaning	Description	Schema
201	Created	If payment is approved by Clearpay, returns a Payment object in response, with a status of APPROVED.	Payment
400	Bad Request	The request body contains invalid or improperly formatted JSON.	Error
401	Unauthorized	Invalid Merchant API credentials were passed in the Authorisation header.	Error
402	Payment Required	The payment is declined by Clearpay, for example, if invalid card details were entered. Clearpay returns a Payment object in response, with a status of DECLINED. This occurs if the billing agreement token is invalid, expired, completed, or does not exist.	Error
403	Forbidden	None.	Error
405	Method Not Allowed	The request was made using an unacceptable HTTP method. Depending on the endpoint, only PUT or POST requests are allowed. Use the OPTIONS HTTP method to determine which methods are allowed for each endpoint.	Error
406	Not Acceptable	The request included an Accept header for something other than application/json or /.	Error
415	Unsupported Media Type	The request did not include a Content-Type header, or its value was anything other than application/json.	Error
422	Unprocessable Entity	The create checkout request could not be processed for one of the reasons listed below.

Unprocessable Entity reasons - 422 in the table above

invalid_object: One or more required fields were missing or invalid
unsupported_payment_type: The amount is outside the merchant’s payment limits, as returned by _Get Configuration_
unsupported_currency: One or more money objects may have contained a currency that differs from the merchant’s account currency.|Inline| |500|Internal Server Error| A common cause of this response from PUT/POST endpoints is that the request body is missing or empty. |Error|

Example Responses

201 Response

1 {
2   "id": "12345678",
3   "token": "ltqdpjhbqu3veqikk95g7p3fhvcchfvtlsiobah3u4l5nln8gii9",
4   "status": "APPROVED",
5   "created": "2023-01-01T00:00:00.000Z",
6   "originalAmount": {
7     "amount": "16.00",
8     "currency": "GBP"
9   },
10   "openToCaptureAmount": {
11     "amount": "0.00",
12     "currency": "GBP"
13   },
14   "paymentState": "AUTH_APPROVED",
15   "merchantReference": "merchantOrderId-1234",
16   "refunds": [],
17   "orderDetails": {
18     "consumer": {
19       "phoneNumber": "0400 000 000",
20       "givenNames": "Joe",
21       "surname": "Customer",
22       "email": "test@example.com"
23     },
24     "billing": {
25       "name": "Joe Consumer",
26       "line1": "Flat 5",
27       "line2": "46 Collins Street",
28       "area1": "Some-Town-Somewhere",
29       "region": "Suffolk",
30       "postcode": "AB1 2XY",
31       "countryCode": "GB",
32       "phoneNumber": "0400 000 000"
33     },
34     "items": null,
35         "subscriptions": [
36       {
37         "name": "VIP Membership Renewal",
38         "merchantReference": "vip-1234",
39         "pageUrl": "https://merchant.example.com/vip.html",
40         "imageUrl": "https://merchant.example.com/vip.jpg",
41         "price": {
42           "amount": "16.00",
43           "currency": "GBP"
44         },
45         "recurringBilling": {
46           "unit": "MONTH",
47           "count": 1
48         }
49       }
50     ],
51     "discounts": [],
52     "taxAmount": {
53       "amount": "1.45",
54       "currency": "GBP"
55     }
56   },
57   "events": [
58     {
59       "id": "1OUR16OTqL3DgJ3ELlwKowU9v6K",
60       "created": "2019-01-01T00:00:00.000Z",
61       "expires": "2019-01-01T00:00:00.000Z",
62       "type": "AUTH_APPROVED",
63       "amount": {
64         "amount": "16.00",
65         "currency": "GBP"
66       }
67     }
68   ]
69 }

400 Response

1 {
2   "errorCode": "invalid_json",
3   "errorId": "16628d4fb02900d4",
4   "message": "Bad request",
5   "httpStatusCode": 400
6 }

401 Response

1 {
2   "errorCode": "unauthorized",
3   "errorId": "16628d4fb02900d4",
4   "message": "Credentials are required to access this resource.",
5   "httpStatusCode": 401
6 }

Declined Payment

If the payment is declined by Clearpay, it returns a Payment object in response, with a status of “DECLINED”. For example, if invalid card details were entered.

This occurs if the billing agreement token is invalid, expired, completed, or does not exist.

1 {
2   "id": "12345678",
3   "token": "ltqdpjhbqu3veqikk95g7p3fhvcchfvtlsiobah3u4l5nln8gii9",
4   "status": "DECLINED",
5   "created": "2019-01-01T00:00:00.000Z",
6   "originalAmount": {
7     "amount": "29.99",
8     "currency": "GBP"
9   },
10   "openToCaptureAmount": {
11     "amount": "29.99",
12     "currency": "GBP"
13   },
14   "paymentState": "AUTH_DECLINED",
15   "merchantReference": "merchantOrderId-1234",
16   "refunds": [],
17   "orderDetails": {
18     "consumer": {
19       "phoneNumber": "0400 000 000",
20       "givenNames": "Joe",
21       "surname": "Customer",
22       "email": "test@example.com"
23     },
24     "billing": {
25       "name": "Joe Customer",
26       "line1": "Flat 5",
27       "line2": "46 Collins Street",
28       "area1": "Some-Town-Somewhere",
29       "region": "Suffolk",
30       "postcode": "AB1 2XY",
31       "countryCode": "UK",
32       "phoneNumber": "0400 000 000"
33     },
34     "items": null,
35         "subscriptions": [
36       {
37         "name": "VIP Membership Renewal",
38         "merchantReference": "vip-1234",
39         "pageUrl": "https://merchant.example.com/vip.html",
40         "imageUrl": "https://merchant.example.com/vip.jpg",
41         "price": {
42           "amount": "16.00",
43           "currency": "GBP"
44         },
45         "recurringBilling": {
46           "unit": "MONTH",
47           "count": 1
48         }
49       }
50     ],
51     "discounts": [],
52     "taxAmount": {
53       "amount": "1.45",
54       "currency": "GBP"
55     }
56   },
57   "events": [
58     {
59       "id": "1OUR16OTqL3DgJ3ELlwKowU9v6K",
60       "created": "2019-01-01T00:00:00.000Z",
61       "expires": "2019-01-01T00:00:00.000Z",
62       "type": "AUTH_DECLINED",
63       "amount": {
64         "amount": "16.00",
65         "currency": "GBP"
66       }
67     }
68   ]
69 }
70 {
71   "errorCode": "invalid_token",
72   "errorId": "16628d4fb02900d4",
73   "message": "The checkout token is invalid, expired, completed, or does not exist.",
74   "httpStatusCode": 402
75 }

405 Response

1 {
2   "errorCode": "method_not_allowed",
3   "errorId": "16628d4fb02900d4",
4   "message": "Method not allowed",
5   "httpStatusCode": 405
6 }

406 Response

1 {
2   "errorCode": "error",
3   "errorId": "16628d4fb02900d4",
4   "message": "Not acceptable",
5   "httpStatusCode": 406
6 }

415 Response

1 {
2   "errorCode": "error",
3   "errorId": "16628d4fb02900d4",
4   "message": "Unsupported media type",
5   "httpStatusCode": 415
6 }

The create checkout request could not be processed for one of these reasons:

invalid_object: One or more required fields were missing or invalid.
unsupported_payment_type: The amount is outside of the merchant’s payment limits, as returned by Get Configuration.
unsupported_currency: One or more money objects may have contained a currency that differs from the merchant’s account currency.

1 {
2   "errorCode": "invalid_object",
3   "errorId": "16628d4fb02900d4",
4   "message": "One or more required fields were missing or invalid",
5   "httpStatusCode": 422
6 }
7 {
8   "errorCode": "unsupported_payment_type",
9   "errorId": "16628d4fb02900d4",
10   "message": "Unsupported payment type",
11   "httpStatusCode": 422
12 }
13 {
14   "errorCode": "unsupported_currency",
15   "errorId": "16628d4fb02900d4",
16   "message": "Unsupported currency",
17   "httpStatusCode": 422
18 }

500 Response

1 {
2   "errorCode": "error",
3   "errorId": "16628d4fb02900d4",
4   "message": "Internal server error",
5   "httpStatusCode": 500
6 }

Response Schema

Enumerated Values

Property	Value
status	APPROVED
status	DECLINED
paymentState	AUTH_APPROVED
paymentState	AUTH_DECLINED
paymentState	PARTIALLY_CAPTURED
paymentState	CAPTURED
paymentState	CAPTURE_DECLINED
paymentState	VOIDED
priority	STANDARD
priority	EXPRESS
unit	DAY
unit	WEEK
unit	MONTH
type	BILLING
status	ACTIVE
status	COMPLETED
status	CANCELLED
status	EXPIRED

Capturing the Payment

The payment is captured in the same way as any other standard payment is captured. See the Deferred Capture topic for more details

Note

To do any of the above operations, you must be authenticated by MerchantAuthentication.

Recurring Payments - More Information

Recurring Payments