Guides

Recurring Payments

Learn how to process recurring payments within the Acquired.com API.

Suggest Edits

Overview

In today's dynamic digital landscape, the ability to seamlessly handle recurring payments has become a fundamental requirement for businesses looking to provide subscription-based services, memberships, and other recurring billing models. These payments can be for a one-off amount, or for a regular amount, such as a weekly, monthly or annual charge.

At Acquired.com we offer the ability to process recurring payments via the following payment methods:

  • Card payments
  • Apple Pay
  • Google Pay

To understand how recurring payments work in Hosted Checkout, refer to the guides here.

Recurring payment process

The first step in a recurring payment process is to create a customer. The customer is pivotal to the Acquired.com API, all recurring payments will be associated to the customer_id. Submit a POST request to the /customers endpoint containing the associated customer information. For more information on this process, please see our customers API reference.

In the customer's first /payments request, ensure that the create_card parameter is set to true. In a successful response, a card_id will be returned which can then be used in the subsequent recurring payments request.

The below example shows the initial payment request, where a card is being created.

{
  "transaction": {
    "order_id": "1f1f2a61-5b68-4725-a0ce-9560514ec00b",
    "amount": 15.02,
    "currency": "gbp",
    "moto": false,
    "capture": true,
    "custom_data": "L3BheW1lbnQtbGlua3MgcGF5IGN1c3RvbV9kYXRh"
  },
  "payment": {
    "card": {
      "holder_name": "E Johnson",
      "scheme": "visa",
      "number": "4000011180138710",
      "expiry_month": 10,
      "expiry_year": 26,
      "cvv": "123"
    },
    "create_card": true,
    "reference": "Custom Ref 001"
  },
  "customer": {
    "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "tds": {
    "is_active": false,
    "redirect_url": "https://yourdomain.com/redirect",
    "webhook_url": "https://yourdomain.com/webhook"
  }
}

A card_id will then be returned within the response:

{
  "transaction_id": "a7e3fde5-5b83-44f4-9915-782bc7121717",
  "status": "success",
  "reason": "",
  "issuer_response_code": "00",
  "check": {
    "avs_line1": "matched",
    "avs_postcode": "matched",
    "cvv": "matched"
  },
  "card_id": "00cfdbdc-5e81-4ce2-adc1-14920120618f",
  "links": [
    {
      "rel": "self",
      "href": "/v1/transactions/a7e3fde5-5b83-44f4-9915-782bc7121717"
    }
  ]

📘

Note

This process works in exactly the same way for a Apple Pay or Google Pay transaction, simply ensure that the create_card parameter is set to true and a card_id will be returned within the response and can be passed in the recurring payment request.

This card_id can then be included within the recurring payment request.

For more information on the parameters involved, please refer to our recurring payments API reference.

/payments/recurring request:

{
  "transaction": {
    "order_id": "5c5fddcc-6a5c-400d-823b-920022b9fc51",
    "amount": 15.02,
    "currency": "gbp",
    "capture": true
  },
  "payment": {
    "card_id": "00cfdbdc-5e81-4ce2-adc1-14920120618f",
    "reference": "Custom Ref 001",
    "subscription_reason": "recurring"
  }
}

/payments/recurring response:

The response will be handled in the same way as any payments response, but will exclude the CVV as this is not required for recurring payments.

{
   "transaction_id": "673bcc81-3c71-4bf6-80c0-5269ad8b974b",
   "status": "success",
   "issuer_response_code": "00",
   "check": {
    "avs_line1": "matched",
    "avs_postcode": "matched"
   },
   "links": [
     {
       "rel": "self",
       "href": "/v1/transactions/673bcc81-3c71-4bf6-80c0-5269ad8b974b"
    }
  ]
 }

📘

Note

This process works in exactly the same way for a Apple Pay or Google Pay transaction, simply ensure that the create_card parameter is set to true and a card_id will be returned within the response and can be passed in the recurring payment request.

Descriptions for subscription_reason values

Enum ValueDescription
recurringUsed when processing an authorisation request as part of a regularly scheduled payment (e.g., monthly subscriptions or membership fees).
instalmentIndicates an instalment payment plan, where the total payment amount is split into multiple fixed payments over time.
unscheduledUsed for payments that occur irregularly or unpredictably, without a fixed schedule, but still based on a prior agreement.
re-submissionIndicates a resubmission of a previously declined or failed authorisation request, typically after resolving the reason for the initial failure.
re-authorisationUsed when an existing authorisation needs to be renewed or extended, often because the original authorisation has expired.
delayed chargeIndicates a charge applied after the original transaction date, typically for additional costs incurred after the initial service was provided.
no-showUsed when a customer fails to appear for a booked service, and a fee is charged according to the service provider's cancellation policy.

Reducing the risk of disputes

When processing recurring payments, we recommend to communicate how often and how much the customer will be charged as clearly as possible to avoid the risk of generating disputes. It is also advised to notify your customer in advance of their next payment, for example by sending them an email.

Updated 4 months ago