Recurrent Payments

Prerequisites

• You have completed the card tokenization for a customer
• You have an API Key. For more details see the Authorization Guide.
• You have control over the backend server to retrieve data securely.

Overview

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

Setting up 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 authorization 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"
}

Processing Checkout

A mandate object must be passed at checkout processing stage. This object indicates that a customer has given consent to store their payment details for recurrent payments. You need to handle consent, 3DS flow and PCI/DSS compliance yourself in case of recurring payments, and by passing the mandate object, you assert that you have done so.

Depending on the local region regulations, this request may result in a 3DS redirection step, which you will need to handle accordingly. If you want to test 3DS flow, you can request SumUp to enable 3DS on your test account.

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

Retrieving Checkout

If you have successfully processed the checkout, a token representing a payment instrument is created. You can retrieve the checkout to find the token 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"
  }
}

Processing Subsequent Payments

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",
}