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.
  3. Let your manager know which webhooks you will need (this depends on how you'll be using the API). By default, you will only receive mandatory webhooks.

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.

ready_to_confirm​

The bank is waiting for your confirmation to perform the operation (mandatory)​

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 confirm_request to Bank 131. If something is not right, cancel the operation by sending a cancel_request to Bank 131.

Notification parameters​

NameMandatoryTypeDescription
type+stringWebhook type: ready_to_confirm
session+PaymentSessionPayment session
confirm_information- (mandatory only for the transactions with an escrow account)ConfirmInformationTransaction confirmation information

Webhook example: using ready_to_confirm to confirm a payout​

curl -X POST \
  https://partner.ru \
  -H 'content-type: application/json' \
  -H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
  -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": "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"
            }
        ]
    }
}'

Webhook example: using ready_to_confirm to perform a payment​

curl -X POST \
  https://partner.ru \
  -H 'content-type: application/json' \
  -H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
  -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": "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"
            }
        ]
    }
}'

payment_finished​

The Bank informs you of the result of an operation (mandatory)​

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.

Notification parameters​

NameMandatoryTypeDescription
type+stringWebhook type: payment_finished
session+PaymentSessionThe payment session

Webhook example: payment_finished​

curl -X POST \
  https://partner.ru \
  -H 'content-type: application/json' \
  -H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
  -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": "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": "******"
          }
        }
      }
      ]
  }
}'

action_required​

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

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

Webhook parameters​

NameMandatoryTypeDescription
type+stringWebhook type: action_required
session+PaymentSessionThe payment session

Webhook example: action_required​

curl -X POST \
  https://partner.ru \
  -H 'content-type: application/json' \
  -H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
  -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": "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"
          }
        },
        "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"
            }
          }
        }
      }]
    }
  }
}'

ready_to_capture​

The bank informs you that the money has been put on hold (optional)​

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 the session/capture request. To cancel the payment, send the session/cancel request.

Webhook parameters​

NameMandatoryTypeDescription
type+stringWebhook type: ready_to_capture
session+PaymentSessionThe payment session

Webhook example: ready_to_capture​

curl -X POST \
  https://partner.ru \
  -H 'content-type: application/json' \
  -H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
  -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": "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"
            }
        ]
    }
}'

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, 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+stringHook's name. payment_refunded
session+PaymentSessionPayment session

Webhook example: payment_refunded​

curl - X POST\
https: //partner.ru \
    -H 'Content-Type: application/json'\ -
    H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc'\ -
    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"
            }
        },
        "amount_details": {
            "amount": 1000,
            "currency": "rub"
        },
        "amounts": {
          "fee": {
            "merchant_fee": {
              "amount": 10,
              "currency": "RUB"
            }
          }
        },
        "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"
            }
        }]
    }]
  }
}'

nominal_topup​

Bank 131 informs you when your escrow account is replenished (optional)​

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. If the amount is 100 rubles, 10000 is passed)
payment+PaymentPayment details
abs_doc_id+stringDocument identifier
abs_doc_num+stringDocument number
amount+stringPayment amount (Amount in minor currency units. If the amount is 100 rubles, 10000 is passed)
currency+stringPayment currency code according to ISO 4217
payment_date+datePayment date and time according to ISO 8601
purpose-stringPayment purpose
contragent+ContragentPayment sender information
name-stringSender's name
inn-stringSender's INN
kpp-stringSender's KPP
account_number+stringSender's account number
bank_bik+stringSender's bank BIK
bank_name-stringSender's bank name

Webhook example: nominal_topup​

curl -X POST \
  https://partner.ru \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-SIGN: a4f1698616d6ad7b8b73a9d72d281eeb443b64dee3f38df430eeed6aa29e1dc' \
  -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": "Roga i Kopita LTD",
    "contragent_inn": "1655415696",
    "contragent_kpp": "165501001",
    "contragent_account_number": "30110810800000000593",
    "contragent_bank_bik": "049205131",
    "contragent_bank_name": "Bank 131"
}'