Objects

PaymentSession

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

Payment operations can only be performed within 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).

Name	Mandatory	Type	Description
id	+	string	Session identifier
status	+	string	Status. Possible values: created, in_progress, accepted, cancelled, error
created_at	+	string	Creation date in ISO 8601 format
updated_at	+	string	Update date in ISO 8601 format
payments	-	array<Payment>	A list of payouts performed within the session
acquiring_payments	-	array<AcquiringPayment>	A list of payments performed within the session
next_action	-	string	A label indicating actions needed to perform the transaction successfully. Possible values: confirm, capture
error	-	Error	Error 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.

Name	Mandatory	Type	Description
id	+	string	Payout identifier
status	+	string	Status. Possible values: succeeded, in_progress, pending, failed
created_at	+	string	Creation date in ISO 8601 format
finished_at	-	string	Completion date in ISO 8601 format
customer	-	Customer	The recipient's data in your system, E.g. the login that lets you verify the recipient on your side.
payment_method	+	PaymentMethod	The method of receiving the payout
amount_details	+	AmountDetails	Amount
fiscalization_details	-	FiscalizationDetails	Fiscalization details
participant_details	-	ParticipantDetails	The details of payout participants required 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 in order to perform the operation. Returned in responses and webhooks
error	-	Error	Error 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 been completed successfully;
• failed — the payout has not gone through because of an error.

AcquiringPayment

An object containing all the payment details.

Name	Mandatory	Type	Description
id	+	string	Unique payment identifier
status	+	string	Payment status Possible values: succeeded, in_progress, pending, failed
created_at	+	string	Creation date in ISO 8601 format
finished_at	-	string	Completion date in ISO 8601 format
customer	-	Customer	User (payer) details
payment_details	+	PaymentDetails	Payment data
amount_details	+	AmountDetails	Amount
recurrent	-	RecurrentTokenInfo	Details needed to perform recurring payments
participant_details	-	ParticipantDetails	Participants' details
refunds	-	array<Refund>	Refund list
customer_interaction	-	Customer	Data needed for user interaction
metadata	-	*	Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks
error	-	Error	Error 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 been completed successfully;
• failed — the payment has not gone through due to an error.

Refund

An object containing details about the refund.

Name	Mandatory	Type	Description
id	+	string	Unique refund identifier
status	+	string	Refund status. Possible values: in_progress, accepted, declined, error
amount_details	+	AmountDetails	An object containing the amount of the refund
created_at	+	string	Creation date
finished_at	-	string	Completion date

Refund statuses (status)

• in_progress — the payment is being processed;
• accepted — the refund has been completed successfully;
• declined — Bank 131 has 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.

Name	Mandatory	Type	Description
type	+	string	The type of method for receiving the payout. Possible values: card, bank_account, wallet
card	-	CardPaymentMethod	Recipient's bank card
bank_account	-	BankAccountPaymentMethod	Recipient's bank account
wallet	-	WalletPaymentMethod	Recipient's electronic wallet
tax	-	TaxPaymentMethod	Payouts to the Russian Federal Tax Agency

PaymentDetails

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

Name	Mandatory	Type	Description
type	+	string	Payment method type. Possible values: card, recurrent, internal_transfer, secured_card, faster_payment_system
card	-	CardPaymentMethod	Bank card details
recurrent	-	RecurrentTokenInfo	Details for repeating the payment using the token
internal_transfer	-	InternalTransferInfo	Internal transfer details
secured_card	-	SecuredCard	Tokenized card details
faster_payment_system	-		Payment via FPS

PaymentOptions

Parameters needed to perform the payment.

Name	Mandatory	Type	Description
return_url	-	string	The URL to which the user is redirected after the payment has been performed. The URL must be valid.
recurrent	-	bool	Determines whether the payment is to be performed using the saved token.

BankAccountPaymentMethod

An object with the payout recipient's account description.

Name	Mandatory	Type	Description
system_type	+	string	Bank payment system. Options: ru, faster_payment_system, faster_payment_system_verification
ru	-	BankAccountRU	Recipient's Russian bank account (region: ru)
faster_payment_system	-	FasterPaymentSystem	Recipient's data in the Faster Payment System
faster_payment_system_verification	-	FasterPaymentSystemVerification	Data for the recipient verification in the Faster Payment System

BankAccountRU

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

Name	Mandatory	Type	Description
bik	+	string	Recipient’s Bank Identification Code
account	+	string	Recipient's bank account
full_name	+	string	The individual's full name. In case of a payout to an account of a sole proprietor should be passed in the following format: ИП <full name>. In case of a payout to a legal entity, enter the entity's name, if it is provided in the agreement. Important: if the name is passed incorrectly the recipient bank may cancel the payout and the payout will be refunded.
description	+	string	Payout purpose
inn	- (mandatory for the payouts to the accounts of legal entities and individual proprietors)	string	The recipient's INN, 10 digits for legal entities, 12 digits for individuals, including individual proprietors.
kpp	- (mandatory for the payouts to the accounts of legal entities)	string	The recipient's Tax Registration Reason Code (KPP)
is_fast	-	bool	Indicates whether an urgent payout should be made (via BESP). An urgent payout takes place within an hour, a regular one — from 1 to 3 banking days.

FasterPaymentSystem

An object with the data of a user of the Faster Payment System.

Name	Mandatory	Type	Description
phone	+	string	Recipient's phone number
bank_id	+	string	Identifier of the recipient's bank in the FPS
description	+	string	Payout purpose

FasterPaymentSystemVerification

An object with the data for the recipient verification in the Faster Payment System.

Name	Mandatory	Type	Description
phone	+	string	Recipient's phone number
bank_id	+	string	Identifier of the recipient's bank in the FPS

CardPaymentMethod

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

Name	Mandatory	Type	Description
type	+	string	Card details transmission type. Possible values: bank_card, encrypted_card
bank_card	-	BankCard	Unencrypted card
encrypted_card	-	EncryptedCard	Card with encrypted fields (tokenized)
brand	-	string	Card information. Returned in notifications, needed for user display.
last4	-	string	Card information. Returned in notifications, needed for user display.

BankCard

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

Name	Mandatory	Type	Description
number	+	string	Card number
expiration_month	-	string	Month
expiration_year	-	string	Year
security_code	-	string	CVC (security code)
cardholder_name	-	string	Cardholder's name

EncryptedCard

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

Name	Mandatory	Type	Description
number_hash	+	string	Card number hash
expiration_date_hash	-	string	Expiration date hash
security_code_hash	-	string	CVC code hash
cardholder_name_hash	-	string	Cardholder's name hash

WalletPaymentMethod

An object containing electronic wallet details.

Name	Mandatory	Type	Description
type	+	string	Wallet type. Possible values: qiwi, yoomoney
qiwi	-	QiwiWalletPaymentMethod	QIWI wallet details
yoomoney	-	YooMoneyWalletPaymentMethod	YooMoney (Yandex.Money) wallet details

QiwiWalletPaymentMethod

An object containing QIWI wallet details.

Name	Mandatory	Type	Description
account	+	string	QIWI Wallet ID: holder phone number in international format (without +). Example: 79210010203. Example: 79210010203

YooMoneyWalletPaymentMethod

Object containing YooMoney (Yandex.Money) wallet details.

Name	Mandatory	Type	Description
account	+	string	YooMoney wallet number, 11 to 20 digits. Example: 4100175017397
description	-	string	Payment description, 128 character maximum. If there are more characters, the operation will not go through.

TaxPaymentMethod

Object containing tax payment method.

Name	Mandatory	Type	Description
type	+	string	Tax payment type. Variants: tax_short.
tax_short	+	TaxShort	Tax payment data with minimum set of parameters.

TaxShort

Object containing tax payment data with minimum set of parameters.

Name	Mandatory	Type	Description
tax_details	+	TaxDetails	Tax payment details.

PublicToken

Object with information about a public token.

Name	Mandatory	Type	Description
token	+	string	Token

RecurrentToken

Object with information about a recurrent token.

Name	Mandatory	Type	Description
token	+	string	Token

CardTokenInfo

Object with details of a tokenized bank card.

Name	Mandatory	Type	Description
number_hash	+	string	Token (tokenized bank card)
brand	+	string	Payment system, i.e. visa
last4	+	string	Last 4 card numbers

PublicTokenInfo

Object with information about a public token.

Name	Mandatory	Type	Description
token	+	string	Token
created_at	+	string	Creation date in ISO 8601 format
finished_at	+	string	Completion date in ISO 8601 format.
is_active	+	bool	Possible to conduct the operation with this token: true — allowed, false — not allowed

RecurrentTokenInfo

Object with information about a recurrent token. For more information about recurrent token and its settings please see here.

Name	Mandatory	Type	Description
token	+	string	Token
created_at	+	string	Creation date in ISO 8601 format
finished_at	+	string	Completion date in ISO 8601 format. The setting isn't processed by the Bank.
is_active	+	bool	Possible to conduct the operation with this token: true — allowed, false — not allowed

InternalTransferInfo

Object with information about an internal transfer

Name	Mandatory	Type	Description
type	+	string	Transfer type. Possible values: transfer_from_nominal_account
transfer_from_nominal_account	-	TransferFromNominalAccount	Information about a transfer from a nominal account

SecuredCard

Object with information about a tokenized card.

Name	Mandatory	Type	Description
type	+	string	Transfer type. Possible values: google_pay
google_pay	-	GooglePayInfo	Information about a payment via Google Pay

TransferFromNominalAccount

Object with information about a transfer from a nominal account.

Name	Mandatory	Type	Description
description	+	string	Description

GooglePayInfo

Object with information about a Google Pay transfer.

Name	Mandatory	Type	Description
token	+	string	Google Pay token

AmountDetails

Amount object.

Name	Mandatory	Type	Description
amount	+	int	Amount value in minor currency units (ruble decimal format). If the amount is 100 rubles, enter 10000
currency	+	string	The ISO 4217 currency code. Case insensitive. Options: rub, eur

TaxDetails

Object containing tax payment details.

Name	Mandatory	Type	Description
period	+	TaxPeriod	Object containing a summary of the period for which you must pay taxes

TaxPeriod

Object containing tax period description.

Name	Mandatory	Type	Description
type	+	string	The period type. Possible values: month, quarter.
number	+	number	Depends upon period type. Number from 1 to 12 for month, number from 1 to 4 for quarter.
year	+	string	Year, 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.

Name	Mandatory	Type	Description
reference	+	string	Identifier of the user (payout recipient or payment sender) in your system.
contacts	-	array<CustomerContact>	User contacts

CustomerContact

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

Name	Mandatory	Type	Description
e-mail	-	string	User's e-mail
phone	-	string	User's phone number

CustomerInteraction

An object describing customer interaction.

Name	Mandatory	Type	Description
type	+	string	Customer interaction type. Possible values: redirect
redirect	-	CustomerInteractionRedirect	User redirect data object
inform	-	CustomerInteractionInform	Payment option data object

CustomerInteractionRedirect

User redirect data object.

Name	Mandatory	Type	Description
url	+	string	Redirect address including GET parameters
base_url	+	string	Redirect address
method	+	string	Submission 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

CustomerInteractionInform

Payment option data object

Name	Mandatory	Type	Description
qr	-	QRInformInteraction	Object containing QR code for payments via FPS

QRInformInteraction

Object containing QR code for payments via FPS

Name	Mandatory	Type	Description
content	+	string	Link to QR code
img	+	string	QR code body

FiscalizationDetails

Fiscalization details object.

Name	Mandatory	Type	Description
professional_income_taxpayer	+	ProfessionalIncomeTaxpayer	Fiscalization details for the self-employed

FiscalizationReceipt

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

Name	Mandatory	Type	Description
id	+	string	Receipt idenitfier
link	-	string	Receipt link

FiscalizationService

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

Name	Mandatory	Type	Description
name	+	string	Service name
amount_details	+	AmountDetails	Service price
quantity	-	integer	Number 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 necessary depend upon the method of receiving the payout.

Name	Mandatory	Type	Description
full_name	- (mandatory for Participant.recipient for payouts to any cards)	string	Name
company_name	-	string	Company name
reference	-	string	Recipient identifier in your system.
tax_reference	-	string	Taxpayer identifier
beneficiary_id	- (mandatory for the payments and payouts with a beneficiary)	string	The INN of the beneficiary
country_iso2	-	string	The country (ISO-3166-1 alpha-2)

ParticipantDetails

Payout participant details.

Name	Mandatory	Type	Description
sender	-	Participant	Sender's details
recipient	-	Participant	Recipient's details

ProfessionalIncomeTaxpayer

Object containing fiscalization details for the self-employed.

Name	Mandatory	Type	Description
services	+	array<FiscalizationService>	The list of services provided
tax_reference	+	string	The INN of the self-employed person
receipt	-	FiscalizationReceipt	Fiscalization receipt. Returned in notifications
payer_type	-	string	Payer type (who pays the self-employed). Possible values: legal, individual, foreign
payer_tax_number	-	string	The INN of the payer. Mandatory for payer_type: legal
payer_name	-	string	Payer name. Mandatory for payer_type: legal

Payer type payer_type

Payer type. Possible values:

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

WalletDetails

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

Name	Mandatory	Type	Description
id	+	string	Balance identifier
amount_details	+	AmountDetails	Current balance

TokenizeWidgetMetadata

An object containing settings for the tokenization widget.

Name	Mandatory	Type	Description
access	+	bool	Identifies 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.

Name	Mandatory	Type	Description
tax_reference	+	string	The INN of the self-employed person

AcquiringWidgetMetadata

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

Name	Mandatory	Type	Description
session_id	+	string	Identifies the payment session for which the payment will be performed.
show_recurrent_checkbox	-	bool	Whether to display the checkbox in the widget interface Enable automatic payments
success_return_url	-	string	The URL to which the user is redirected after the payment has been successfully completed.
failure_return_url	-	string	The URL to which the user is redirected when an error occurs during the payment.
success_on_hold	-	bool	Whether to show a message about a successful payment to a payer when holding. By default, false and the widget shows a loading screen until the end of the hold.

СonfirmInformation

Object with a confirmation information for a transaction with a nominal account.

Name	Mandatory	Type	Description
transfer_details	+	TransferDetails	Information about a transfer

TransferDetails

Object with information about a transfer.

Name	Mandatory	Type	Description
payment_method	+	CardPaymentMethod	The method of receiving the payout
customer	+	NominalPaymentParticipant	Information about a payer
recipient	+	NominalPaymentParticipant	Information about a recipient
purpose	+	string	Payout purpose in the following format: <description>; card:<card mask>
amount	+	AmountDetails	Amount

NominalPaymentParticipant

Information about a payer and recipient of a payout from a nominal account.

Name	Mandatory	Type	Description
account_number	-	string	Account number
name	-	string	Name
bank_name	-	string	Bank's name
bik	-	string	Bank's BIC
correspondent_account_number	-	string	Correspondent account number

Error

Error description object.

Name	Mandatory	Type	Description
code	-	string	Error code
description	-	string	Error description

Error codes

NotificationCountInformation

The object contains a number of unread notifications for a self-employed person's tax reference number (INN).

Name	Mandatory	Type	Description
tax_reference	+	string	Tax reference number (INN)
count	-	int	Number of unread notifications per each tax_reference value

NotificationInformation

The object contains detailed information about notifications for a self-employed person's tax reference number (INN).

Name	Mandatory	Type	Description
tax_reference	+	string	Tax reference number (INN)
notifications	-	array<Notifications>	Notifications for the value from tax_reference

Notifications

The array contains detailed information about notifications the Federal Tax Service sends to a self-employed person.

Name	Mandatory	Type	Description
id	+	string	Identifier
title	+	string	Notification header
message	+	string	Notification body
status	+	string	Status. Possible values: "NEW" — new and unread notification; "ACKNOWLEDGED" — read notification; "ARCHIVED" — archived notification.
created_at	+	dateTime	Notification date

Notification_list

The array contains data for informing the Federal Tax Service about ststuses of notifications sent to the self-employed.

Name	Mandatory	Type	Description
message_id_list	-	array<string>	Array with message IDs
tax_reference	+	string	Tax reference number (INN)