Skip to main content

Payouts from an escrow account with our widget or by token

You can make payouts from an escrow account to bank cards using a token or a hash instead of the card number. You can get a token/hash as follows:

The scope of PCI DSS requirements you must comply with depends on the method you choose. Before making a payout, identify the beneficiary.

How to enable a webhook to get notified on your escrow account top-ups >

Step 1. Get a public token​

A public token is required to connect the widget. Send a request to Bank 131 to create a token (token), specifying the widget type as tokenize_widget. The response will contain your public token.

Example of getting a public token
curl -X POST \
  http://demo.bank131.ru/api/v1/token \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "tokenize_widget": {
      "access": true
    }
  }'

Step 2. Initialize the widget on your site​

Initialize the widget on your site using the public token obtained in the previous step.

The payout recipient can then enter their bank card number into the data collection form.

Step 3. Create a payment session​

Create a session using the session/multi/create/nominal method. You will receive the payment session identifier in response. You will need it in the subsequent steps.

Alternatively, you can use the session/multi/init/payment/nominal method to create a session and a payout at the same time. In this case, specify all the parameters for a payout with the token or hash right away and skip the next step. This option is not recommended.

Creating a session
curl -X POST \
  https://demo.bank131.ru/api/v1/session/multi/create/nominal \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "metadata": "good"
  }'

Step 4. Start the payout​

Start the payout using the session/multi/start/payment/nominal method. Pass the session identifier along with all the parameters for a payout with the hash received from the widget.

info

You can find information on the hash or card through the token/info method. For example, you can get the last 4 digits of the card number to show the recipient which card the payout will be made to.

Payout example with the widget
curl -X POST \
  https://demo.bank131.ru/api/v1/session/multi/start/payment/nominal \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "session_id": "ps_3230",
    "payment_details": {
      "type": "internal_transfer",
      "internal_transfer": {
        "type": "transfer_from_nominal_account",
        "transfer_from_nominal_account": {
          "description": "Transfer under the offer agreement"
        }
      }
    },
    "payment_method": {
      "type": "card",
      "card": {
        "type": "encrypted_card",
        "encrypted_card": {
          "number_hash": "63191fa17cc7edf818ee5d6611a2c2169ab30b705111cffd710af39880deef09"
        }
      }
    },
    "participant_details": {
      "sender": {
        "full_name": "Vector LLC",
        "beneficiary_id": "1234567890"
      },
      "recipient": {
        "full_name": "Ivanov Ivan Ivanovich"
      }
    },
    "amount_details": {
      "amount": 10000,
      "currency": "rub"
    },
    "customer": {
      "reference": "123456789012"
    }
  }'

Step 5. Wait for a webhook saying the payout is ready​

Bank 131 will send you a ready_to_confirm webhook. This means that the payout can be performed and the Bank is waiting for you to confirm or cancel.

The webhook body will contain the confirm_information object. Save it, as you will need this object to confirm or cancel the transaction.

Webhook 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": "2025-05-14T09:32:20.099952Z",
      "updated_at": "2025-05-14T09:32:20.099911Z",
      "payments": [{
        "id": "po_7639847",
        "status": "pending",
        "created_at": "2025-05-14T09:32:20.099944Z",
        "customer": {
          "reference": "123456789012"
        },
        "payment_method": {
          "type": "card",
          "card": {
            "last4": "8371",
            "brand": "mastercard",
            "country_iso3": "RUS"
          }
        },
        "participant_details": {
          "sender": {
            "full_name": "Vector LLC",
            "beneficiary_id": "1234567890"
          },  
          "recipient": {
            "full_name": "Ivanov Ivan Ivanovich"
          }
        }
      }],
      "acquiring_payments": [{
        "id": "pm_6933973",
        "status": "pending",
        "created_at": "2025-05-14T09:32:20.099966Z",
        "customer": {
          "reference": "123456789012"
        },
        "payment_details": {
          "type": "internal_transfer",
          "internal_transfer": {
            "type": "transfer_from_nominal_account",
            "transfer_from_nominal_account": {
              "description": "Transfer under the offer agreement",
              "card_mask": "553691******8371"
            }
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "participant_details": {
          "sender": {
            "full_name": "Vector LLC",
            "beneficiary_id": "1234567890"
          },
          "recipient": {
            "full_name": "Ivanov Ivan Ivanovich"
          }
        }
      }],
      "next_action": "confirm"
    },
    "confirm_information": {
      "transfer_details": {
        "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 under the offer agreement",
        "amount": {
          "amount": 10000,
          "currency": "rub"
        }
      }
    }
  }'

Step 6. Confirm or cancel the payout​

Check the payout details and confirm (session/confirm) or cancel (session/cancel) the payout passing the confirm_information object.

Confirming the session
curl -X POST \
  https://demo.bank131.ru/api/v1/session/confirm \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "session_id": "ps_3230",
    "confirm_information": {
      "transfer_details": {
        "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 under the offer agreement",
        "amount": {
          "amount": 10000,
          "currency": "rub"
        }
      }
    }
  }'
Canceling the session
curl -X POST \
  https://demo.bank131.ru/api/v1/session/cancel \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "session_id": "ps_3230",
    "confirm_information": {
      "transfer_details": {
        "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 under the offer agreement",
        "amount": {
          "amount": 10000,
          "currency": "rub"
        }
      }
    }
  }'

Step 7. Wait for a webhook with the payout results​

Bank 131 will send you a payment_finished webhook. The result of the payout can be found in the status field of the payments/payout_list array.

If the status is succeeded, then the payout was successful. If the status is failed, then an error occurred during the payout.

More about the payout statuses >

View error codes >