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.
HomeGuidesAPI Reference
HomeGuidesAPI Reference
  • Introduction to Clearpay
    • Getting Started with Clearpay Online
    • Business Hub
    • Marketing Resources
  • Platforms
    • Platforms Quickstart
    • Adobe Commerce (Magento 2)
    • Adyen
    • Ecwid
    • Shopify
    • Stripe
    • Wix
    • WooCommerce
  • API Development
    • API Quickstart
    • Test Environments
    • Certification
      • Draft Authorise Recurring Payment (Deferred Capture)
  • Clearpay Messaging
    • Getting Started
    • Implementation
    • Migration
    • Launch Clearpay Info Modal Anywhere
LogoLogo
On this page
  • Capturing the Payment
  • Recurring Payments - More Information
API Developmentrecurring-payments

Draft Authorise Recurring Payment (Deferred Capture)

Was this page helpful?
Previous

Getting Started

Next
Built with

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

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

Request Parameters

NameInTypeRequiredDescription
bodybodyRecurringPaymentRequestNo

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

StatusMeaningDescriptionSchema
201CreatedIf payment is approved by Clearpay, returns a Payment object in response, with a status of APPROVED.Payment
400Bad RequestThe request body contains invalid or improperly formatted JSON.Error
401UnauthorizedInvalid Merchant API credentials were passed in the Authorisation header.Error
402Payment RequiredThe 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
403ForbiddenNone.Error
405Method Not AllowedThe 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
406Not AcceptableThe request included an Accept header for something other than application/json or */*.Error
415Unsupported Media TypeThe request did not include a Content-Type header, or its value was anything other than application/json.Error
422Unprocessable EntityThe 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

PropertyValue
statusAPPROVED
statusDECLINED
paymentStateAUTH_APPROVED
paymentStateAUTH_DECLINED
paymentStatePARTIALLY_CAPTURED
paymentStateCAPTURED
paymentStateCAPTURE_DECLINED
paymentStateVOIDED
prioritySTANDARD
priorityEXPRESS
unitDAY
unitWEEK
unitMONTH
typeBILLING
statusACTIVE
statusCOMPLETED
statusCANCELLED
statusEXPIRED

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
    • Store Clearpay as a Payment Method
    • Checkout and Store Clearpay as Payment Method
    • Create Recurring Payment
    • Recurring Payments Flow
    • Setup Billing Agreement Approval
    • Create Billing Agreement
    • Get Billing Agreement
    • Cancel Billing Agreement
    • Create Recurring Payment (Immediate Capture)