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 Create Recurring Payment (Immediate Capture)
  • Clearpay Messaging
    • Getting Started
    • Implementation
    • Migration
    • Launch Clearpay Info Modal Anywhere
LogoLogo
On this page
  • Recurring Payments - More Information
API Developmentrecurring-payments

Draft Create Recurring Payment (Immediate Capture)

Was this page helpful?
Previous

Getting Started

Next
Built with

This method creates a new recurring payment using the Billing Agreement as the payment method.

A new order is created based on the request body and payment is captured using the Billing Agreement. To achieve this, a Billing Agreement token is provided as the payment method.

The process starts with the following post:

POST /v2/recurring-payments

Sample Request

1POST https://api-sandbox.clearpay.com/v2/recurring-payments 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": "2023-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 the payment is approved by Clearpay, it returns a Payment object in response, with a status of APPROVED. If the payment is declined by Clearpay, for example, if invalid card details were entered, rit eturns a Payment object in response, with a status of DECLINED.Payment
400Bad RequestThe request body contains invalid or improperly formatted JSON.Error
401UnathorizedInvalid Merchant API credentials were passed in the Authorization header.Error
402Payment RequiredThe agreement token is invalid, expired, completed, or does not exist.Error
403ForbiddenAccess is forbidden. Recurring payments product must be enabled on the merchant account.Error
405Method Not AllowedThe request was made with an unacceptable HTTP Method. Depending on the endpoint, only PUT or POST requests are allowed. Use the OPTIONS HTTP Method to decide 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 EntityOne or more required fields were missing or invalid.Error
500Internal Server ErrorA common cause of this response from PUT/POST endpoints is that the request body is missing or empty.Error

Example responses

200 - 201 Approved

1{
2 "id": "12345678",
3 "token": "ltqdpjhbqu3veqikk95g7p3fhvcchfvtlsiobah3u4l5nln8gii9",
4 "status": "APPROVED",
5 "created": "2019-01-01T00:00:00.000Z",
6 "originalAmount": {
7 "amount": "16.00",
8 "currency": "GBP"
9 },
10 "openToCaptureAmount": {
11 "amount": "0.00",
12 "currency": "AUD"
13 },
14 "paymentState": "CAPTURED",
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": "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 "id": "1OUR16OTqL3DgJ3ELlwKowU9v6K",
70 "created": "2019-01-01T00:00:00.000Z",
71 "expires": "2019-01-01T00:00:00.000Z",
72 "type": "CAPTURED",
73 "amount": {
74 "amount": "16.00",
75 "currency": "GBP"
76 }
77 }
78 ]
79}

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}

402 Response

1{
2 "errorCode": "invalid_token",
3 "errorId": "16628d4fb02900d4",
4 "message": "The billing agreement token is invalid, expired, completed, or does not exist.",
5 "httpStatusCode": 402
6}

403 Response

1{
2 "errorCode": "forbidden",
3 "errorId": "16628d4fb02900d4",
4 "message": "Access is forbidden. Recurring payments product must be enabled on the merchant account.",
5 "httpStatusCode": 403
6}

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}

422 Response

1{
2 "errorCode": "invalid_object",
3 "errorId": "16628d4fb02900d4",
4 "message": "One or more required fields were missing or invalid.",
5 "httpStatusCode": 422
6}

500 Response

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

To create a recurring payment, 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
    • Authorise Recurring Payment (Deferred Capture)