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