Webhooks

Webhooks are notifications about events happening on Bank 131's side. The Bank sends webhooks to inform you of the results of your operations, ask for confirmation, or alert you about actions you need to take. Also, webhooks can include information on the applicable transaction fee. To enable this functionality, please contact your Bank 131 manager.

How to obtain webhooks

In your system, create an address to receive webhooks at.
Inform your Bank 131 manager of this address.

What to send in response

Bank 131 waits for you to send the 200 HTTP code in response to any webhook.

If the Bank receives a 4** or 5** code, the request will be resent repeatedly at intervals of increasing length until it gets a response.

`action_required`

The Bank is waiting for you or your users to take the necessary action

The Bank sends this webhook to you when you or your users need to carry out certain actions to proceed with the operation. For example, a user might need to go through 3D Secure authentication when paying via bank card.

Webhook parameters

Name	Mandatory	Type	Description
type	+	string	Webhook type: `action_required`
session	+	object	Payment session

Webhook example: action_required

curl -X POST \
https://partner.ru \
-H 'content-type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "type": "action_required",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "acquiring_payments": [
      {
        "id": "pm_131",
        "status": "pending",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user@131.ru"
        },
        "payment_details": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "8801",
            "bin": "220220"
          }
        },
        "amount_details": {
          "amount": 15000,
          "currency": "rub"
        },
        "amounts": {
          "fee": {
            "merchant_fee": {
              "amount": 10,
              "currency": "RUB"
            }
          }
        },
        "customer_interaction": {
          "type": "redirect",
          "redirect": {
            "url": "https://bank131.ru?foo=bar",
            "base_url": "https://bank131.ru",
            "method": "POST",
            "qs": {
              "foo": "bar"
            },
            "params": {
              "PaReq": "sdfew^//asdhbv",
              "MD": "abc75daefnn"
            }
          }
        },
        "transaction_info": {
          "rrn": "425307614918",
          "auth_code": "057441"
        }
      }
    ]
  }
}'

`nominal_topup`

Bank 131 informs you when your escrow account is replenished

Bank 131 sends this webhook every time funds are added to your escrow account as a result of any internal or bank-to-bank transaction. The webhook body includes information on the amount of added funds and the new balance of your account.

Note that you can give the Bank manager any address to which you would like to receive these notifications.

Webhook parameters

Name	Mandatory	Type	Description
inn	+	string	Recipient`s INN
kpp	-	string	Recipient`s KPP
account_number	+	string	Replenished account number
account_balance	+	int	Current account balance (Amount in minor currency units. For 100 rubles, `10000` is passed)
doc_id	+	string	Document identifier
doc_num	+	string	Document number
amount	+	int	Payment amount (Amount in minor currency units. For 100 rubles, `10000` is passed)
currency	+	string	Payment currency code according to ISO 4217
paymentDate	+	date	Payment date and time according to ISO 8601
purpose	-	string	Payment purpose
contragent_name	-	string	Sender's name
contragent_inn	-	string	Sender's INN
contragent_kpp	-	string	Sender's KPP
contragent_account_number	+	string	Sender's account number
contragent_bank_bik	+	string	Sender's bank BIK
contragent_bank_name	-	string	Sender's bank name

Webhook example: nominal_topup

curl -X POST \
https://partner.ru \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "inn": "3316004790",
  "kpp": "156605101",
  "account_number": "40702810600200000014",
  "account_balance": 518619720,
  "doc_id": "2080040124641368",
  "doc_num": "333",
  "amount": 66660,
  "currency": "810",
  "paymentDate": "2023-07-27T20:04:36.807000+03:00",
  "purpose": "Escrow account replenishment for 5896.60 rubles",
  "contragent_name": "Vector LTD",
  "contragent_inn": "1655415696",
  "contragent_kpp": "165501001",
  "contragent_account_number": "30110810800000000593",
  "contragent_bank_bik": "049205131",
  "contragent_bank_name": "Bank 131"
}'

`payment_finished`

The Bank informs you of the result of an operation

The Bank sends this webhook to you when it has completed an operation (a payment or a payout). The webhook body contains all the details of the operation, including its status (in the status field). For example, if you are sending a payout and have received the succeeded status in this webhook, it means that the payout has been completed successfully.
Also, the webhook body contains information on the Federal Tax Service receipt in the receipt parameter: its identifier and a link to download it. Click the link to download the receipt.

Webhook parameters

Name	Mandatory	Type	Description
type	+	string	Webhook type: `payment_finished`
session	+	object	Payment session

Webhook example: payment_finished

curl -X POST \
https://partner.ru \
-H 'content-type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "type": "payment_finished",
  "session": {
    "id": "ps_3230",
    "status": "accepted",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "payments": [
      {
        "id": "po_2018",
        "status": "succeeded",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [
            {
              "email": "user@gmail.com"
            }
          ]
        },
        "payment_method": {
          "type": "bank_account",
          "bank_account": {
            "system_type": "ru",
            "ru": {
              "bic": "*******02",
              "account": "****************5734",
              "full_name": "***",
              "description": "*****",
              "is_fast": false
            }
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "amounts": {
          "fee": {
            "merchant_fee": {
              "amount": 10,
              "currency": "RUB"
            }
          }
        },
        "fiscalization_details": {
          "professional_income_taxpayer": {
            "services": [
              {
                "name": "****",
                "amount_details": {
                  "amount": "10000",
                  "currency": "rub"
                },
                "quantity": 1
              }
            ],
            "tax_reference": "*********628",
            "receipt": {
              "id": "**********",
              "link": "https://lknpd.nalog.ru/api/v1/receipt/*****/print"
            },
            "payer_type": "foreign",
            "payer_name": "******"
          }
        },
        "transaction_info": {
          "rrn": "425307614918",
          "auth_code": "057441"
        }
      }
    ]
  }
}'

`payment_refunded`

Bank 131 informs you of the result of a refund

Bank 131 will send you this webhook after a refund is performed. The notification parameters contain information about the payment session, including all the information about the refunds.

The webhook is sent in the following cases:

you made a refund using the session/refund method,
the recipient's bank returned your payment sent to a Russian bank account,
within the chargeback procedure.

If the return is made within the chargeback procedure, the refunds object contains the following additional line: "is_chargeback": true.

Webhook parameters

Name	Mandatory	Type	Description
type	+	string	Webhook type: `payment_refunded`
session	+	object	Payment session

Webhook example: payment_refunded

curl - X POST\
https: //partner.ru \
-H 'Content-Type: application/json'\ -
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "type": "payment_refunded",
  "session": {
    "id": "ps_3230",
    "status": "accepted",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "acquiring_payments": [
      {
        "id": "pm_2705",
        "status": "succeeded",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "finished_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_details": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "4242",
            "bin": "220220"
          }
        },
        "amount_details": {
          "amount": 1000,
          "currency": "rub"
        },
        "amounts": {
          "fee": {
            "merchant_fee": {
              "amount": 10,
              "currency": "RUB"
            }
          }
        },
        "transaction_info": {
          "rrn": "425307614919",
          "auth_code": "057441"
        },
        "metadata": "good",
        "refunds": [
          {
            "id": "rf_203",
            "status": "accepted",
            "created_at": "2018-05-27T02:03:00.000000Z",
            "finished_at": "2018-05-27T02:03:00.000000Z",
            "is_chargeback": true,
            "amount_details": {
              "amount": 1000,
              "currency": "rub"
            },
            "transaction_info": {
              "rrn": "425307614918",
              "auth_code": "057441"
            }
          }
        ]
      }
    ]
  }
}'

`ready_to_capture`

The Bank informs you that the money has been put on hold

Bank 131 sends this webhook to you when putting money on hold, after the first step of a payment performed in two stages. This means that the amount has been put on hold successfully, and the Bank is waiting for your next command. To debit the money, send a (session/capture) request. To cancel the payment, send a (session/cancel) request.

Webhook parameters

Name	Mandatory	Type	Description
type	+	string	Webhook type: `ready_to_capture`
session	+	object	Payment session

Webhook example: ready_to_capture

curl -X POST \
https://partner.ru \
-H 'content-type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "type": "ready_to_capture",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "acquiring_payments": [
      {
        "id": "pm_2018",
        "status": "pending",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [
            {
              "email": "user@gmail.com"
            }
          ]
        },
        "payment_details": {
          "type": "card",
          "card": {
            "last4": "4242",
            "brand": "visa"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "amounts": {
          "fee": {
            "merchant_fee": {
              "amount": 10,
              "currency": "RUB"
            }
          }
        },
        "metadata": "good"
      }
    ]
  }
}'

`ready_to_confirm`

The Bank is waiting for your confirmation to perform the operation

Bank 131 sends this webhook when it is ready to perform an operation (a payment or a payout). You need to check the operation parameters and make a decision. If everything looks good, confirm the operation by sending a (session/confirm) to Bank 131. If something is not right, cancel the operation by sending a (session/cancel) to Bank 131.

Webhook parameters

Name	Mandatory	Type	Description
type	+	string	Webhook type: `ready_to_confirm`
session	+	object	Payment session
confirm_information	- (mandatory only for the transactions with an escrow account)	object	Transaction confirmation information

Webhook examples: ready_to_confirm

Payout confirmation
Performing a payment

curl -X POST \
https://partner.ru \
-H 'content-type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "type": "ready_to_confirm",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "next_action": "confirm",
    "payments": [
      {
        "id": "po_2018",
        "status": "pending",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [
            {
              "email": "user@gmail.com"
            }
          ]
        },
        "payment_method": {
          "type": "card",
          "card": {
            "last4": "4242",
            "brand": "visa"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "amounts": {
          "fee": {
            "merchant_fee": {
              "amount": 10,
              "currency": "RUB"
            }
          }
        },
        "metadata": "good"
      }
    ]
  }
}'

curl -X POST \
https://partner.ru \
-H 'content-type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "type": "ready_to_confirm",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "acquiring_payments": [
      {
        "id": "pm_2018",
        "status": "pending",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [
            {
              "email": "user@gmail.com"
            }
          ]
        },
        "payment_details": {
          "type": "card",
          "card": {
            "last4": "4242",
            "brand": "visa"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "amounts": {
          "fee": {
            "merchant_fee": {
              "amount": 10,
              "currency": "RUB"
            }
          }
        },
        "metadata": "good"
      }
    ]
  }
}'

`transaction_registration`

Processing a successful payout

When the transferred funds are successfully paid out abroad, the Bank will send the payment partner a transaction_registration webhook to which the partner must send a response.
The webhook will contain the following essential information:

the parent session within which the funds were accepted (session_payment_id)
the payout session (current) within which the funds were paid out (session_id)
the amount paid out

If required, the payment partner can deactivate this webhook. To do this, please contact your Bank 131 manager.

Webhook parameters

Name	Mandatory	Type	Description
session_payment_id	+	string	Payment session ID
session	+	object	Session details
id	+	string	Payout session ID
status	+	string	Current session status. The available values
created_at	+	string	Session creation date and time in the RFC 3339 format. Example: `2022-11-15T15:38:50.255803Z`
updated_at	+	string	Session update date and time in the RFC 3339 format. Example: `2022-11-15T15:38:50.255803Z`
error	-	object	Error details. Returned only if an error occurred
description	-	string	Error description
code	-	string	Error code
payments	+	array	Payment details
id	+	string	Payment ID
status	+	string	Current payment status. The available values
created_at	+	string	Payment creation date and time in the RFC 3339 format. Example: `2022-11-15T15:38:50.255803Z`
finished_at	-	string	Payment finalization date and time in the RFC 3339 format. Example: `2022-11-15T15:38:50.255803Z`
payment_method	+	object	Payment method
type	+	string	Payment method name. Valid value: `moneysend`
amount_details	+	object	`amount_details` object sent in the request
amount	+	float	Amount in minor values
currency	+	string	Currency
paymentMetadata	-	object	Additional metadata
parentSessionId	-	string	Payment session ID
participant_details	+	object	Information on the sender and recipient. The object is guaranteed. All the keys and nested objects are not guaranteed
sender	-	object	Sender details. The object is guaranteed. All the keys and nested objects are not guaranteed
recipient	-	object	Recipient details. The object is guaranteed. All the keys and nested objects are not guaranteed
error	-	object	Transaction error details. Returned only if an error occurred
description	-	string	Error description
code	-	string	Error code

Webhook example: transaction_registration

{
  "session_payment_id": "ps_949108",
  "session": {
    "id": "ps_949139",
    "status": "accepted",
    "created_at": "2023-03-03T15:00:05.864870Z",
    "updated_at": "2023-03-03T15:00:06.307414Z",
    "payments": [
      {
        "id": "po_231420",
        "status": "succeeded",
        "created_at": "2023-03-03T15:00:05.948271Z",
        "finished_at": "2023-03-03T15:00:06.136321Z",
        "payment_method": {
          "type": "moneysend",
          "moneysend": {}
        },
        "amount_details": {
          "amount": 143000,
          "currency": "USD"
        },
        "paymentMetadata": {
          "parentSessionId": "ps_949108"
        },
        "participant_details": {
          "sender": {
            "full_name": "Анастасия Медынич Олеговна",
            "first_name": "Анастасия",
            "last_name": "Медынич",
            "middle_name": "Олеговна",
            "country_iso3": "RUS",
            "city": "Стерлитамак",
            "postal_code": "",
            "building": "1",
            "date_of_birth": "1994-01-06",
            "street": "Конаковская",
            "state": "Республика Башкортостан",
            "description": "описание описания",
            "identity_document": {
              "id_type": "Паспорт гражданина Российской Федерации",
              "id_number": "6916 706690",
              "issue_date": "2020-01-01",
              "division_code": "",
              "issued_by": "ОВД ПО Кировскому району"
            },
            "citizenship_country_iso3": "RUS",
            "service_point": {
              "id": "1",
              "name": "точка на Ленина",
              "country_iso3": "RUS",
              "state": "Москва",
              "city": "Москва",
              "street": "Ленина",
              "house": "1",
              "oktmo": "36634436111",
              "terminal_id": "345"
            },
            "source_of_money": "зарплата",
            "contacts": {
              "phone": {
                "full_number": "+79376151530",
                "country_iso3": "RUS",
                "operator_code": "937",
                "short_number": "6151530"
              }
            }
          },
          "recipient": {
            "full_name": "Ivan Olegov Sergeevich",
            "first_name": "Ivan",
            "last_name": "Olegov",
            "middle_name": "Sergeevich",
            "date_of_birth": "1987-11-08",
            "currency": "USD",
            "contacts": {
              "phone": {
                "full_number": "+43523452345",
                "country_iso3": "TUR",
                "operator_code": "352",
                "short_number": "3452345"
              }
            }
          }
        }
      }
    ]
  }
}

How to obtain webhooks​

What to send in response​

action_required​

The Bank is waiting for you or your users to take the necessary action​

Webhook parameters​

nominal_topup​

Bank 131 informs you when your escrow account is replenished​

Webhook parameters​

payment_finished​

The Bank informs you of the result of an operation​

Webhook parameters​

payment_refunded​

Bank 131 informs you of the result of a refund​

Webhook parameters​

ready_to_capture​

The Bank informs you that the money has been put on hold​

Webhook parameters​

ready_to_confirm​

The Bank is waiting for your confirmation to perform the operation​

Webhook parameters​

transaction_registration​

Processing a successful payout​

Webhook parameters​

How to obtain webhooks

What to send in response

`action_required`

The Bank is waiting for you or your users to take the necessary action

Webhook parameters

`nominal_topup`

Bank 131 informs you when your escrow account is replenished

Webhook parameters

`payment_finished`

The Bank informs you of the result of an operation

Webhook parameters

`payment_refunded`

Bank 131 informs you of the result of a refund

Webhook parameters

`ready_to_capture`

The Bank informs you that the money has been put on hold

Webhook parameters

`ready_to_confirm`

The Bank is waiting for your confirmation to perform the operation

Webhook parameters

`transaction_registration`

Processing a successful payout

Webhook parameters