Host-to-Host Integration Scenario

Self-developed integration (Host-to-Host scenario)

In this scenario, you handle both the selection of payment method and inputting payment data on your side.

You can accept payments via bank transfer or with credit/debit cards. Card payments require PCI DSS compliance certification. If you don't have the certificate, choose another integration scenario.

You need to implement the following steps independently:

Let the payer select the payment method
Collect payment data from the payer for the selected method
Inform the payer about the payment results

The integration process varies depending on the chosen payment method.

Payment by bank card

Note: To accept bank card payments, you must have a certificate compliant with the requirements of PCI DSS. If you don't have a certificate, choose another integration scenario.

To integrate via API, you need to follow these 4 steps:

Create a payment and obtain a session identifier
Get a token and a URL address
[Create an

HTML form](../04-payments/03-payment-external.md#data-for-html-form)

Redirect the payer to the HTML form

Step 1. Create payment

To create a payment, use the Create payment endpoint, but in the payway parameter, send the value for the Host-to-Host scenario. You can obtain this value from your manager or check it in the settings of your shop in the personal account. Typically, payway parameter has the prefix h2h. Example: bank_h2h_usd.

Example request for creating a payment

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
       }

In the response, Feennex returns the session ID in the session_id parameter. Save this identifier: you will need it in the following steps.

Example response

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

Step 2. Obtain token and URL address

To obtain a token, use the Data for HTML Form endpoint. In the request body, send the session identifier you received in the previous step in the session_id parameter.

Example request for obtaining the token

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

In the response, Feennex returns the form_token and payform_url parameters. Save them: you will need them for the next step.

Example response

{
   "data":{
      "form_token":"uerhdw47d748yd784dy83uhueh834h84dh84hd8dh8",
      "payform_url":"https://example.com/payform/"
   },
   "error_code":0,
   "message":"success",
   "result":true
}

Step 3. Make payment form

You need to collect the payer's bank card information and send a request to create an HTML form.

Collect payer's bank card details

Note: You must have a certificate compliant with the PCI DSS requirements.

On your side, you need to implement a page for entering the payer's bank card details. On this page, you will need to collect the following data:

Card validity date (year and month)
Three-digit CVV or CVC code
Card number
Name and surname of the cardholder

Send request to create HTML form

You need to send a POST request to create an HTML form. Send the request to the payform_url you received in the previous step. In the request body, include the payer's bank card details, form_token, and the session_id session identifier.

Example request to create the payment form:

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

In the response, Feennex returns an HTML form.

Step 4. Redirect payer to HTML form

Redirect the payer to the HTML form you received in the response on the previous step. The payer will be automatically directed to the 3D-secure page where they will be asked to enter the code.

If the payment is successful, Feennex will redirect the payer to the Success URL. If the payment fails or the code is incorrect, Feennex will redirect the payer to the Failed URL.

Payment via bank transfer

Payers will be able to transfer payment to a bank account using one of the following methods:

QR code — the payer sees a QR code, scans it, and follows the deep link to either the browser or the mobile banking app, if installed, to complete the transfer.
Card number — the payer sees the card number to which the transfer should be sent.

To integrate via API, you need to follow three steps:

Create a payment
Obtain transfer details
Request payment status

The interaction occurs asynchronously: after successfully creating the payment, you can immediately attempt to obtain transfer details.

Step 1. Create a payment

To create a payment, use the Create payment endpoint, but in the payway parameter, pass the value for the Host-to-Host scenario. You can get this value from your manager or check it in the settings of your shop in the personal account. Typically, it has the prefix h2h. For example, sbp_h2h_usd.

Example request for creating a payment

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
       }'

Response example

{
   "data":{
      "data":{},
      "id":123456789,
      "method":"sbp",
      "url":"bank"
   },
   "error_code":0,
   "message":"Ok",
   "result":true
}

Step 2. Obtain transfer details

After creating a payment, you need to obtain the transfer details. You must display this information to the payer on your payment page.

To obtain transfer details, use the Request payment status for other payment methods endpoint.

Note: If transfer details are not available, repeat the request later — transfer details are not assigned to the payment immediately.

Example request for obtaining transfer details

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 returns a standard response. The ps_data object contains the transfer details.

Note! In some cases Feennex can return a suggested amount in the suggested_amount parameter. Recommend that the payer transfers this suggested amount and inform them that this will decrease the time needed to process the payment.

Example of a message with a suggested transfer amount

You requested a payment of X but there are currently no bank requisites for that amount.

We recommend you to pay XX to procced with this transaction.

Example response

{
   "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,
         "suggested_amount": "1200",
         "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": 2,
      "updated": "2024-02-05 18:37:18"
   },
   "error_code": 0,
   "message": "Ok",
   "result": true
}

The ps_data object consists of the following parameters:

Parameter	Type	Description
amount	number	Amount that the payer should pay
suggested_amount	string	Suggested transfer amount. Recommend the payer to transfer this amount to decrease payment processing time.
bank	string	Name of the recipient bank. Returned if the `method` parameter has a value of `sbp`. Otherwise, it returns an empty value
card	string	Recipient's bank card number. Returned if the `method` parameter has a value of `bank`. Otherwise, it returns an empty value
card_holder_name	string	Name of the cardholder
currency	string	Currency of the transfer
expired	string	Time by which the payer should send the transfer. It is recommended to notify the payer about this
method	string	Payment method code. The possible values will be provided by your manager.
phone	string	Payer's phone number. Returned if the `method` parameter has a value of `sbp`. Otherwise, it returns an empty value
url	string	URL address to generate the QR code from. Returned if the `method` parameter has a value of `qr`. Otherwise, it returns an empty value

Step 3. Request payment status

After displaying the payment details, you can check the payment status: either periodically send a request or wait for a successful callback.

If you're sending a request, use the Request payment status for third-party payment systems endpoint.

In the Host-to-Host scenario, the statuses work the same way as when creating a payment request.

If the status parameter in the response returns the value 4, it means the payer has successfully made the payment and the funds have been credited to your shop. More about payment statuses

Example of a successful response

{
   "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
}

Self-developed integration (Host-to-Host scenario)​

Payment by bank card​

Step 1. Create payment​

Step 2. Obtain token and URL address​

Step 3. Make payment form​

Collect payer's bank card details​

Send request to create HTML form​

Step 4. Redirect payer to HTML form​

Payment via bank transfer​

Step 1. Create a payment​

Step 2. Obtain transfer details​

Step 3. Request payment status​

Self-developed integration (Host-to-Host scenario)

Payment by bank card

Step 1. Create payment

Step 2. Obtain token and URL address

Step 3. Make payment form

Collect payer's bank card details

Send request to create HTML form

Step 4. Redirect payer to HTML form

Payment via bank transfer

Step 1. Create a payment

Step 2. Obtain transfer details

Step 3. Request payment status