Recurring

The recurring functionality allows merchants to complete a transaction using saved information from a previous transaction. This means that it is not necessary to enter card or PayPal details for subsequent transactions.

Recurring transactions are very much the same as normal transactions. In this guide we'll use card as an example. However, recurring does also work for PayPal. Please take a look at the card integration guide for more information about the normal card integration.

For more information see the API documentation.

Required fields

Recurring transactions have a couple of additionally required fields:

See the card integration guide for more information about creating a customer object.

First transaction initialization

In addition to the normal initializing a card transaction request you have to supply the recurring_type and customer parameter.

Here is a valid request body that initiates the first recurring card transaction:

{
    "payment_profile": "7c23a50d-8699-431c-a82b-a78718d2b6f6",
    "amount": 14,
    "customer": "cbbfa6ec-fb44-4da4-94c4-d81e92fd43e6",
    "customer_ip": "127.0.0.1",
    "details": {
        "redirect_url": "https://example.com/finalize"
    },
    "dynamic_descriptor": "orderdesc01",
    "merchant_reference": "my order id",
    "payment_product": "card",
    "recurring_type": "first",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/86.0.4240.198 Safari/537.36",
    "webhook_transaction_update": "https://example.com"
}

Obtain the card ID

When the transaction has been completed successfully you would usually request the transaction information via the following endpoint:
GET /v1/transaction/{Transaction ID}

Collect the card field from this response. This is the Card ID required for subsequent transactions.

Subsequent transaction initialization

In addition to the normal initializing a card transaction request you have to supply the recurring_type, customer and card parameter. For PayPal transactions the card parameter should not be included.

Here is a valid request body that initiates the subsequent recurring card transaction:

{
    "payment_profile": "7c23a50d-8699-431c-a82b-a78718d2b6f6",
    "amount": 14,
    "card": "a61335cf-8c8b-4a75-a259-fd4dac62fb37",
    "customer": "cbbfa6ec-fb44-4da4-94c4-d81e92fd43e6",
    "customer_ip": "127.0.0.1",
    "details": {
        "redirect_url": "https://example.com/finalize"
    },
    "dynamic_descriptor": "orderdesc01",
    "merchant_reference": "my order id",
    "payment_product": "card",
    "recurring_type": "repeat",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/86.0.4240.198 Safari/537.36",
    "webhook_transaction_update": "https://example.com"
}

Advanced outcome testing for recurring repeat

Similar to the outcome tests for normal card transactions, advanced outcome tests can also be conducted for recurring transactions. These tests enable the simulation of various decline or failure outcomes by using specific holder names.

To perform these tests, choose a holder name in the format: repeat-response-[number]. For example, using repeat-response-2 will result in a decline with a status_reason of "Refused".

Overview of options: