Skip to main content

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.

info

If the webhooks are disabled, you will need to send a session/status request each time to understand the next step and the operation result.

How to get webhooks​

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

If the option is enabled, you will receive all enabled webhooks (selective webhook delivery cannot be set up).

IP addresses our webhooks arrive from: 84.201.171.246 and 84.252.136.174.

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 or no response at all, it will resend the webhook repeatedly at increasing intervals. Here is how it works:

  • The interval between resends increases progressively, but never exceeds 15 minutes.
  • After 30 minutes, Bank 131 stops sending the webhook.

How to process webhooks with the SDK​

To handle webhooks in PHP, use the PHP SDK library. The handleWebHook method automatically verifies the signature and converts the JSON into a $hook object containing the webhook type (getType()) and session data (getSession()).

IMPORTANT!

The set of fields in the webhook may expand over time depending on the payment methods used. Make sure it does not break your service.

action_required​

The Bank is waiting for additional actions from you or your users​

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.

The waiting time for an action depends on the transaction type and current settings. For example, the waiting time for 3DS confirmation for card payments is 20 minutes, while the QR code lifetime for payments via FPS can vary from 5 to 60 minutes. If the action is not performed within the set time, the operation is automatically completed with the cancelled status.

Webhook parameters​

NameMandatoryTypeDescription
type+stringWebhook type: action_required
session+objectPayment session
Example
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@gmail.com"
        },
        "payment_details": {  // content depends on the payment method
          "type": "card",
          "card": {
            "last4": "4940",
            "brand": "mir",
            "bin": "220024",
            "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc"
          }
        },
        "amount_details": {
          "amount": 15000,
          "currency": "rub"
        },
        "amounts": { 
          "fee": {
            "merchant_fee": {
              "amount": 10,
              "currency": "RUB"
            }
          }
        },
        "customer_interaction": { // content depends on the payment method and provider
          "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"
            }
          }
        },
        "payment_options": {
          "recurrent": false
        },
        "metadata": "good"
      }]
    }
  }'

confirmation_payout​

Bank 131 informs you when money is successfully deposited into the account at the recipient bank​

The Bank sends you this webhook, specifying the date and time of the funds' deposit, in the following cases:

  • funds delivered to the recipient's account—for payouts through BESP
  • transfer accepted by the Central Bank (i.e., the funds have been debited from Bank 131's account and sent to the recipient's bank account)—for non-speedy payouts

This webhook is disabled by default. To start receiving confirmation_payout webhooks, contact your Bank 131 manager.

The webhook can arrive within up to 7 business days from the transaction date. The webhook may not be received if the recipient bank fails to provide confirmation. This does not affect the actual deposit of funds into the recipient's account. The payout can be refunded after you receive the webhook.

Webhook parameters​

NameMandatoryTypeDescription
type+stringWebhook type: confirmation payout
event+stringPayout receipt type. Options:
- Payout accepted Central Bank
- Funds credited recipient's account
event_date+datePayout receipt date and time according to ISO 8601
transaction_id+stringUnique transaction identifier
session_id+stringUnique session identifier
Example
curl -X POST \
  https://partner.ru \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "type":"confirmation_payout",
    "event":"Funds credited recipient's account",
    "event_date":"2024-11-27T02:03:00.000000Z",
    "transaction_id":"po_2018",
    "session_id":"ps_3230"
  }'

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​

NameMandatoryTypeDescription
inn+stringRecipient's INN
kpp-stringRecipient's KPP
account_number+stringReplenished account number
account_balance+intCurrent account balance (Amount in minor currency units. For 100 rubles, 10000 is passed)
doc_id+stringDocument identifier
doc_num+stringDocument number
amount+intPayment amount (Amount in minor currency units. For 100 rubles, 10000 is passed)
currency+stringPayment currency code according to ISO 4217
paymentDate+datePayment date and time according to ISO 8601
purpose-stringPayment purpose
contragent_name-stringSender's name
contragent_inn-stringSender's INN
contragent_kpp-stringSender's KPP
contragent_account_number+stringSender's account number
contragent_bank_bik+stringSender's bank BIK
contragent_bank_name-stringSender's bank name
Example
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 LLC",
    "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 when it completes 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 receive the succeeded status in this webhook, it means that the payout has been completed successfully.

Webhook parameters​

NameMandatoryTypeDescription
type+stringWebhook type: payment_finished
session+objectPayment session
Examples
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",
        "finished_at": "2018-05-27T02:03:00.000000Z",
        "payment_method": {  // content depends on the payment method
          "type": "bank_account",
          "bank_account": {
            "system_type": "ru",
            "ru": {
              "bik": "*******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": {  // only for payouts to self-employed persons
          "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"
        }
      }],
      "actions": {
        "confirm": "2018-05-27T02:03:00.000000Z"
      }
    }
  }'

payment_refunded​

Bank 131 informs you of the result of a refund​

Bank 131 sends you this webhook after a refund is performed. The notification parameters contain information about the payment session, which includes information about the refunds.

The webhook is sent in the following cases:

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

Webhook parameters​

NameMandatoryTypeDescription
type+stringWebhook type: payment_refunded
session+objectPayment session
Example
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": {  // content depends on the payment method
          "type": "card",
          "card": {
            "last4": "4940",
            "brand": "mir",
            "bin": "220024",
            "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc"
          }
        },
        "amount_details": {
          "amount": 1000,
          "currency": "rub"
        },
        "amounts": {
          "fee": {
            "merchant_fee": {
              "amount": 10,
              "currency": "RUB"
            }
          }
        },
        "transaction_info": {
          "rrn": "425307614919",
          "auth_code": "057862"
        },
        "payment_options": {
          "recurrent": false
        },
        "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"
          },
          "metadata": {
            "internal_refund_id": "rf_123"
          },
          "amounts": {  // commission is not refunded
            "fee": {
              "merchant_fee": {
                "amount": 0,
                "currency": "RUB"
              }
            }
          },
          "transaction_info": {
            "rrn": "425307614918",
            "auth_code": "057441"
          }
        }]
      }],
      "actions": {
        "confirm": "2018-05-27T02:03:00.000000Z",
        "capture": "2018-05-27T02:03:00.000000Z"
      }
    }
  }'

ready_to_capture​

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

If you work with delayed capture payments, Bank 131 will always send you this webhook before debiting funds.

The webhook means that the amount has been successfully put on hold, and the Bank is waiting for your command. To debit the money, send a (session/capture) request. To cancel the payment, send a (session/cancel) request.

Webhook parameters​

NameMandatoryTypeDescription
type+stringWebhook type: ready_to_capture
session+objectPayment session
Example
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",
      "next_action": "capture",
      "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": {  // content depends on the payment method
          "type": "card",
          "card": {
            "last4": "4940",
            "brand": "mir",
            "bin": "220024",
            "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "amounts": { 
          "fee": {
            "merchant_fee": {
              "amount": 10,
              "currency": "RUB"
            }
          }
        },
        "payment_options": {
          "recurrent": false
        },
        "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) request to the Bank. If something is wrong, cancel the operation by sending a (session/cancel) request.

The maximum waiting time for a confirmation is 240 minutes. If no confirmation is received within this time, the operation will automatically be completed with the cancelled status.

You can set up automatic confirmation of the payment session—in this case, ready_to_confirm will not be sent. To configure the automatic confirmation, contact your Bank 131 manager.

info

This webhook is mandatory when the operation requires the confirm_information object: for payouts from a settlement or escrow account, and for money transfers.

Webhook parameters​

NameMandatoryTypeDescription
type+stringWebhook type: ready_to_confirm
session+objectPayment session
confirm_information- (mandatory for transactions with a settlement or escrow account, and money transfers)objectInformation for confirming the transaction
Examples
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": "2025-09-14T09:32:19.891392Z",
      "updated_at": "2025-09-14T09:32:20.494410Z",
      "payments": [{
        "id": "po_7639847",
        "status": "pending",
        "created_at": "2025-09-14T09:32:20.100149Z",
        "customer": {
          "reference": "123456789012"
        },
        "payment_method": {  // content depends on the payment method
          "type": "card",
          "card": {
            "brand": "mir",
            "last4": "4940",
            "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc"
          }
        },
        "amount_details": {
          "amount": 293400,
          "currency": "RUB"
        },
        "amounts": {
          "fee": {
            "merchant_fee": {
              "amount": 10,
              "currency": "RUB"
            }
          }
        },
        "participant_details": {
          "sender": {
            "full_name": "Vector LLC",
            "beneficiary_id": "1234567890"
          },
          "recipient": {
            "full_name": "Ivanov Ivan Ivanovich"
          }
        }
      }],
      "acquiring_payments": [{  // for payouts to an escrow or settlement account
        "id": "pm_6933973",
        "status": "pending",
        "created_at": "2025-09-14T09:32:20.099952Z",
        "customer": {
          "reference": "123456789012"
        },
        "payment_details": {  // content depends on the payment method
          "type": "internal_transfer",
          "internal_transfer": {
            "type": "transfer_from_nominal_account",
            "transfer_from_nominal_account": {
              "description": "Transfer in accordance with the offer",
              "card_mask": "553691******8371"
            }
          }
        },
        "amount_details": {
          "amount": 293400,
          "currency": "RUB"
        },
        "amounts": {
          "fee": {
            "merchant_fee": {
              "amount": 10,
              "currency": "RUB"
            }
          }
        },
        "participant_details": { // for payouts to an escrow or settlement account
          "sender": {
            "full_name": "Vector LLC",
            "beneficiary_id": "1234567890"
          },
          "recipient": {
            "full_name": "Ivanov Ivan Ivanovich"
          }
        }
      }],
      "next_action": "confirm"
    },
    "confirm_information": {  // for payouts from an escrow or settlement account
      "transfer_details": {
        "payment_method": {  // content depends on the payment method
          "type": "card",
          "card": {
            "brand": "mastercard",
            "last4": "8371",
            "country_iso3": "RUS"
          }
        },
        "customer": {
          "account_number": "40702810700200000000",
          "name": "Vector LLC",
          "bank_name": "Bank 131",
          "bik": "049205131",
          "correspondent_account_number": "30101810822000000000"
        },
        "recipient": {
          "account_number": "30233810000000000000",
          "name": "Ivanov Ivan Ivanovich",
          "bank_name": "Bank 131",
          "bik": "049205123",
          "correspondent_account_number": "30101810822000000974"
        },
        "purpose": "Transfer in accordance with the offer",
        "amount": {
          "amount": 293400,
          "currency": "RUB"
        }
      }
    }
  }'