Recurring Payment Scenarios

Recurring

Description

Recurring is merchant initiated transactions for automatic or systematically repeated payments, using previously saved customers' card data.

In order to use Recurring, at first, the card data has to be saved: learn more about it in the Payment Method Saving section. Card data can be saved either on the merchant's side or on the Cardaq side.

Two types of Recurring are supported:

  • Automatic (Merchant Initiated Transactions (MIT); unscheduled): off-session payments for which the cardholder does not participate and for which the merchant charges their customers irregularly and for different amounts. For example, taxi apps - the cardholder is charged for the final amount at the end of the ride, and the charging does not require cardholder’s confirmation;
  • Recurring (Merchant Initiated Transactions (MIT); scheduled): off-session payments for which the cardholder does not participate and for which the merchant charges their customers regularly for the same amount. For example, gym memberships - the cardholder is charged at the beginning or the end of the billing cycle and it is always done for the same amount.

Recurring is compatible with the following payment scenarios and additional capabilities:

  • One-Step Payment
  • Two-Step Payment
  • Full Refund
  • Partial Refund
  • Reversal
  • Use of Dynamic Descriptor
  • Use of Service Location details
  • QCash
  • SDWO Funding Payment
  • SDWO Purchase Payment
  • Taxes

Recurring (Automatic) is compatible with all of the above and:

  • Use of Travel Data
  • All types of Payouts (A2A, B2P, P2P, OG, SDWO)

Request Example

Cardaq-side Recurring

  1. Create a new request to POST /orders/. Note that the price value must be ≥0.01.
{
    "client": {
        "original_client": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "email": "test@test.com"
    },
    "products": [
        {
            "title": "Test product",
            "price": 1.00
        }
    ],
    //optional
    "use_scenario": "recurring",
    "recurring_number": "2", // conditional field, may be required for some acquiring connections; mandatory for cards issued in India
    "recurring_number_expected": "12", // conditional field, may be required for some acquiring connections
    "recurring_period": "06", // conditional field, may be required for some acquiring connections; mandatory for cards issued in India
    "recurring_reference": "Ref345235" // conditional field, may be required for some acquiring connections; mandatory for cards issued in India
}

The request body above includes an optional parameter use_scenario. Possible values for this parameter are automatic and recurring. If this parameter is not specified, then the value of setup_future_use that was specified during the initial registration will be used.
If a client has more than one card, then, instead of original_client parameter, recurring_card parameter can be passed to use the particular card.
In case other optional parameters are needed, see API Reference.

  1. Create a new request to POST /orders/{order_id}/charge/ endpoint without a request body.

Merchant-side Recurring

  1. Create a new request to POST /orders/. Note that the price value must be ≥0.01.
{
    "client": {
        "email": "test@test.com"
    },
    "products": [
        {
            "title": "Test product",
            "price": 1.00
        }
    ],
    //optional
    "recurring_number": "2", // conditional field, may be required for some acquiring connections; mandatory for cards issued in India
    "recurring_number_expected": "12", // conditional field, may be required for some acquiring connections
    "recurring_period": "06", // conditional field, may be required for some acquiring connections; mandatory for cards issued in India
    "recurring_reference": "Ref345235" // conditional field, may be required for some acquiring connections; mandatory for cards issued in India
}

The request body above includes only the mandatory parameters for the request type. In case optional parameters are needed, see API Reference.

  1. Create a new request to POST payment api_do_url.
{
    "cardholder_name": "GATE TEST",
    "card_number": "448371******6388",
    "exp_month": "**",
    "exp_year": "**",
    "saved_by_merchant": true, // should be passed during initial and subsequent executions
    "scenario": "recurring", // should match setup_future_use value used in registration
    "cof_trace_id": "0100000000000000" // conditional field, may be required for some acquiring connections
}

Note that:

  • cof_trace_id, also known as Scheme Reference ID or Scheme Transaction ID, is the initial payment’s ID provided by the card scheme and returned by the gateway, during the initial payment.

One-Click

Description

One-Click (Cardholder Initiated Transactions (CIT)) payments are on-sessions payments where the cardholder participates. Example, food delivery apps where the cardholder creates a cart and approves the final amount for authorization at the end.

In order to use One-Click, at first, the card data has to be saved: learn more about it in the Payment Method Saving section. Card data can be saved either on the merchant's side or on the Cardaq side.

One-Click is compatible with the following payment scenarios and additional capabilities:

  • One-Step Payment
  • Two-Step Payment
  • Full Refund
  • Partial Refund
  • Reversal
  • Use of Travel Data
  • Use of Dynamic Descriptor
  • Use of Service Location details
  • QCash
  • SDWO Funding Payment
  • SDWO Purchase Payment
  • Taxes

Request Example

Cardaq-side One-Click

  1. Create a new request to POST /orders/. Note that the price value must be ≥0.01.
{
    "client": {
        "email": "test@test.com",
        "original_client": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    },
    "use_scenario": "one-click",
    "products": [
        {
            "title": "Test product",
            "price": 1.00
        }
    ]
}

If a client has more than one card, then, instead of original_client parameter, recurring_card parameter can be passed to use the particular card.
The request body above includes only the mandatory parameters for the request type. In case optional parameters are needed, see API Reference.

  1. Present to the customer one of the Gateway-hosted checkout options (Full Page or Web SDK), using the appropriate URL you received in the response to the previous step. Card data input fields will be already prefilled for your customer's convenience.

Merchant-side One-Click

  1. Create a new request to POST /orders/. Note that the price value must be ≥0.01.
{
    "client": {
        "email": "test@test.com"
    },
    "products": [
        {
            "title": "Test product",
            "price": 1.00
        }
    ]
}

The request body above includes only the mandatory parameters for the request type. In case optional parameters are needed, see API Reference.

  1. Create a new request to POST payment api_do_url.
{
    "cardholder_name": "GATE TEST",
    "card_number": "448371******6388",
    "exp_month": "**",
    "exp_year": "**",
    "cvv": "***", // mandatory field for non-3D terminals
    "saved_by_merchant": true, // should be passed during initial and subsequent executions
    "scenario": "one-click", // should match setup_future_use value used in registration
    "cof_trace_id": "0100000000000000" // conditional field, may be required for some acquiring connections
}

Note that:

  • In case of 3DS terminals, EU cards will always be required to authenticate, using 3DS.
  • cof_trace_id, also known as Scheme Reference ID or Scheme Transaction ID, is the initial payment’s ID provided by the card scheme and returned by the gateway, during the initial payment.