Recurring Payments

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

Overview

Recurring payments can be used to charge customers on a regular basis, such as, for subscription or credit-based services. They can be for a one-off amount, or for a regular amount, such as a weekly, monthly or annual charge. The customer goes through the payment process once, for the first transaction, and then the recurring process occurs automatically.

For recurring payments, you need to gain customer consent through the first payment. It works in the same way as a regular payment and the customer may also be required to authenticate the initial transaction with EMV® 3-D Secure. After the first payment, the customer's card will be charged automatically without having to perform a new payment flow.

See the below steps for an overview on how a recurring payment request is processed:

  1. A request is submitted into the /payments/recurring endpoint.
  2. We will decrypt the card details from the card_id field and look up the associated scheme reference data for the card.
  3. The recurring payment will be submitted to the acquiring bank.

Recurring payment request

See below a list of the parameters passed in the recurring payments request:

FieldTypeDescription
order_idstringUnique reference assigned by you for the payment request.
amountfloatThe total amount you want to charge.
currencystringISO 4217 currency code in lower case.
capturebooleanSet to false if you want to just authorise and request a funds transfer later.
card_idstringUUID assigned by Acquired.com for the card.
referencestringWhere supported by the acquiring bank set the reference to appear on the card holder's bank statement.
subscription_reasonstringIndicates the reason for processing an authorisation request against a previously stored card: recurring instalment unscheduled resubmission reauthorisation delayed_charge no_show

Request:

{
  "transaction": {
    "order_id": "5c5fddcc-6a5c-400d-823b-920022b9fc51",
    "amount": 15.02,
    "currency": "gbp",
    "capture": true
  },
  "payment": {
    "card_id": "0d004a37-4163-70d2-f512-6313bf3da9de",
    "reference": "Custom Ref 001",
    "subscription_reason": "recurring"
  }
}

Successful response:

{
   "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

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.


Error responses

In this response the currency is invalid:

{
    "status": "error",
    "error_type": "validation",
    "title": "Your request parameters did not pass our validation.",
    "instance": "/v1/payments/recurring",
    "invalid_parameters": [
        {
            "parameter": "transaction.currency",
            "reason": "transaction.currency can not be empty"
        }
    ]
}

In the next response the subscription_reason is invalid:

{
    "status": "error",
    "error_type": "validation",
    "title": "Your request parameters did not pass our validation.",
    "instance": "/v1/payments/recurring",
    "invalid_parameters": [
        {
            "parameter": "payment.subscription_reason",
            "reason": "must be either recurring, instalment, unscheduled, resubmission, reauthorisation, delayed_charge or no_show"
        }
    ]
}

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 chargebacks. It is also advised to notify your customer in advance of their next payment, for example by sending them an email.