Cascading payments

Cascading payments is used to increase payments conversion.

For working with cascading payments, several equivalent gateways must be connected to the shop (for example, both gateways can accept Visa card payments). Then, if one payment request returns failed transaction status, you could repeat the request, and the system will redirect the request to the second gateway, which has a chance to process the transaction successfully.

Cascading payments works with payment and authorization transactions types and only with failed transaction status (it doesn't work with expired and incomplete (statuses)[integration/card_api/statuses]).

How to use

Step 1 - Make a payment or authorization request.

Step 2 - If the response returns the failed transaction status, add to the request excluded_gateways array containing gateway_id of the gateways that returns failed status, set parameter "duplicate_check": false and repeat the request.

Step 3 - If the response again returns the failed transaction status, repeat Step 2; if transaction status is successful, the transaction was successfully processed.

Request

Request parameters as same as payment or authorization requests except for the next parameter:

Parameter	Type	Description
additional_data	object	A section of additional information about the payment.
excluded_gateways * required	array	An array, consisting of gateway_id of the gateway/gateways, that return failed status during the previous requests. gateway_id is returned in each response.

Response

Example of the request for cascading payments

{
  "request": {
    "dynamic_billing_descriptor": nil,
    "billing_address": {
      "first_name": nil,
      "last_name": nil,
      "address": "Baker street 221b",
      "city": "London",
      "country": "GB",
      "state": nil,
      "phone": nil,
      "zip": nil,
      "email": "example@example.com",
      "birth_date": nil,
      "device_id": nil
    },
    "customer": {
      "ip": "127.0.0.1",
      "email": "example@example.com"
    },
    "test": false,
    "notification_url": nil,
    "return_url": "https://example.com/widget/confirm.html?token=e3266138b6bf0789d4bb12f584130bbe8d181199682dc3fc86b1df38c94c3a",
    "language": "ru",
    "credit_card": {
      "number": "5 XXXX 9423",
      "verification_value": "[FILTERED]",
      "holder": "John Doe",
      "save_card": false,
      "exp_month": "08",
      "exp_year": "2026"
    },
    "currency": "BYN",
    "amount": 100,
    "description": "Test async #1",
    "tracking_id": "async-123",
    "additional_data": {
      "request_id": "f3c809d1-6dfe-41f8-b803-6a15782e3de0",
      "browser": {
        "screen_width": 1680,
        "screen_height": 1050,
        "screen_color_depth": 24,
        "language": "ru",
        "java_enabled": false,
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.114 Safari/537.36",
        "time_zone": -180,
        "accept_header": "application/json"
      },
      "vendor": {
        "name": "CTP",
        "token": "e3266138b6bfb0789d4bb12f584130bbe8dd181199682dc3fc86b1df38c94c3a"
      },
      "excluded_gateways": [
        "408",
        "409"
      ]
    },
    "expired_at": nil,
    "duplicate_check": false
  }
}