Сценарий: Самостоятельная интеграция Host-to-Host

Сценарий Самостоятельная интеграция Host-to-Host

В этом сценарии выбор способа оплаты и ввод данных для оплаты проходит на вашей стороне.

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

Вам необходимо самостоятельно реализовать следующие шаги процесса оплаты:

выбор способа оплаты;
получение от пользователя данных для оплаты выбранным способом;
сообщение пользователю результатов проведения платежа.

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

Oплата банковской картой

Обратите внимание! Платежи картой доступны, если для вашего магазина подключен этот способ оплаты и есть сертификат на соответствие требованиям PCI DSS. Если сертификата нет, выберите другой сценарий интеграции.

Для интеграции по API нужно выполнить 4 шага:

Создать платеж и получить идентификатор сессии
Получить токен и URL-адрес
Сформировать HTML-форму
Перенаправить плательщика на HTML-форму

Шаг 1. Создание платежа

Для создания платежа используйте метод [Создание платежа](../04-payments/03-payment-external.md#invoicecreate), но в параметре 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": "Svyatoslav Myronovych Polishchuk",
          "form_token": "uerhdw47d748yd784dy83uhueh834h84dh84hd8dh8",
          "session_id": ""
       }

В ответе вернется HTML-форма.

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

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

Оплата переводом на банковский счет

Плательщики смогут перечислить оплату на банковский счет одним из следующих способов:

Номер карты — плательщик видит номер карты, на которую нужно отправить перевод.

Для интеграции по API нужно выполнить три шага:

Создать платеж
Получить данные для перевода
Запросить статус платежа

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

Шаг 1. Создание платежа

Для создания платежа используйте метод [Создание платежа](../04-payments/03-payment-external.md#invoicecreate), но в параметре payway передавайте значение для сценария Host-to-Host. Это значение вы можете получить у менеджера или посмотреть в настройках магазина в [личном кабинете](https://wallet.feennex.com/shops). Обычно оно имеет префикс 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.

Если отправляете запрос, используйте [Запрос статуса платежа при оплате через сторонние платежные системы](../04-payments/03-payment-external.md#invoicecheck).

В сценарии Host-to-Host cтатусы работают так же, как и при создании счета на оплату. Если в ответе в параметре status возвращается значение 4 — плательщик успешно провел оплату, деньги поступили на ваш кошелек. [Подробнее про статусы счета](../07-reference/02-statuses.md#3)

Пример успешного ответа

{
   "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": "Ощадбанк",
         "card": "",
         "card_holder_name": "Поліщук Святослав Миронович",
         "currency": "usd",
         "expired": 1707152043.557505,
         "method": "bank",
         "phone": "380000000000",
         "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
}