---
name: bank131-webhooks
description: Use when the user asks about Bank 131 webhooks: what webhook types the Bank sends (`action_required`, `ready_to_confirm`, `ready_to_capture`, `payment_finished`, `payment_refunded`, `confirmation_payout`, `nominal_topup`), how to set up receiving webhooks and provide the URL to the Bank, responding with HTTP 200 OK, webhook retry policy and retry intervals, webhook sender IP addresses, verifying the Bank's webhook signature, 3D Secure redirects and `customer_interaction`, delayed payments (capture and cancel), session auto-confirmation, chargeback and the `is_chargeback` flag, the FNS receipt in webhooks, fiscalization, escrow account top-ups, BESP payouts, and the `session/status` alternative when webhooks are disabled.
---

### How to receive webhooks

- Create a URL in your system that will receive webhooks and provide it to your Bank 131 manager.
- If the option is enabled, you will receive all connected webhooks. Selective webhook configuration is not possible.
- If webhooks are disabled, send a session/status request each time to understand the next step and the result of the operation.
- Webhooks can also deliver information about the commission applied to an operation. To enable this, contact your Bank 131 manager.

Webhooks are sent from these IP addresses: `84.201.171.246` and `84.252.136.174`.

### Responding to webhooks

- Reply to every webhook with HTTP code 200.
- If the Bank receives a 4xx or 5xx code, or no response at all, it retries the webhook at increasing intervals that never exceed 15 minutes.
- The Bank stops retrying 30 minutes after the first attempt.
- The webhook fields may expand over time depending on the payment methods used. Make sure this does not break your service.

### Verifying the Bank's signature

- Bank 131 signs all webhooks using its secret key.
- Verify the signature with the Bank's public key and the SHA-256 algorithm; the signature is transmitted in Base64 in the `X-PARTNER-SIGN` header.
- Save the Bank's public key in the PEM format (separately for live and for demo testing).

### Types of webhooks

Bank 131 sends these webhook types:

- `action_required` — the Bank needs additional actions from you or your users (for example, 3D Secure authentication for a card payment). The maximum waiting time is 60 minutes; if no action happens, the operation is automatically canceled.
- `ready_to_confirm` — the Bank is ready to perform the operation (payout or payment). Check the operation parameters, then confirm with session/confirm or cancel with session/cancel. The maximum waiting time is 240 minutes. Auto-confirmation can be configured — contact your manager.
- `ready_to_capture` — the money is frozen. Send session/capture to debit it or session/cancel to cancel the payment. For delayed payments, the Bank always sends this webhook before debiting.
- `payment_finished` — the operation (payout or payment) is finished. The result is in the status field; `succeeded` means success. The receipt parameter contains the FNS receipt ID and a link to it.
- `payment_refunded` — a refund has been completed. Sent after session/refund, when the recipient bank returns a payout, or during a chargeback. In a chargeback, the refunds array contains `"is_chargeback": true`.
- `confirmation_payout` — funds have been credited to the recipient's account (BESP payouts) or the transfer was accepted by the Central Bank (regular payouts). Disabled by default — contact your manager to enable it.
- `nominal_topup` — funds were credited to your escrow account. It contains the credited amount and the new account balance (amounts are in minor units: 100 rubles = 10000).

### Webhook examples

Webhooks are sent as POST requests to your URL with the `X-PARTNER-SIGN` header.

`payment_finished` (operation result):

```json
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",
      "payments": [{
        "id": "po_2018",
        "status": "succeeded",
        "payment_method": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "4242"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        }
      }]
    }
  }'
```

`ready_to_confirm` (the Bank waits for your confirmation):

```json
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",
      "next_action": "confirm",
      "payments": [{
        "id": "po_2018",
        "status": "pending",
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        }
      }]
    }
  }'
```

`action_required` (additional actions needed, for example 3D Secure):

```json
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",
      "acquiring_payments": [{
        "id": "pm_131",
        "status": "pending",
        "customer_interaction": {
          "type": "redirect",
          "redirect": {
            "url": "https://bank131.ru?foo=bar",
            "method": "POST"
          }
        }
      }]
    }
  }'
```