Recurring payments with Strong Customer Authentication

To ease the subsequent payments event, an initial checkout is authenticated according to 3DS checks. All following checkouts refer to the initial one in terms of 3DS authentication.

You will go through the following steps:

1. Set up a checkout session
2. Process checkout
3. Retrieve the checkout
4. Process future subsequent payments with a token

Steps

1. Set up a checkout session

The flow is initiated with the create a checkout endpoint. It is important to pass the customer_id parameter in this step, for future linking to a payment instrument, ideal for quickly creating and processing later payments. Additionally, a purpose parameter is passed to indicate the payment type as recurrent and process an authorisation charge of the checkout amount indicated, which is instantly reimbursed.

{
  ...
  "purpose": "SETUP_RECURRING_PAYMENT"
  ...
}

The initial checkout may be subject to the 3DS challenge, depending on multiple factors described briefly here.

Sample request available in our API Reference.

{
  "checkout_reference": "CO746453",
  "amount": 5,
  "currency": "EUR",
  "merchant_code": "ME7RMQN3",
  "description": "Sample request",
  "return_url": "http://example.com",
  "customer_id": "DC000101",
  "purpose": "SETUP_RECURRING_PAYMENT"
}

2. Process checkout

A mandate object needs to be passed at checkout processing. This object indicates that a customer has given consent to store their payment details for recurrent payments.

Depending on the local region regulations this request may result in a 3DS redirection step, which you will need to handle accordingly.

{
  "payment_type": "card",
  "installments": 1,
  "card": {
    "name": "FIRSTNAME LASTNAME",
    "number": "4111111111111111",
    "expiry_year": "2023",
    "expiry_month": "01",
    "cvv": "123",
    "zip_code": "12345"
  },
  "mandate": {
    "type": "recurrent",
    "user_agent": "Chrome: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3865.90 Safari/537.36.",
    "user_ip": "2001:0db8:85a3:0000:0a00:8a2e:0370:7300"
  }
}

3. Retrieve the checkout

If the previous operation is successful, a token representing a payment instrument is created. You can retrieve a checkout to find the value within a payment_instrument object.

{
  "id": "cd36780e-f43d-4f22-1i9e-e32a1a1bafc8",
  "checkout_reference": "0BYNWLYC7KV",
  "amount": 3.51,
  "currency": "EUR",
  ...
  "payment_instrument": {
    "token": "2fa27578-e765-5dbh-aa97-d45d3d6cdfbb"
  }
}

4. Process future subsequent payments with a token

After following the above requests you can now process recurring payments by referencing the saved token and the associated customer. Both token and customer_id fields are required.

{
  "payment_type": "card",
  "installments": 1,
  "token": "{{CARD_TOKEN}}"
  "customer_id": "DC000101",
}