Host-to-host интеграция для получения платежей¶

Крупные организации, выполняющие требования PCI DSS, могут использовать Host-to-host (H2H) интеграцию для получения карточных платежей.

Отправьте заявку службе поддержки , чтобы уточнить требования и включить для вашего аккаунта режим H2H-платежей.

Общая схема взаимодействия¶

Клиент формирует заказ на сайте мерчанта.
Чтобы предоставить клиенту возможность выбора варианта для оплаты, мерчант отправляет предзапрос платежа и получает в ответе от платформы Cascad список доступных методов.
Мерчант отображает список методов, и клиент выбирает удобный ему способ оплатить заказ.

Пункты 2 и 3 можно пропустить

Отправка предзапроса не требуется, если мерчант определяет метод оплаты за клиента и создает инвойс платежа после формирования заказа.
Мерчант создает инвойс платежа. Получив инвойс, Cascad:
- Инициирует транзакцию на стороне провайдера.
- Присылает в ответе bearerToken платежа.
- Отправляет Callback мерчанту с уведомлением об успешном создании инвойса.
Мерчант отображает данные платежной формы на своей стороне.
Клиент вводит реквизиты для оплаты. Мерчант отправляет платёжные данные на Card Gate Cascad. Cascad перенаправляет запрос на списание средств эмитенту.
В случае, если требуется 3DSecure верификация, мерчант получает данные для отображения страницы верификации. Клиент подтверждает платёж на странице верификации, и данные передаются эмитенту.
Эмитент возвращает результаты оплаты и завершает транзакцию.
Статус платежа фиксируется и перенаправляется мерчанту.
Мерчант отображает клиенту статус платежа на страницах своего сайта.
Cascad отправляет мерчанту Callback с уведомлением о статусе платежа.
Для уточнения статуса транзакции мерчант может провести реконсиляцию платежа по ID либо получить полный список данных инвойсов с помощью приватного API. Также на портале доступно ежедневное получение отчетов по транзакциям.

Создание платежного инвойса¶

Параметры для авторизации

Создание инвойса для H2H-соединения осуществляется по BasicAuth стандарту через приватный API — https://pay.cascad.com.

Для авторизации используются ID аккаунта как Login (Username) и ключ API как Password. Вы можете найти нужные параметры в настройках аккаунта в разделе «Интеграция» .

API: PRIVATE

Авторизация: BasicAuth

Endpoint: /payment-invoices

Method: POST

JSON

Пример запроса для инвойса

{
    "data": {
    "type": "payment-invoices",
    "attributes": {
        "reference_id": "{guid}",
        "description": "Payment by order#1",
        "currency": "USD",
        "amount": 17,
        "service": "payment_card_USD_hpp",
        "return_url": "https://example.com/",
        "callback_url": "https://example.com/payments/callback"
        }
    }
}

Пример ответа

{
"data": {
    "type": "payment-invoices",
    "id": "cpi_pbqlMhg37O49gcxf",
    "attributes": {
    "status": "processed",
    "serial_number": "pbqlMhg37O49gcxf",
    "resolution": "ok",
    "moderation_required": false,
    "amount": 100,
    "payment_amount": 100,
    "currency": "USD",
    "service_currency": "USD",
    "reference_id": "0f3cb67e-097c-4367-a06e-e7523b427234",
    "test_mode": true,
    "description": "test",
    "descriptor": null,
    "fee": 0,
    "deposit": 100,
    "processed": 1615991970,
    "processed_amount": 100,
    "refunded_amount": null,
    "processed_fee": 0,
    "processed_deposit": 100,
    "metadata": [],
    "flow_data": {
        "action": "https://cardgate.psp.name/hpp/cgi_8A8vc28Hr15D8tZ3",
        "method": "GET",
        "params": [],
        "metadata": {
        "sid": "cgi_8A8vc28Hr15D8tZ3",
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9...obAhMSLaJOOmm-s"
        }
    },
    "flow": "hpp",
    "payment_flow": "charge",
    "return_url": "https://example.com",
    "return_urls": {
        "fail": "https://example.com/1",
        "pending": "https://example.com/2",
        "success": "https://example.com/3"
    },
    "callback_url": "http://example.com/4",
    "created": 1615991953,
    "updated": 1615991970,
    "payload": {
        "token": null,
        "auth_type": "card",
        "client_ip": "...",
        "payment_card": {
        "last": "0000",
        "mask": "512381******0000",
        "brand": null,
        "first": "512381",
        "holder": null,
        "network": "mastercard",
        "expiry_year": "44",
        "issuer_name": "U.S. BANK, N.A.",
        "expiry_month": "11",
        "issuer_country": "US"
        }
    },
    "original_data": {
        "external_id": "cgi_8A8vc28Hr15D8tZ3",
        "merchant_id": "host2hostTest",
        "provider_id": null,
        "external_mid": "org_02HJ5jTUtan8ZXaT",
        "provider_code": "test"
    },
    "rrn": null,
    "approval_code": null,
    "reserved_amount": null,
    "reserve_expires": null,
    "unreserved": null,
    "source": "merchant_dashboard",
    "callback_logs": []
    },
    "relationships": {
    "payment-service": {
        "data": {
        "type": "payment-services",
        "id": "payment_card_usd_hpp"
        }
    },
    "payment-method": {
        "data": {
        "type": "payment-methods",
        "id": "payment_card"
        }
    },
    "payment-request": {
        "data": {
        "type": "payment-requests",
        "id": "prq_tE4lUowE4f1C39od"
        }
    },
    "active-payment": {
        "data": {
        "type": "payments",
        "id": "pay_MOq594PzFxwU2CF9gntin897"
        }
    },
    "commerce-account": {
        "data": {
        "type": "commerce-accounts",
        "id": "coma_CVGZ6W38ZsBe5cqI"
        }
    },
    "currency-account": {
        "data": {
        "type": "currency-accounts",
        "id": "comca_p7mPXxsCTFu6sONW"
        }
    },
    "customer": {
        "data": null
        }
    },
    "links": {
    "self": "/commerce/payment-invoices/cpi_pbqlMhg37O49gcxf"
    }
},
"included": [
    {
    "type": "payment-requests",
    "id": "prq_tE4lUowE4f1C39od",
    "attributes": {
        "amount": 100,
        "paid_amount": 100,
        "amount_readonly": true,
        "currency": "USD",
        "reference_id": "cpi_pbqlMhg37O49gcxf",
        "status": "SUCCESSFUL",
        "description": "test",
        "test_mode": true,
        "expires": 1616164743,
        "created": 1615991953,
        "processed": 1615991970,
        "return_url": "https://psp.name/return?id=cpi_pbqlMhg37O49gcxf",
        "callback_url": null,
        "resolution": "OK",
        "payment_service": null,
        "metadata": {
        "fee": "0.00",
        "fee_strategy": "external"
        },
        "fields": []
    },
    "relationships": {
        "payment-page": {
        "data": null
        },
        "rate-schema": {
        "data": {
            "type": "rate-schemes",
            "id": "ers_bJYZhE0G2IzVgA7H"
            }
        },
        "routing-schema": {
        "data": {
            "type": "checkout-routing-schemes",
            "id": "rtg_2QQfnlKAkqT39Nnk"
            }
        },
        "payments": {
        "data": [
            {
            "type": "payments",
            "id": "pay_MOU2CF9gnq594PzFxwtin897"
                }
            ]
        },
        "merchant-account": {
        "data": {
            "type": "merchant-accounts",
            "id": "ma_aBct0mkJ3WiRndih"
            }
        },
        "payment-service": {
        "data": null
        },
        "payment-method": {
        "data": {
            "type": "payment-methods",
            "id": "payment_card"
            }
        },
        "payment-provider": {
        "data": {
            "type": "payment-providers",
            "id": "cardgate"
            }
        }
      }
    }
  ]
}

Отправка данных карты на Card Gate¶

API: CARDGATE (URL при интеграции выдаётся менеджером)

Endpoint: /payment/sale

Method: POST

Авторизация: bearerToken (передается параметр token, полученный в ответ на запрос создания инвойса, объект flow_data → metadata)

Кроме обязательных атрибутов с данными карт, есть возможность также передать опциональные — с параметрами браузера клиента в объекте browser_info*.

Если карта не требует 3DS-аутентификации, но в ответе вернулся промежуточный статус транзакции (process_pending), для уточнения статуса нужно дождаться сообщения Callback либо провести реконсиляцию платежа по ID инвойса.

JSON

Пример запроса с карточными данными

{
"data": {
    "type": "sale-operation",
    "attributes": {
        "card_number": "5519283812030000",
        "card_holder": "Card Holder",
        "cvv": "123",
        "exp_month": "10",
        "exp_year": "35",
        "browser_info": {
            "browser_tz": "-60", // Часовой пояс
            "browser_screen_width": "1920" // Ширина экрана браузера
            }
        }
    }
}

Пример ответа (по 3DS 1.0)

{
    "status": "process_pending",
    "auth_mode": "3ds",
    "auth_payload": {
        "action": "https://card.psp.name/acs/auth",
        "method": "POST",
        "params": {
            "MD": "cGF5X2xKWXUwaDBVeDNQMHhmTFp5enY1WFNiMl9keF9jbg",
            "PaReq": "eyJ0eXAiOiJKV1eyJjb2RlM2RzUT_uYyy6xDaS4gZHrDfTzlCbcYGOD8lYmGgoIjoiOTM1MTgzIiwicGF5bWVudF9pZCI6InBheV9sSll1MGI6IjEwMjIifQ.QiLCJhbGciOiJIUzUxMiJ9.eHUekACfQEuwYHSp3v1ctZ8eS5rE9PAtVSfyyJGgFOe16fKRaQgwVXgzUDB4ZkxaeXp2NVhTYjJfZHhfY24iLCJjYXJkX251bWJlciI6IjUxMjM4MTcyMzQwNjAwMDAiLCJleHBfZGF0ZS",
            "TermUrl": "https://card.psp.name/complete-auth?pid=pay_lJYu0h0Ux3P0xfLZyzv5XSb2_dx_cn"
        }
    }
}

Пример ответа (без 3DS аутентификации)

{
    "status": "processed",
    "auth_mode": null,
    "auth_payload": []
}

* Возможные свойства объекта browser_info

Свойство	Тип	Описание	Пример
`browser_accept_header`	`string`	Формат ожидаемого браузером заголовка	`application/json, text/plain, */`
`browser_color_depth`	`string`	Глубина цвета браузера	`24`
`browser_ip`	`string`	IP адрес плательщика	`123.123.12.1`
`browser_java_enabled`	`boolean`	Возможность исполнения браузером Java-кода	`false`
`browser_language`	`string`	Код языка браузера (согласно ISO)	`en-US`
`browser_screen_height`	`string`	Высота экрана браузера	`1200`
`browser_screen_width`	`string`	Ширина экрана браузера	`1920`
`browser_tz`	`string`	Часовой пояс (разница в минутах между UTC и локальным временем плательщика)	`-120`
`browser_user_agent`	`string`	Точное содержание заголовка User-Agent НТТР, отправленного браузером	`Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.135 Safari/537.36`
`device_channel`	`string`	Идентификатор канала устройства	`02`
`window_height`	`string`	Высота окна браузера	`1200`
`window_width`	`string`	Ширина окна браузера	`1920`

(для 3DS) Перенаправление пользователя на ACS¶

В ответе на запрос /payment/sale объект auth_payload содержит данные для 3D-Secure.

На action URL нужно передать параметры формы - params методом - method.

Warning

Параметры могут отличаться в зависимости от банка и версии технологии авторизации.

Примеры объекта auth_payload для:

3DS 1.0 (JSON)

{
"auth_payload":{
        "action":"https://acs.pay_domain/acspage/cap?RID=8\u0026VAA=A",
        "method":"POST",
        "params":{
            "MD":"999999999",
            "PaReq":"eJxVUlFvVA2jYv2jAQfuZfoD5v2E5KfQlLFJ2jAQfuZfoD5v2E5KQqurpe5os5wRBJU6dZCX79bszlDIrUe6+zWRkwjEe0qVHL3dmbqjeATGvs6XKz2Np1GBFSxq3r684PeiZvQbwnXOj9i951XdPeC4HWHT5bV1v+3z29+Vgs/OIi+9oe48acmxbs8VxVT7cFNkaX3+raapimUYqiZPbGz2CAOvRCP6gbytXany0njnTX07Y3Ii6VYY9u64EQNFz3J5OPlalzjc/4nyTv63+Lo+rfR6tFtlbfnofQDCDmaXpUEdS3SmcbXhU7MLJSwQ12gwovceazvouxlVLxmX8EgKkXeDuMSs7UoPPH47/yLbkeV+MU3SeTqst8PT5mfi9m5WZtmv+eMzCzuTzr0rcpzulYTmVbAfBLejA8KAsIlhlij6b8b+AbaDvJg=",
            "TermUrl":"https://pay.cascad.com/3ds-return?pid=pay_Hjh3kMlNdqE4WpOmNPCoIgFU_K1_nM"
            }
    }
}

3DS 2.0 (JSON)

{
    "auth_payload": {
    "action": "https://acs.pay_domain/acspage/challenge?id=0c95e0873",
    "method": "POST",
    "params": {
        "creq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjBjOTNhNWFhLTUyNzAtMzhiNi04ZGQ4LWY5Mjc5MTVlMDg3MyIsImFjc1RyYW5zSUQiOiIyYjVkNzIyYi0yNjk2LTRhOTktYTcxZS1iZjYwYmI5MzlmNTgiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0="
        }
    }
}