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

    Payout Methods

    • To a Russian bank card
    • To a foreign bank card
    • To a Russian bank account
    • To a QIWI Wallet
    • To a YooMoney (Yandex.Money)
    • To the Russian Federal Tax Agency

    Payout Scenarios

    • Payout to a card via widget
    • 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
  • 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
  • Verification request
  • Verification status
  • HTTP codes

Reports

  • Payouts report
  • Payments report
  • Monthly report

API Reference

  • Objects
  • Methods
  • Webhooks
  • Error codes

Objects

PaymentSession

A container with data about all the operations performed within a single payment session.

Payment operations can only be performed in a session. One or more operations of the same or different types can be performed within the session (e.g. several payouts, a payment and a refund, or a payment which is subsequently split).

NameMandatoryTypeDescription
id+stringSession identifier
status+stringThe status. Possible values: created, in_progress, accepted, cancelled, error
created_at+stringCreation date in ISO 8601 format
updated_at+stringUpdate date in ISO 8601 format
payments-arrayA list of payouts performed within the session
acquiring_payments-arrayA list of payments performed within the session
next_action-stringA label indicating actions needed to perform the transaction successfully. Possible values: confirm, capture
error-ErrorError description

Payment session statuses (status)

  • created — the session has been created and is waiting to be started or canceled;
  • in_progress — the payment is being processed;
  • accepted — the payment has been completed successfully;
  • cancelled — the payment has been canceled;
  • error — an unexpected error occured while processing. The resulting status is unknown. You need to contact Bank 131's support team.

Next steps (next_action)

If this field is not empty, it means that Bank 131 is waiting for you to perform specific actions to continue with the operation:

  • confirm — you need to confirm the operation (confirm_request) or cancel it (cancel_request);
  • capture — you need to perform the debit (session/capture) or cancel it (cancel_request).

Payment

An object containing all the payout details.

NameMandatoryTypeDescription
id+stringPayout identifier
status+stringThe status. Possible values: succeeded, in_progress, pending, failed
created_at+stringCreation date in ISO 8601 format
finished_at-stringCompletion date in ISO 8601 format
customer-CustomerThe recipient's data in your system, e.g. the login that lets you verify the recipient on your side.
payment_method+PaymentMethodThe method of receiving the payout
amount_details+AmountDetailsThe amount
fiscalization_details-FiscalizationDetailsFiscalization details
participant_details-ParticipantDetailsThe details on payout participants needed to perform the payout, e.g. the names and addresses of the payer and the recipient.
refunds-array<Refund>Refund list
metadata-*Additional information. Any data you need to perform the operation. Returned in responses and webhooks
error-ErrorError description

Payout statuses (status)

  • in_progress — the payment is being processed;
  • pending — awaiting your confirmation (confirm_request) or cancelation (cancel_request);
  • succeeded — the payout has completed successfully;
  • failed — the payout has not gone through because of an error.

AcquiringPayment

An object containing all the payment details.

NameMandatoryTypeDescription
id+stringUnique payment identifier
status+stringPayment status Possible values: succeeded, in_progress, pending, failed
created_at+stringCreation date in ISO 8601 format
finished_at-stringCompletion date in ISO 8601 format
customer-CustomerUser (payer) details
payment_details+PaymentDetailsPayment data
amount_details+AmountDetailsThe amount
recurrent_token-RecurrentDetailsDetails needed to perform recurring payments
participant_details-ParticipantDetailsParticipants' details
refunds-array<Refund>Refund list
customer_interaction-CustomerData needed for user interaction
metadata-*Additional information. Any data you need to perform the operation. Returned in responses and webhooks
error-ErrorError description

Payment statuses (status)

  • in_progress — the payment is being processed;
  • pending — awaiting your confirmation (confirm_request) or cancelation (cancel_request);
  • succeeded — the payment has completed successfully;
  • failed — the payment has not gone through because of an error.

Refund

An object containing details about the refund.

NameMandatoryTypeDescription
id+stringUnique refund identifier
status+stringRefund status. Possible values: in_progress, accepted, declined, error
amount_details+AmountDetailsAn object containing the amount of the refund
created_at+stringCreation date
finished_at-stringCompletion date

Refund statuses (status)

  • in_progress — the payment is being processed;
  • accepted — the refund has completed successfully;
  • declined — Bank 131 declined the refund;
  • error — the refund has not gone through because of an error.

PaymentMethod

An object containing the description of the method for receiving the payout.

NameMandatoryTypeDescription
type+stringThe type of method for receiving the payout. Possible values: card, bank_account, wallet
card-CardPaymentMethodRecipient's bank card
bank_account-BankAccountPaymentMethodRecipient's bank account
wallet-WalletPaymentMethodRecipient's electronic wallet
tax-TaxPaymentMethodPayouts to the Russian Federal Tax Agency

PaymentDetails

An object containing the description of the method for performing the payment.

NameMandatoryTypeDescription
type+stringPayment method type. Possible values: card, recurrent
card-CardPaymentMethodBank card details
recurrent-RecurrentDetailsDetails for repeating the payment using the token

PaymentOptions

Parameters needed to perform the payment.

NameMandatoryTypeDescription
return_url-stringThe URL to redirect the user to after the payment has been performed. The URL must be valid.
recurrent-boolDetermines whether the payment is to be performed using the saved token.

BankAccountPaymentMethod

An object with the payout recipient's account description.

NameMandatoryTypeDescription
system_type+stringBank account region. Always: ru
ru-BankAccountRURecipient's Russian bank account (region: ru)

BankAccountRU

An object containing Russian bank account details (region: ru).

NameMandatoryTypeDescription
bik+stringRecipient's bank's BIC
account+stringRecipient's bank account
full_name+stringRecipient's full name
description+stringPayout purpose
is_fast-boolDetermines whether the payout is to be performed via BESP

CardPaymentMethod

An object containing the payout recipient's bank card details.

NameMandatoryTypeDescription
type-stringCard details transmission type. Possible values: bank_card, encrypted_card
bank_card-BankCardUnencrypted card
encrypted_card-EncryptedCardCard with encrypted fields (tokenized)
brand-stringCard information. Returned in notifications, needed for user display.
last4-stringCard information. Returned in notifications, needed for user display.

BankCard

Unencrypted card object (can be used if you have PCI DSS).

NameMandatoryTypeDescription
number+stringCard number
expiration_month-stringMonth
expiration_year-stringYear
security_code-stringCVC (security code)
cardholder_name-stringCardholder's name

EncryptedCard

Card with encrypted fields (tokenized). Transmitted during payouts or payments through the widget.

NameMandatoryTypeDescription
number_hash+stringCard number hash
expiration_date_hash-stringExpiration date hash
security_code_hash-stringCVC code hash
cardholder_name_hash-stringCardholder's name hash

WalletPaymentMethod

An object containing electronic wallet details.

NameMandatoryTypeDescription
type+stringWallet type. Possible values: qiwi, yoomoney
qiwi-QiwiWalletPaymentMethodQIWI wallet details
yoomoney-YooMoneyWalletPaymentMethodYooMoney (Yandex.Money) wallet details

QiwiWalletPaymentMethod

An object containing QIWI wallet details.

NameMandatoryTypeDescription
account+stringQIWI Wallet ID: holder phone number in international format (without +). Example: 79210010203

YooMoneyWalletPaymentMethod

Object containing YooMoney (Yandex.Money) wallet details.

NameMandatoryTypeDescription
account+string11 to 20 digits. Example: 4100175017397

TaxPaymentMethod

Object containing tax payment method.

NameMandatoryTypeDescription
type+stringTax payment type: tax_short
tax_short+TaxShortTax payment data with minimum set of parameters

TaxShort

Object containing tax payment data with minimum set of parameters

NameMandatoryTypeDescription
tax_details+TaxDetailsTax payment details

RecurrentDetails

Repeat payment object.

NameMandatoryTypeDescription
token+stringPayment instrument (e.g. bank card) token for recurrent debiting
created_at-stringCreation date in ISO 8601 format
finished_at-stringToken expiration date (bank card expiration date) in the format as per ISO 8601
is_active-boolWhether you can use the token: true means you can; false means you cannot

AmountDetails

Amount object.

NameMandatoryTypeDescription
amount+intAmount value in minor currency units (ruble decimal format). If the amount is 100 rubles, pass 10000
currency+stringThe ISO 4217 currency code. Case insensitive. Always: rub

TaxDetails

Object containing tax payment details.

NameMandatoryTypeDescription
period+TaxPeriodThe tax period

TaxPeriod

Object containing tax period description.

NameMandatoryTypeDescription
type+stringThe period type. Possible values: month, quarter
number+numberDepends on period type. Number from 1 to 12 for month, number from 1 to 4 for quarter
year+stringYear, 4 digits. Example: 2021

Customer

Data about the user (payout recipient or payment sender) in your system, e.g. the login that lets you identify the user. Also includes their contact details.

NameMandatoryTypeDescription
reference+stringIdentifier of the user (payout recipient or payment sender) in your system.
contacts-arrayUser contacts

CustomerContact

Contacts of the user (payout recipient or payment sender).

NameMandatoryTypeDescription
e-mail-stringUser's e-mail
phone-stringUser's phone number

CustomerInteraction

An object describing customer interaction.

NameMandatoryTypeDescription
type+stringCustomer interaction type. Possible values: redirect
redirect-CustomerInteractionRedirectUser redirect data object

CustomerInteractionRedirect

User redirect data object.

NameMandatoryTypeDescription
url+stringRedirect address including GET parameters
base_url+stringRedirect address
method+stringSubmission method, e.g. POST
qs-map<string,string>A set of GET parameters for redirect
params-map<string,*>A set of parameters for the message body for redirect

FiscalizationDetails

Fiscalization details object.

NameMandatoryTypeDescription
professional_income_taxpayer+ProfessionalIncomeTaxpayerFiscalization details for the self-employed

FiscalizationReceipt

An object containing the data of the receipt created during fiscalization.

NameMandatoryTypeDescription
id+stringReceipt idenitfier
link-stringReceipt link

FiscalizationService

An object containing a description of the service which the payout is covering, for fiscalization purposes.

NameMandatoryTypeDescription
name+stringService name
amount_details+AmountDetailsService price
quantity-integerNumber of services provided. The default value is 1

Important: The product of the service price and the number of services provided must equal the amount of the payout.

Participant

Payout participant (payer or recipient) details. Which details are needed depends on the method of receiving the payout.

NameMandatoryTypeDescription
full_name- (mandatory for Participant.recepient for payouts to any cards)stringName
company_name-stringCompany name
reference- (mandatory for Participant.recepient for payouts to nominal accounts)stringRecipient identifier in your system
address_line- (mandatory for Participant.sender for payouts to foreign cards)stringAddress
ipv4- (mandatory for Participant.sender for payouts to foreign cards if the ipv6 field is empty)stringIP version 4 address
ipv6- (mandatory for Participant.sender for payouts to foreign cards if the ipv4 field is empty)stringIP version 6 address
country_iso3- (mandatory for Participant.sender for payouts to foreign cards)stringThe country (ISO-3166-1 alpha-3)
country_iso2-stringThe country (ISO-3166-1 alpha-2)
city- (mandatory for Participant.sender for payouts to foreign cards)stringThe city
postal_code- (mandatory for Participant.sender for payouts to foreign cards)stringPostal address

ParticipantDetails

Payout participant details.

NameMandatoryTypeDescription
sender-ParticipantSender's details
recipient-ParticipantRecipient's details

ProfessionalIncomeTaxpayer

Object containing fiscalization details for the self-employed.

NameMandatoryTypeDescription
services+arrayThe list of services provided
tax_reference+stringThe INN of the self-employed person
receipt-FiscalizationReceiptFiscalization receipt. Returned in notifications
payer_type-stringPayer type (who pays the self-employed). Possible values: legal, individual, foreign
payer_tax_number-stringThe INN of the payer. Mandatory for payer_type: legal
payer_name-stringPayer name. Mandatory for payer_type: legal

Payer type payer_type

Payer type. Possible values:

  • legal — legal entity
  • individual — natural person
  • foreign — non-resident of Russia

WalletDetails

Your guarantee payment balance details (this balance is used to perform payouts).

NameMandatoryTypeDescription
id+stringBalance identifier
amount_details+AmountDetailsCurrent balance

TokenizeWidgetMetadata

An object containing settings for the tokenization widget.

NameMandatoryTypeDescription
access+boolIdentifies whether this public key can use the tokenization widget.

SelfEmployedWidgetMetadata

An object containing settings for the widget used for linking self-employed people to Bank 131.

NameMandatoryTypeDescription
tax_reference+stringThe INN of the self-employed person

AcquiringWidgetMetadata

An object containing settings for the payout form widget (for performing bank card payments).

NameMandatoryTypeDescription
session_id+stringIdentifies the payment session for which the payment will be performed.
show_recurrent_checkbox-boolWhether to display the checkbox in the widget interface Enable automatic payments
success_return_url-stringThe URL to redirect the user to after the payment has been successfully completed.
failure_return_url-stringThe URL to redirect the user to when an error occurs during the payment.

Error

Error description object.

NameMandatoryTypeDescription
code-stringError code
description-stringError description

Error codes

← Monthly reportMethods →
  • PaymentSession
  • Payment
  • AcquiringPayment
  • Refund
  • PaymentMethod
  • PaymentDetails
  • PaymentOptions
  • BankAccountPaymentMethod
  • BankAccountRU
  • CardPaymentMethod
  • BankCard
  • EncryptedCard
  • WalletPaymentMethod
  • QiwiWalletPaymentMethod
  • YooMoneyWalletPaymentMethod
  • TaxPaymentMethod
  • TaxShort
  • RecurrentDetails
  • AmountDetails
  • TaxDetails
  • TaxPeriod
  • Customer
  • CustomerContact
  • CustomerInteraction
  • CustomerInteractionRedirect
  • FiscalizationDetails
  • FiscalizationReceipt
  • FiscalizationService
  • Participant
  • ParticipantDetails
  • ProfessionalIncomeTaxpayer
  • WalletDetails
  • TokenizeWidgetMetadata
  • SelfEmployedWidgetMetadata
  • AcquiringWidgetMetadata
  • Error
Documentation
Documentation
PayoutsPaymentsAPI Reference
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
© 2021 Bank 131