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.

How to obtain webhooks​

  1. In your system, create an address to receive webhooks at.
  2. 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​

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@131.ru"
        },
        "payment_details": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "8801",
            "bin": "220220",
            "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc"
          }
        },
        "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"
        }
      }
    ]
  }
}'

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 regular payouts

The webhook is disabled by default. To start receiving confirmation_payout webhooks, contact you 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. Note that 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. Possible 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 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​

NameMandatoryTypeDescription
type+stringWebhook type: payment_finished
session+objectPayment session
Example
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:

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": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "4242",
            "bin": "220220",
            "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc"
          }
        },
        "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​

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

This webhook 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​

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",
    "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",
            "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc"
          }
        },
        "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​

NameMandatoryTypeDescription
type+stringWebhook type: ready_to_confirm
session+objectPayment session
confirm_information- (mandatory only for the transactions with an escrow account)objectTransaction confirmation information
Example
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",
            "card_id": "05ee8cf7ee103444b384731d74b1b5c87fbb8f751fc3c452c9092fe1245bdc"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "amounts": {
          "fee": {
            "merchant_fee": {
              "amount": 10,
              "currency": "RUB"
            }
          }
        },
        "metadata": "good"
      }
    ]
  }
}'




Ask AI