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).

Name	Mandatory	Type	Description
id	+	string	Session identifier
status	+	string	The 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	A list of payouts performed within the session
acquiring_payments	-	array	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	The 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	The amount
fiscalization_details	-	FiscalizationDetails	Fiscalization details
participant_details	-	ParticipantDetails	The 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	-	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 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	The amount
recurrent_token	-	RecurrentDetails	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 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 completed successfully;
• failed — the payment has not gone through because of 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 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.

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
card	-	CardPaymentMethod	Bank card details
recurrent	-	RecurrentDetails	Details for repeating the payment using the token

PaymentOptions

Parameters needed to perform the payment.

Name	Mandatory	Type	Description
return_url	-	string	The URL to redirect the user to 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 account region. Always: ru
ru	-	BankAccountRU	Recipient's Russian bank account (region: ru)

BankAccountRU

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

Name	Mandatory	Type	Description
bik	+	string	Recipient's bank's BIC
account	+	string	Recipient's bank account
full_name	+	string	Recipient's full name
description	+	string	Payout purpose
is_fast	-	bool	Determines whether the payout is to be performed via BESP

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

YooMoneyWalletPaymentMethod

Object containing YooMoney (Yandex.Money) wallet details.

Name	Mandatory	Type	Description
account	+	string	11 to 20 digits. Example: 4100175017397

TaxPaymentMethod

Object containing tax payment method.

Name	Mandatory	Type	Description
type	+	string	Tax payment type: 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

RecurrentDetails

Repeat payment object.

Name	Mandatory	Type	Description
token	+	string	Payment instrument (e.g. bank card) token for recurrent debiting
created_at	-	string	Creation date in ISO 8601 format
finished_at	-	string	Token expiration date (bank card expiration date) in the format as per ISO 8601
is_active	-	bool	Whether you can use the token: true means you can; false means you cannot

AmountDetails

Amount object.

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

TaxDetails

Object containing tax payment details.

Name	Mandatory	Type	Description
period	+	TaxPeriod	The tax period

TaxPeriod

Object containing tax period description.

Name	Mandatory	Type	Description
type	+	string	The period type. Possible values: month, quarter
number	+	number	Depends on 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	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

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

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 needed depends on the method of receiving the payout.

Name	Mandatory	Type	Description
full_name	- (mandatory for Participant.recepient for payouts to any cards)	string	Name
company_name	-	string	Company name
reference	- (mandatory for Participant.recepient for payouts to nominal accounts)	string	Recipient identifier in your system
address_line	- (mandatory for Participant.sender for payouts to foreign cards)	string	Address
ipv4	- (mandatory for Participant.sender for payouts to foreign cards if the ipv6 field is empty)	string	IP version 4 address
ipv6	- (mandatory for Participant.sender for payouts to foreign cards if the ipv4 field is empty)	string	IP version 6 address
country_iso3	- (mandatory for Participant.sender for payouts to foreign cards)	string	The country (ISO-3166-1 alpha-3)
country_iso2	-	string	The country (ISO-3166-1 alpha-2)
city	- (mandatory for Participant.sender for payouts to foreign cards)	string	The city
postal_code	- (mandatory for Participant.sender for payouts to foreign cards)	string	Postal address

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	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 — natural 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 redirect the user to after the payment has been successfully completed.
failure_return_url	-	string	The URL to redirect the user to when an error occurs during the payment.

Error

Error description object.

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

Error codes