Skip to main content

Сценарій Самостійна інтеграція Host-to-Host​

У цьому сценарії вибір способу оплати та введення даних для оплати відбувається на вашому боці.

Платежі карткою доступні, якщо для вашого магазину підключений цей спосіб оплати і є сертифікат на відповідність вимогам PCI DSS. Якщо сертифіката немає, виберіть інший сценарій інтеграції.

Вам необхідно самостійно реалізувати наступні кроки процесу оплати:

  • вибір способу оплати;
  • отримання від користувача даних для оплати обраним способом;
  • повідомлення користувачеві результатів проведення платежу.

Процес інтеграції відрізняється залежно від способу оплати.

Оплата банківською карткою​

Зверніть увагу! Платежі карткою доступні, якщо для вашого магазину підключений цей спосіб оплати і є сертифікат на відповідність вимогам PCI DSS. Якщо сертифіката немає, виберіть інший сценарій інтеграції.

Для інтеграції по API потрібно виконати 4 кроки:

  1. Створити платіж і отримати ідентифікатор сесії

  2. Отримати токен і URL-адресу

  3. Сформувати HTML-форму

  4. Перенаправити платника на HTML-форму

Крок 1. Створення платежу​

Для створення платежу використовуйте метод Створення платежу, але в параметрі payway передавайте значення для сценарію Host-to-Host. Це значення ви можете отримати у менеджера або переглянути в налаштуваннях магазину в особистому кабінеті. Зазвичай воно має префікс h2h. Приклад: bank_h2h_usd.

Приклад запиту на створення платежу 
curl https://core.feennex.com/invoice/create \
   -H 'Content-Type: application/json' \
   -d '{
          "currency": "840",
          "sign": "912b985f1895962",
          "payway": "bank_h2h_usd",
          "amount": "1000",
          "shop_id": 112,
          "shop_order_id": 4128
       }

У відповіді в параметрі session_id повернеться ідентифікатор сесії. Збережіть цей ідентифікатор – він знадобиться на наступних кроках.

Приклад відповіді


{
    "data": {
        "data": {
            "session_id": "3067894a580242dd86e03890506a88ba"
        },
        "id": 499564464,
        "method": "GET",
        "url": "https://example.com"
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}

Крок 2. Отримання токена та URL-адреси​

Для отримання токена використовуйте метод Дані для HTML-форми. У тілі запиту передайте ідентифікатор сесії, який ви отримали на попередньому кроці в параметрі session_id.

Приклад запиту на отримання токена

curl https://example.com/h2h_data \
   -H 'Content-Type: application/json' \
   -d '{
          "session_id": "3067894a580242dd86e03890506a88ba"
       }

У відповіді повернуться параметри form_token і payform_url. Збережіть їх – вони будуть потрібні на наступному кроці.

Приклад відповіді 
{
   "data":{
      "form_token":"uerhdw47d748yd784dy83uhueh834h84dh84hd8dh8",
      "payform_url":"https://example.com/payform/"
   },
   "error_code":0,
   "message":"success",
   "result":true
}

Крок 3. Формування платіжної форми​

Вам потрібно зібрати дані банківської картки платника та надіслати запит на створення HTML-форми.

Збір даних банківської картки платника​

Зверніть увагу! У вас повинен бути сертифікат на відповідність вимогам PCI DSS

З вашого боку вам потрібно реалізувати сторінку введення даних банківської картки платника. На цій сторінці потрібно зібрати такі дані:

  • рік і місяць закінчення терміну дії картки
  • тризначний код CVV або CVC
  • номер картки
  • ім'я та прізвище власника картки.
Відправлення запиту на створення HTML-форми​

Вам потрібно відправити POST-запит на створення HTML-форми. Запит потрібно відправити на payform_url, який ви отримали на попередньому кроці. У тілі запиту потрібно передати дані банківської картки платника, form_token та ідентифікатор сесії session_id.

Приклад запиту на створення платіжної форми

curl https://example.com/payform/ \
   -H 'Content-Type: application/json' \
   -d '{
          "expiry_year": "26",
          "cvv": "123",
          "expiry_month": "12",
          "card_number": "4111111111111111",
          "card_holder": "IVANOV IVAN",
          "form_token": "uerhdw47d748yd784dy83uhueh834h84dh84hd8dh8",
          "session_id": ""
       }
Крок 4. Перенаправлення платника на HTML-форму​

Перенаправте платника на HTML-форму, яку ви отримали у відповіді на попередньому кроці. Платник автоматично перейде на сторінку введення коду 3D-secure. Якщо оплата пройшла, Feennex перенаправить платника на Success URL. Якщо оплата не пройшла або код невірний – на Failed URL.

Оплата переказом на банківський рахунок​

Платники зможуть перерахувати оплату на банківський рахунок одним із таких способів:

  • Номер картки — платник бачить номер картки, на яку потрібно надіслати переказ.

Для інтеграції по API потрібно виконати три кроки:

  • Створити платіж

  • Отримати дані для переказу

  • Запитати статус платежу

Взаємодія відбувається асинхронно: після успішного створення платежу ви можете відразу спробувати отримати дані для переказу.

Крок 1. Створення платежу​

Для створення платежу використовуйте метод Створення платежу, але в параметрі payway передавайте значення для сценарію Host-to-Host. Це значення ви можете отримати у менеджера або переглянути в налаштуваннях магазину в особистому кабінеті. Зазвичай воно має префікс h2h. Приклад: bank_h2h_usd.

Приклад запиту на створення платежу 
curl https://core.feennex.com/invoice/create \
   -H 'Content-Type: application/json' \
   -d '{
          "currency": 840,
          "sign": "912b985f1895962",
          "payway": "bank_h2h_usd",
          "amount": 1000,
          "shop_id": 112,
          "shop_order_id": 4128
       }'
Приклад відповіді 
{
   "data":{
      "data":{},
      "id":123456789,
      "method":"bank",
      "url":"h2h"
   },
   "error_code":0,
   "message":"Ok",
   "result":true
}

Крок 2. Отримання даних для переказу​

Після створення платежу вам потрібно отримати дані для переказу. Ці дані ви повинні самостійно показувати платнику на вашій платіжній сторінці.

Для отримання даних для переказу використовуйте Запит статусу платежу при оплаті через інші способи оплати.

Зверніть увагу! Якщо даних для переказу немає, повторіть запит пізніше – дані для переказу присвоюються платежу не відразу.

Приклад запиту на отримання даних для переказу

curl https://core.feennex.com/invoice/check \
   -H 'Content-Type: application/json' \
   -d '{
          "now": "2024-02-05 18:37:02",
          "sign": "32b2c32caa8ad",
          "shop_id": 112,
          "shop_order_id": 4128
       }'

Feennex повертає стандартну відповідь. В об'єкті ps_data містяться дані для перекладу.

Параметр Тип Опис
amount number Сума, яку повинен перевести платник
bank string Найменування банку отримувача. Значення повертається, якщо параметр method має значення sbp. В інших випадках повертається порожнє значення
card string Номер банківської картки отримувача. Значення повертається, якщо параметр method має значення bank. В інших випадках повертається порожнє значення
card_holder_name string ПІБ отримувача
currency string Валюта переказу
expired string Час, до якого платник повинен відправити переказ. Рекомендується попереджати про це платника
method string Код способу оплати. Можливі значення вам повідомить менеджер.
phone string номер телефону платника. Значення повертається, якщо параметр method має значення sbp. В інших випадках повертається порожнє значення
url string УРЛ

Крок 3. Запит статусу платежу​

Після відображення даних для переказу ви можете перевіряти статус платежу: періодично надсилати запит або чекати на успішний callback.

Якщо надсилаєте запит, використовуйте Запит статусу платежу при оплаті через сторонні платіжні системи.

У сценарії Host-to-Host статуси працюють так само, як і при створенні рахунку на оплату. Якщо у відповіді в параметрі status повертається значення 4 — платник успішно провів оплату, гроші надійшли на ваш гаманець. Детальніше про статуси рахунку

Приклад успішної відповіді

{
   "data":{
      "client_price": 1000,
      "created": "2024-02-05 18:37:02",
      "description": "Deposit",
      "is_unique": true,
      "payment_id": 123456789,
      "payway": "bank_h2h_usd",
      "processed": null,
      "ps_currency": 840,
      "ps_data": {
         "amount": 1000,
         "bank": "sberbank",
         "card": "",
         "card_holder_name": "Иванов Иван Иванович",
         "currency": "usd",
         "expired": 1707152043.557505,
         "method": "bank",
         "phone": "79999999999",
         "url": ""
      },
      "shop_amount": 1000,
      "shop_currency": 840,
      "shop_id": 50,
      "shop_order_id": "4128",
      "shop_refund": 900,
      "status": 4,
      "updated": "2024-02-05 18:37:18"
   },
   "error_code": 0,
   "message": "Ok",
   "result": true
}