API Developmentrecurring-payments

Draft Create Recurring Payment (Immediate Capture)

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

POST https://api-sandbox.clearpay.com/v2/recurring-payments HTTP/1.1
Host: api-sandbox.afterpay.com
Content-Type: application/json
Accept: application/json

Request Parameters

NameInTypeRequiredDescription
bodybodyRecurringPaymentRequestNo

Example Request Body

{
  "requestId": "259380f5-a9ac-4607-b987-d9c4baa34f83",
  "paymentMethod": {
    "type": "BILLING_AGREEMENT",
    "token": "_7IgXzApNiRoxpEb04LbAFQShsvdE_H3"
  },
  "amount": {
    "amount": "16.00",
    "currency": "GBP"
  },
  "consumer": {
    "phoneNumber": "0400 000 000",
    "givenNames": "Joe",
    "surname": "Customer",
    "email": "test@example.com"
  },
  "billing": {
    "name": "Joe Customer",
    "line1": "Flat 5",
    "line2": "46 Collins Street",
    "area1": "Some-Town-Somewhere",
    "region": "Suffolk",
    "postcode": "AB1 2XY",
    "countryCode": "UK",
    "phoneNumber": "0400 000 000"
  },
  "shipping": {
    "name": "Joe Customer",
    "line1": "Flat 5",
    "line2": "46 Collins Street",
    "area1": "Some-Town-Somewhere",
    "region": "Suffolk",
    "postcode": "AB1 2XY",
    "countryCode": "UK",
    "phoneNumber": "0400 000 000"
  },
  "courier": {
    "shippedAt": "2023-01-01T00:00:00+10:00",
    "name": "UK Fast",
    "tracking": "AA0000000000000",
    "priority": "STANDARD"
  },
  "description": null,
  "items": null,
    "subscriptions": [
    {
      "name": "VIP Membership Renewal",
      "merchantReference": "vip-1234",
      "pageUrl": "https://merchant.example.com/vip.html",
      "imageUrl": "https://merchant.example.com/vip.jpg",
      "price": {
        "amount": "16.00",
        "currency": "GBP"
      },
      "recurringBilling": {
        "unit": "MONTH",
        "count": 1
      }
    }
  ],
  "discounts": [],
  "merchantReference": "merchantOrder-1234",
  "taxAmount": {
    "amount": "1.45",
    "currency": "GBP"
  },
  "shippingAmount": null
}

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

{
  "id": "12345678",
  "token": "ltqdpjhbqu3veqikk95g7p3fhvcchfvtlsiobah3u4l5nln8gii9",
  "status": "APPROVED",
  "created": "2019-01-01T00:00:00.000Z",
  "originalAmount": {
    "amount": "16.00",
    "currency": "GBP"
  },
  "openToCaptureAmount": {
    "amount": "0.00",
    "currency": "AUD"
  },
  "paymentState": "CAPTURED",
  "merchantReference": "merchantOrderId-1234",
  "refunds": [],
  "orderDetails": {
    "consumer": {
      "phoneNumber": "0400 000 000",
      "givenNames": "Joe",
      "surname": "Customer",
      "email": "test@example.com"
    },
    "billing": {
      "name": "Joe Customer",
      "line1": "Flat 5",
      "line2": "46 Collins Street",
      "area1": "Some-Town-Somewhere",
      "region": "Suffolk",
      "postcode": "AB1 2XY",
      "countryCode": "GB",
      "phoneNumber": "0400 000 000"
    },
    "items": null,
        "subscriptions": [
      {
        "name": "VIP Membership Renewal",
        "merchantReference": "vip-1234",
        "pageUrl": "https://merchant.example.com/vip.html",
        "imageUrl": "https://merchant.example.com/vip.jpg",
        "price": {
          "amount": "16.00",
          "currency": "GBP"
        },
        "recurringBilling": {
          "unit": "MONTH",
          "count": 1
        }
      }
    ],
    "discounts": [],
    "taxAmount": {
      "amount": "1.45",
      "currency": "GBP"
    }
  },
  "events": [
    {
      "id": "1OUR16OTqL3DgJ3ELlwKowU9v6K",
      "created": "2019-01-01T00:00:00.000Z",
      "expires": "2019-01-01T00:00:00.000Z",
      "type": "AUTH_APPROVED",
      "amount": {
        "amount": "16.00",
        "currency": "GBP"
      }
    },
    {
      "id": "1OUR16OTqL3DgJ3ELlwKowU9v6K",
      "created": "2019-01-01T00:00:00.000Z",
      "expires": "2019-01-01T00:00:00.000Z",
      "type": "CAPTURED",
      "amount": {
        "amount": "16.00",
        "currency": "GBP"
      }
    }
  ]
}

400 Response

{
  "errorCode": "invalid_json",
  "errorId": "16628d4fb02900d4",
  "message": "Bad request",
  "httpStatusCode": 400
}

401 Response

{
  "errorCode": "unauthorized",
  "errorId": "16628d4fb02900d4",
  "message": "Credentials are required to access this resource.",
  "httpStatusCode": 401
}

402 Response

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

403 Response

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

405 Response

{
  "errorCode": "method_not_allowed",
  "errorId": "16628d4fb02900d4",
  "message": "Method not allowed",
  "httpStatusCode": 405
}

406 Response

{
  "errorCode": "error",
  "errorId": "16628d4fb02900d4",
  "message": "Not acceptable",
  "httpStatusCode": 406
}

415 Response

{
  "errorCode": "error",
  "errorId": "16628d4fb02900d4",
  "message": "Unsupported media type",
  "httpStatusCode": 415
}

422 Response

{
  "errorCode": "invalid_object",
  "errorId": "16628d4fb02900d4",
  "message": "One or more required fields were missing or invalid.",
  "httpStatusCode": 422
}

500 Response

{
  "errorCode": "error",
  "errorId": "16628d4fb02900d4",
  "message": "Internal server error",
  "httpStatusCode": 500
}
Note

To create a recurring payment, you must be authenticated by MerchantAuthentication.

Recurring Payments - More Information