Documentation

Documentation

  • Bank 131 API
  • Languages iconEnglish
    • Русский

›API Reference

131 Documentation

  • API features
  • Where to begin

Introduction to API

  • Interaction
  • API libraries
  • Testing
  • Version history

How Payouts Work

  • Features
  • How it all works
  • Main payout scenario
  • Payout refunds
  • The Self-employed

    • Payouts to the self-employed
    • Linking the self-employed
    • Fiscalization

    Payout Methods

    • To a Russian bank card
    • To a Russian bank account
    • To a QIWI Wallet
    • To a YooMoney (Yandex.Money)
    • To the Russian Federal Tax Agency
    • Via FPS by a phone number

    Payout Scenarios

    • Payout to a card via widget
    • Payout from a nominal account to a bank card
    • Single-request payout
    • Payout to a card with PCI DSS
    • Payout to a self-employed person with fiscal receipt

How Payments Work

  • Features
  • Payment process
  • Payments via bank card
  • Payments with later capture
  • Refunds
  • Recurring payments
  • Payments via FPS by QR code
  • Payments via Telegram

    • How to create your Telegram bot
    • How to connect your Telegram bot
    • How to setup your Telegram bot

    Split Payments

    • Features and options
    • Split payments out of the box
    • Split payments using API

    Payment Scenarios

    • Paying via payment form
    • Paying with PCI DSS
    • Single-request payment

Widgets

  • Widget to get card details
  • Payment form widget
  • Widget for linking a self-employed person to the Bank

Passport Verification

  • Features
  • Interaction
  • Methods

    • Verification request
    • Verification status
  • Response and errors

Reports

  • Payouts report
  • Payments report
  • Monthly report

API Reference

  • Objects
  • Methods
  • Webhooks
  • Error codes

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.

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+PaymentSessionThe payment session
confirm_information- (mandatory only for the trasactions with a nominal 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": "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"
                },
                "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": "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"
                },
                "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.

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": "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": "card",
                    "card": {
                        "last4": "4242",
                        "brand": "visa"
                    }
                },
                "amount_details": {
                    "amount": 10000,
                    "currency": "rub"
                },
                "metadata": "good"
            }
        ]
    }
}'

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": "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"
        },
        "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": "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"
                },
                "metadata": "good"
            }
        ]
    }
}'

payment_refunded

Bank 131 informs you of the result of a refund

Bank 131 sends this webhook to you after performing a refund. 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 method session/refund
  • the recipient's bank returned a payment sent to a Russian bank account.

Webhook parameters

NameMandatoryTypeDescription
type+stringThe hook's name. payment_refunded
session+PaymentSessionThe payment 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"
        },
        "metadata": "good",
        "refunds": [{
            "id": "rf_203",
            "status": "accepted",
            "created_at": "2018-05-27T02:03:00.000000Z",
            "finished_at": "2018-05-27T02:03:00.000000Z",
            "amount_details": {
                "amount": 1000,
                "currency": "rub"
            }
        }]
    }]
  }
}'
← MethodsError codes →
  • ready_to_confirm
  • payment_finished
  • action_required
  • ready_to_capture
  • payment_refunded
Documentation
Documentation
PayoutsPaymentsAPI ReferenceService documents
Step by step
Payout to a card via widgetPayout to a card with PCI DSSPayout to the self-employed Paying via payment form
Get in touch
Ideas and partnerships — partners@131.ruMedia — press@131.ru
© 2023 Bank 131