Skip to main content

Objects

AccountStatement

An object with statement details.

NameMandatoryTypeDescription
date_from+dateStatement start date
date_to+dateStatement end date
account_number+stringAccount number (20 digits) for which the statement is generated

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
payment_details+PaymentDetailsPayment data
amount_details+AmountDetailsAmount
amounts-AmountsTransaction fee
finished_at-stringCompletion date in ISO 8601 format
customer+CustomerUser (payer) details
recurrent-RecurrentTokenInfoDetails 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 in order 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 been completed successfully;
  • failed — the payment has not gone through due to an error.

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 which the user is redirected after the payment has been successfully completed.
failure_return_url-stringThe URL to which the user is redirected when an error occurs during the payment.
success_on_hold-boolWhether 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.

AmountDetails

Amount object.

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

Amounts

An object with information on the transaction fee.

NameMandatoryTypeDescription
fee-MerchantFeeInformation on the applicable fee

BalanceDetails

Account balance details.

NameMandatoryTypeDescription
current_balance-stringCurrent account balance (the value can be positive or equal to 0). The value is specified in minor currency units (ruble decimal format). If the amount is 100 rubles, the value is 10000

BankAccountPaymentMethod

An object with the payout recipient's account description.

NameMandatoryTypeDescription
system_type+stringBank payment system. Options: ru, faster_payment_system, faster_payment_system_verification
ru-BankAccountRURecipient's Russian bank account (region: ru)
faster_payment_system-FasterPaymentSystemRecipient's data in the Faster Payment System
faster_payment_system_verification-FasterPaymentSystemVerificationData for the recipient verification in the Faster Payment System

BankAccountRU

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

NameMandatoryTypeDescription
bik+stringRecipient’s Bank Identification Code
account+stringRecipient's bank account
full_name+stringThe 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+stringPayout purpose
inn- (mandatory for the payouts to the accounts of legal entities and individual proprietors)stringThe 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)stringThe recipient's Tax Registration Reason Code (KPP)
is_fast-boolIndicates 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.

BankCard

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

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

CardElements

An object with the number of a card for tokenizing.

NameMandatoryTypeDescription
ref+stringA fixed value, always number
type+stringA fixed value, always card_number
card_number+stringCard number

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.

CardTokenInfo

Object with details of a tokenized bank card.

NameMandatoryTypeDescription
number_hash+stringToken (tokenized bank card)
brand+stringPayment system, i.e. visa
last4+stringLast 4 card numbers

ConfirmInformation

Object with a confirmation information for a transaction with an escrow account.

NameMandatoryTypeDescription
transfer_details+TransferDetailsInformation about a transfer

Contragent

An object with counterparty details.

NameMandatoryTypeDescription
name-stringCounterparty's name
inn-stringCounterparty's INN
kpp-stringCounterparty's KPP
account_number+stringCounterparty's account number
bank_bik+stringCounterparty's bank BIK
bank_name-stringCounterparty's bank name

CounterParty

An object with counterparty details.

NameMandatoryTypeDescription
kpp-stringCounterparty's KPP
inn-stringCounterparty's INN
name+stringCounterparty's name
account_number+stringCounterparty's account number
bank_code+stringCounterparty's bank BIK

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 (up to 128 characters)
contacts-array\<CustomerContact>User 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
inform-CustomerInteractionInformPayment option data object

CustomerInteractionInform

Payment option data object

NameMandatoryTypeDescription
qr-QRInformInteractionObject containing QR code for payments via FPS

CustomerInteractionRedirect

User redirect data object.

NameMandatoryTypeDescription
url+stringRedirect address including GET parameters
base_url+stringRedirect address
method+stringSubmission method, E.g. GET, POST
qs-map\<string,string>A set of parameters depending on the transaction method
params-map\<string,*>A set of parameters depending on the transaction method
  • Check if any parameters are specified in the qs and params objects.
  • Redirect the user to the redirect address specified in base_url using the method from the method parameter and including all the required parameters in the URL or request body.

Data

Masked user account data object.

NameMandatoryTypeDescription
masked_account+stringFirst 5 and last 4 digits of an account

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

Error

Error description object.

NameMandatoryTypeDescription
code-stringError code
description-stringError description

Error codes

FasterPaymentSystem

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

NameMandatoryTypeDescription
phone+stringRecipient's phone number
bank_id+stringIdentifier of the recipient's bank in the FPS
description+stringPayout purpose

FasterPaymentSystemVerification

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

NameMandatoryTypeDescription
phone+stringRecipient's phone number
bank_id+stringIdentifier of the recipient's bank in the FPS

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. The object may contain up to 6 services.

  • The restriction on the number of services per receipt is regulated by the Federal Tax Service (not by the Bank).
  • If the number of services is greater than six, you can:
    • split them into multiple receipts,
    • combine them.
      Example: if 10 consulting services, 10 000 rubles each, were provided, you can specify 10 services, 10 000 rubles each, as a single item instead of specifying each service separately.
  • The product of the service price and the number of services provided must equal the amount of the payout.
NameMandatoryTypeDescription
name+stringService name
amount_details+AmountDetailsService price
quantity-integerNumber of services provided. Default value: 1

InternalTransferInfo

Object with information about an internal transfer

NameMandatoryTypeDescription
type+stringTransfer type. Possible values: transfer_from_nominal_account
transfer_from_nominal_account-TransferFromNominalAccountInformation about a transfer from an escrow account
transfer_from_bank_account-TransferFromBankAccountInformation about a transfer from a settlement account

InternetBanking

Details on payments via payment systems.

NameMandatoryTypeDescription
type+stringPayment system. Possible values: sber_pay
sber_pay+SberPaySberPay payment system transaction details

MerchantFee

Information on the applicable fee. The number of objects matches the number of applicable fees.

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

NominalPaymentParticipant

Information about a payer and recipient of a payout from an escrow account.

NameMandatoryTypeDescription
account_number-stringAccount number
name-stringName
bank_name-stringBank's name
bik-stringBank's BIC
correspondent_account_number-stringCorrespondent account number

NotificationCountInformation

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

NameMandatoryTypeDescription
tax_reference+stringTax reference number (INN)
count-intNumber 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).

NameMandatoryTypeDescription
tax_reference+stringTax 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.

NameMandatoryTypeDescription
id+stringIdentifier
title+stringNotification header
message+stringNotification body
status+stringStatus. Possible values: "NEW" — new and unread notification; "ACKNOWLEDGED" — read notification; "ARCHIVED" — archived notification.
created_at+dateTimeNotification date

Notification_list

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

NameMandatoryTypeDescription
message_id_list-array\<string>Array with message IDs
tax_reference+stringTax reference number (INN)

Participant

Payout participant (payer or recipient) details. Which details are necessary depend upon the method of receiving the payout.

NameMandatoryTypeDescription
full_name- (mandatory for Participant.recipient for payouts to any cards)stringFull ame
first_name-stringFirst name
last_name-stringLast name
middle_name-stringPatronymic name
company_name-stringCompany name
reference-stringRecipient identifier in your system
tax_reference-stringTaxpayer identifier
beneficiary_id- (mandatory for the payments and payouts with a beneficiary)stringThe INN of the beneficiary
country_iso3-stringThe country (ISO-3166-1 alpha-3)
account- (mandatory for Participant.sender when making payouts from an escrow account)stringSender's escrow account

ParticipantDetails

Payout participant details.

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

Payment

An object containing all the payout details.

NameMandatoryTypeDescription
id+stringPayout identifier
status+stringStatus. 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+AmountDetailsAmount
amounts-AmountsTransaction fee
fiscalization_details-FiscalizationDetailsFiscalization details
participant_details-ParticipantDetailsThe 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-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 been completed successfully;
  • failed — the payout has not gone through because of an error.

PaymentDetails

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

NameMandatoryTypeDescription
type+stringPayment method type. Possible values: card, recurrent, internal_transfer, secured_card, faster_payment_system, wallet
card-CardPaymentMethodBank card details
recurrent-RecurrentTokenInfoDetails for repeating the payment using the token
internal_transfer-InternalTransferInfoInternal transfer details
faster_payment_system-FasterPaymentSystemPayment via FPS
wallet-WalletPaymentMethodPayment via wallet

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

PaymentOptions

Parameters needed to perform the payment.

NameMandatoryTypeDescription
return_url-stringThe URL to which the user is redirected after the payment has been performed. The URL must be valid.
recurrent-boolDetermines whether the payment is to be performed using the saved token.
expiration_at-datetimeimmutableInvoice lifetime. Format: YYY-MM-DD HH:MM:SS

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

NameMandatoryTypeDescription
id+stringSession identifier
status+stringStatus. 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-array\<Payment>A list of payouts performed within the session
acquiring_payments-array\<AcquiringPayment>A 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 occurred while processing

    Attention! This status is not final. Please contact Bank 131's support team and wait for a final transaction status.

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:

ProfessionalIncomeTaxpayer

Object containing fiscalization details for the self-employed.

NameMandatoryTypeDescription
services+array\<FiscalizationService>List of services provided (maximum 6)
tax_reference+stringSelf-employed person's INN
receipt-FiscalizationReceiptFiscalization receipt. Returned in notifications
payer_type-stringPayer type (who pays the self-employed). Possible values: legal, individual, foreign
payer_tax_number-stringPayer's INN. 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 — individual person
  • foreign — non-resident of Russia

PublicToken

Object with information about a public token.

NameMandatoryTypeDescription
token+stringToken

PublicTokenInfo

Object with information about a public token.

NameMandatoryTypeDescription
token+stringToken
created_at+stringCreation date in ISO 8601 format
finished_at+stringCompletion date in ISO 8601 format.
is_active+boolPossible to conduct the operation with this token: true — allowed, false — not allowed

QRInformInteraction

Object containing QR code for payments via FPS.

NameMandatoryTypeDescription
content+stringLink to QR code
img+stringQR code body

RecurrentToken

Object with information about a recurrent token.

NameMandatoryTypeDescription
token+stringToken

RecurrentTokenInfo

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

NameMandatoryTypeDescription
token+stringToken
created_at+stringCreation date in ISO 8601 format
finished_at+stringCompletion date in ISO 8601 format. The setting isn't processed by the Bank.
is_active+boolPossible to conduct the operation with this token: true — allowed, false — not allowed
initiator-stringRecurring payment type. Possible values: merchant — MIT payment (by default), client — CIT payment

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
is_chargeback-boolWhether the refund is made within a chargeback

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.

SberPay

SberPay payment details.

NameMandatoryTypeDescription
phone-stringPhone number to send PUSH or SMS to. Format: 7**********
channel+ENUMSberPay payment channel. Options: app, web_mobile, web

SelfEmployedWidgetMetadata

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

NameMandatoryTypeDescription
tax_reference+stringINN of the self-employed person

TaxPeriod

Object containing tax period description.

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

TaxShort

Object containing tax payment data with minimum set of parameters.

NameMandatoryTypeDescription
tax_details+TaxDetailsTax payment details.

TaxDetails

Object with data for tax payments.

NameRequiredTypeDescription
period- (Required for payments with an extended set of fields)stringPeriod. Input format described below.
kbk- (Required for payments with an extended set of fields)stringBudget classification code, 20 digits.
oktmo- (Required for payments with an extended set of fields)stringAll-Russian Classifier of Territories of Municipal Formations, 8 or 11 digits.
payment_reason- (Required for payments with an extended set of fields)stringPayment reason. Input format described below.
document_number- (Required for payments with an extended set of fields)stringDocument number. Input format described below.
document_date- (Required for payments with an extended set of fields)stringDocument date. Input format described below.
Input format for the 'period' field in requests with extended parameters
  • If the payment_reason field is set to "ТП" or "ЗД", then the payment frequency established by legislation should be specified in one of the following formats:
    • for monthly payments: "МС.MM.YYYY", where MM is the month (from 01 to 12), and YYYY is the year for which the payment is made (e.g., for income tax withholding for February 2020, use "МС.02.2020");
    • for taxes paid quarterly: "КВ.QQ.YYYY", where QQ is the quarter (from 01 to 04), and YYYY is the year for which the tax is paid;
    • for semi-annual taxes (e.g., Simplified Tax System): "ПЛ.HH.YYYY", where HH is the half-year (01 or 02), and YYYY is the year for which the tax is transferred;
    • for annual payments: "ГД.00.YYYY", where YYYY is the year for which the tax is paid (e.g., for final profit tax calculation for 2019, use "ГД.00.2019").
  • If the payment_reason field is set to "ТР", then the demand date is indicated.
  • If the payment_reason field is set to "АП", then "0" is used.
Input format for the 'payment_reason' field in requests with extended parameters
  • "ТП" — when paying the tax/contribution for the current period;
    • "ЗД" — when voluntarily repaying tax/contribution arrears;
    • "ТР" — when repaying the debt based on a demand issued by the tax authority or the Social Insurance Fund (FSS);
  • "АП" — when repaying the debt based on an audit act (before the demand is issued).
Input format for the 'document_number' field in requests with extended parameters
  • If the payment_reason field is set to "ТП" or "ЗД", then use "0".
    • If the payment_reason field is set to "ТР", use the number of the tax payment demand.
    • If the payment_reason field is set to "АП", use the number of the decision issued after the audit.
Input format for the 'document_date' field in requests with extended parameters
  • If the payment_reason field is set to "ТП", use the date of signing the declaration or "0" if the date is not specified.
  • If the payment_reason field is set to "ЗД", use "0".
  • If the payment_reason field is set to "ТР", use the date of the payment demand.
  • If the payment_reason field is set to "АП", use the date of the post-audit decision.

TaxFull

Object with data for tax payment with an extended set of parameters.

NameRequiredTypeDescription
uin+stringUnique identifier of the charge. Always 0 for tax payments.
description+stringPurpose of the payment
tax_details+stringPayment data for tax payment
payer+TaxPayerSender's data for tax payment
payee+TaxPayeeRecipient's data for tax payment

TaxPaymentMethod

Object with data for tax payment.

NameRequiredTypeDescription
type+stringTax type or payment method. Options: tax_short, tax_full
tax_full+TaxFullData for tax payment with an extended set of parameters
tax_details- (required for minimal field payment)TaxDetailsData for tax payment with a minimal set of parameters

TaxRuPayee

Object with recipient data for tax payments with extended parameters.

NameRequiredTypeDescription
bik+stringRecipient bank's BIK
account+stringAccount number
account_eks+stringUnified Treasury Account
name+stringRecipient name
inn+stringRecipient's INN, 10 digits.

TaxRuPayer

Object with sender data for tax payments with extended parameters.

NameRequiredTypeDescription
kpp+stringSender's KPP, 9 digits.
inn+stringSender's INN, 10 digits.

TokenizeWidgetMetadata

An object containing settings for the tokenization widget.

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

TotalBalance

An object with balance information.

NameMandatoryTypeDescription
opening+intOpening balance on the statement start date
closing+intClosing balance on the statement end date

TotalTurnover

An object with information on funds movement.

NameMandatoryTypeDescription
debet+intTotal debits over the period covered by the statement
credit+intTotal credits over the period covered by the statement

Transactions

An array with information on transactions.

NameMandatoryTypeDescription
amount+intTop-up amount (non-negative values only)
base_amount-intTransaction amount in the currency. Should be filled out only for transactions in currencies other than Russian rubles. When using the base currency (RUB), the parameter is optional
currency+stringTransaction currency
payment_date+dateTransaction date
bank_system_id+stringPayment identifier. It is specified for all kinds of payments:
- for payments sent via the API
- for transfers from another bank
- for payments made through online banking
transaction_id-stringTransaction identifier. It is specified for payments sent via the API
session_id-stringSession identifier. It is specified for payments sent via the API
purpose+stringPayment purpose
counter_party+CounterPartyInformation about a payer
type+stringTransaction type. Possible values: credit (for replenishment operations), debet (for write-off operations) values

TransferDetails

Object with information about a transfer.

NameMandatoryTypeDescription
payment_method+CardPaymentMethodThe method of receiving the payout
customer+NominalPaymentParticipantInformation about a payer
recipient+NominalPaymentParticipantInformation about a recipient
purpose+stringPayout purpose in the following format: <description>; card:<card mask>
amount+AmountDetailsAmount

TransferFromBankAccount

An object with information on a transfer from a settlement account.

NameMandatoryTypeDescription
description+stringDescription

TransferFromNominalAccount

An object with information on a transfer from an escrow account. 

NameMandatoryTypeDescription
description+stringDescription

WalletDetails

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

NameMandatoryTypeDescription
id+stringBalance identifier
amount_details+AmountDetailsCurrent balance

WalletPaymentMethod

An object containing electronic wallet details.

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

YooMoneyWalletPaymentMethod

Object containing YooMoney (Yandex.Money) wallet details.

NameMandatoryTypeDescription
account+stringYooMoney wallet number, 11 to 20 digits. Example: 4100175017397
description-stringPayment description (up to 128 characters)
Feedback