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://gate.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": "UAH",
        "amount": 17,
        "service": "payment_card_UAH_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": "UAH",
    "service_currency": "UAH",
    "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_UAH_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": "UAH",
        "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`	Ідентифікатор каналу пристрою (desktop, mobile, tablet)	`desktop`
`window_height`	`string`	Висота вікна браузера	`1200`
`window_width`	`string`	Ширина вікна браузера	`1920`

(для 3DS) Перенаправлення користувача на ACS¶

У відповіді на запит /payment/sale об'єкт auth_payload містить дані для 3D-Secure.

На action URL потрібно передати параметри форми params методом method. Водночас самі параметри та їх назви можуть змінюватись в залежності від еквайєра.

Приклади об'єкта 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://gate.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="
        }
    }
}

Особливості передачі параметрів за 3DS 1.0 flow

У стандартній відповіді на запит при 3DS 1.0 в auth_payload приходять параметри MD (Merchant Data, номер посилання для ідентифікації транзакції на стороні мерчанта), PaReq (Payer Authentication Request, повідомлення відповіді DIBS сервера) і TermUrl (URL веб-сайту мерчанта, на який автентифікуючий банк відправить платника після завершення автентифікації).

Ви можете замінити отриманий параметр TermUrl на свій для перенаправлення користувача. Але, в такому випадку, обов'язково ретранслюйте запит ACS без модифікації і тим самим методом, яким надіслав ACS, на вихідну адресу TermUrl (endpoint: /payment/sale).