Recurring - Card

The recurring functionality enables merchants to process transactions using previously saved information from a customer's initial transaction. This eliminates the need to re-enter card details for subsequent transactions.

Recurring transactions closely resemble standard transactions. This guide uses card payments as an example. For comprehensive information about standard card integration, please refer to the card integration guide.

For detailed API specifications, consult the API documentation.

Required Fields

Recurring transactions require additional fields:

For information on creating a customer object, refer to the customer creation section in the card integration guide.

First Transaction Initialization

In addition to the standard card transaction initialization request, you must include the recurring_type and customer parameters.

Below is a sample request body for initiating 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

After the successful completion of the initial transaction, retrieve the Card ID for future use:

1. Send a GET request to fetch the transaction details:
   GET /v1/transaction/{Transaction ID}
2. In the response, locate the card field. This value is the Card ID.
3. Securely store this Card ID for subsequent transactions.

Subsequent transaction initialization

For subsequent recurring transactions, you need to include additional parameters in your request:

• recurring_type: Set this to "repeat" for subsequent transactions
• customer: The Customer ID obtained when creating the customer
• card: The Card ID obtained after the initial transaction

These parameters are in addition to the standard fields required for initializing a card transaction.

Here's a sample request body for initiating a 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 card 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: