Objects
accept_code
Data for sending a code.
Name | Mandatory | Type | Description |
---|---|---|---|
rest_of_attempts | + | string | Number of code sending attempts |
active_to | + | string | Code lifetime |
callback_url | + | string | Address to which to send the code |
account_details
Information about the sender and recipient accounts.
Name | Mandatory | Type | Description |
---|---|---|---|
sender | + | object | Information about the sender account |
recipient | + | object | Information about the recipient account |
account_statement
Statement details.
Name | Mandatory | Type | Description |
---|---|---|---|
date_from | + | date | Statement start date |
date_to | + | date | Statement end date |
account_number | + | string | Account number (20 digits) for which the statement is generated |
acquiring_payments
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 |
payment_details | + | object | Payment data |
amount_details | + | object | Amount |
amounts | - | object | Transaction fee |
finished_at | - | string | Completion date in ISO 8601 format |
customer | + | object | User (payer) details |
recurrent | - | object | Details needed to perform recurring payments |
participant_details | - | object | Participants' details |
refunds | - | array | Refund list |
customer_interaction | - | object | Data needed for user interaction |
transaction_info | - | object | Transaction details |
metadata | - | object | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks |
error | - | object | Error description |
Payment statuses (status
)
in_progress
– the payment is being processed.pending
– awaiting your confirmation (session/confirm
) or cancellation (session/cancel
).succeeded
– the payment has been completed successfully.failed
– the payment has not gone through due to an error.
acquiring_widget
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 Enable automatic payments checkbox in the widget interface |
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 |
amount
Amount object.
Name | Mandatory | Type | Description |
---|---|---|---|
amount | + | int | Amount value in minor currency units (ruble decimal format). For 100 rubles, enter 10000 |
currency | + | string | The ISO 4217 currency code. Case insensitive. Options: rub , eur |
amount_details
Amount object.
Name | Mandatory | Type | Description |
---|---|---|---|
amount | + | int | Amount value in minor currency units (ruble decimal format). For 100 rubles, enter 10000 |
currency | + | string | The ISO 4217 currency code. Case insensitive. Options: rub , eur |
amounts
Information on the transaction fee.
Name | Mandatory | Type | Description |
---|---|---|---|
fee | - | object | Information on the applicable fee |
balance
Account balance details.
Name | Mandatory | Type | Description |
---|---|---|---|
current_balance | - | string | Current account balance (the value can be positive or equal to 0). The value is specified in minor currency units (ruble decimal format). For 100 rubles, the value is 10000 |
bank_account
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 | - (mandatory for system_type = ru ) | object | Recipient's Russian bank account (region: ru) |
faster_payment_system | - (mandatory for system_type = faster_payment_system ) | object | Recipient's data in the Faster Payment System |
faster_payment_system_verification | - (mandatory for system_type = faster_payment_system_verification ) | object | Data for the recipient verification in the Faster Payment System |
bank_account_ru
Bank account details.
Name | Mandatory | Type | Description |
---|---|---|---|
bik | - (mandatory for the /api/v1/tokenize method) | string | Recipient’s Bank Identification Code |
account | - (mandatory for the /api/v1/tokenize method) | string | Recipient's bank account |
token | - (mandatory for the /api/v1/token/info method) | string | Bank account token |
bank_card
An unencrypted card object (can be used if you have PCI DSS).
Name | Mandatory | Type | Description |
---|---|---|---|
number | + | string | Card number |
expiration_month | - (mandatory for payments if available) | string | Month |
expiration_year | - (mandatory for payments if available) | string | Year |
security_code | - (mandatory for payments if available) | string | CVC (security code) |
cardholder_name | - | string | Cardholder's name |
card
The payout recipient's bank card details.
Name | Mandatory | Type | Description |
---|---|---|---|
type | + | string | Card details transmission type. Possible values: bank_card , encrypted_card , tokenized_card |
bank_card | - (mandatory for type = bank_card ) | object | Unencrypted card |
encrypted_card | - (mandatory for type = encrypted_card ) | object | Card with encrypted fields (tokenized) |
tokenized_card | - (mandatory for type = tokenized_card ) | object | Tokenized card number |
brand | - | string | Card information. Returned in notifications, needed for user display |
last4 | - | string | Card information. Returned in notifications, needed for user display |
bin | - | string | Bank Identification Number (BIN) (the first 6 digits of a card number) |
card_elements
The number of a card for tokenizing.
Name | Mandatory | Type | Description |
---|---|---|---|
ref | + | string | A fixed value, always number |
type | + | string | A fixed value, always card_number |
card_number | + | string | Card number |
confirm_information
Confirmation information for a transaction with an escrow account.
Name | Mandatory | Type | Description |
---|---|---|---|
transfer_details | + (for payouts to cards) | object | Information about a transfer |
account_details | + (for payouts to bank accounts) | object | Information about the sender and recipient accounts |
contacts
Contacts of the user (payout recipient or payment sender).
Name | Mandatory | Type | Description |
---|---|---|---|
- | string | User's email | |
phone | - | string | User's phone number |
counter_party
Counterparty details.
Name | Mandatory | Type | Description |
---|---|---|---|
kpp | - | string | Counterparty's KPP |
inn | - | string | Counterparty's INN |
name | + | string | Counterparty's name |
account_number | + | string | Counterparty's account number |
bank_code | + | string | Counterparty's bank BIK |
customer
(user in your system)
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.
Parent objects: acquiring_payments
, payments
.
Name | Mandatory | Type | Description |
---|---|---|---|
reference | + | string | Identifier of the user (payout recipient or payment sender) in your system (up to 128 characters) |
contacts | - | array | User contacts |
customer
(payer)
Information about the payer of a payout from an escrow account.
Parent objects: transfer_details
.
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 |
inn | - | string | Bank's INN (for cash and settlement only) |
kpp | - | string | Bank's KPP (for cash and settlement only) |
customer_authorization
Information required for payments by Uzcard or Humo cards.
Name | Mandatory | Type | Description |
---|---|---|---|
type | + | string | Authentication type. Always: sms |
suspend_key | + | string | Confirmation key required when sending a code |
accept_code | + | object | Data for sending a code |
resend_sms | + | object | Data for requesting a new code |
customer_interaction
An object describing customer interaction.
Name | Mandatory | Type | Description |
---|---|---|---|
type | + | string | Customer interaction type. Possible values: redirect , inform |
redirect | - (mandatory for type = redirect ) | object | User redirect data |
inform | - (mandatory for type = inform ) | object | Payment option data |
data
(user account)
Masked user account data.
Name | Mandatory | Type | Description |
---|---|---|---|
masked_account | + | string | First 5 and last 4 digits of an account |
data
(token and card number)
Token and tokenized card details.
Returns in response to the tokenize/elements
request.
Name | Required | Type | Description |
---|---|---|---|
number | + | object | Token information |
encrypted_card
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 |
error
Error description object.
Name | Mandatory | Type | Description |
---|---|---|---|
code | - | string | Error code |
description | - | string | Error description |
faster_payment_system
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. To get the identifier, use the fps/banks method |
description | + | string | Payout purpose |
faster_payment_system_verification
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. To get the identifier, use the fps/banks method |
fee
Information on the applicable fee. The number of objects matches the number of applicable fees.
Name | Mandatory | Type | Description |
---|---|---|---|
amount | + | int | Amount value in minor currency units (ruble decimal format). For 100 rubles, enter 10000 |
currency | + | string | The ISO 4217 currency code. Case insensitive. Options: rub , eur |
fiscalization_details
Fiscalization details.
Name | Mandatory | Type | Description |
---|---|---|---|
professional_income_taxpayer | + | object | Fiscalization details for the self-employed |
info
(bank account token)
Bank account token details.
Name | Mandatory | Type | Description |
---|---|---|---|
created_at | + | string | Creation date in ISO 8601 format |
finished_at | + | string | Completion date in ISO 8601 format |
masked_account | + | string | Masked bank account |
type | + | string | Token type. Always: bank_account_ru |
info
(tokenized bank card)
Details of a tokenized bank card.
Returns in response to the token/info
request.
Name | Mandatory | Type | Description |
---|---|---|---|
number_hash | + | string | Token (tokenized bank card) |
brand | + | string | Payment system, i.e. visa |
last4 | + | string | Last 4 card numbers |
type | + | string | Token type. Always: card |
info
(notifications number)
The 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 |
info
(notifications information)
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 for the value from tax_reference |
info
(public token)
Information about a public token.
Returns in response to the token/info
request.
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 |
type | + | string | Token type. Always: public_token |
info
(token for recurring payments or payouts)
Object with information about a token for recurring payments or payouts. More information about recurring payments and token settings.
Returns in response to the token/info
request.
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 |
initiator | - | string | Recurring payment type. Possible values: merchant – MIT payment (by default), client – CIT payment |
type | + | string | Token type. Always: recurrent_token |
info
(tokenized card details)
Tokenized card details. Returns in response to the tokenize/elements
request.
Parent objects: number
.
Name | Required | Type | Description |
---|---|---|---|
masked_card_number | + | string | Masked card number |
card_network | + | string | Card payment system |
card_type | + | string | Card type |
inform
Payment option data.
Name | Mandatory | Type | Description |
---|---|---|---|
qr | - | object | QR code for payments via FPS |
internal_transfer
Information about an internal transfer
Name | Mandatory | Type | Description |
---|---|---|---|
type | + | string | Transfer type. Possible values: transfer_from_nominal_account , transfer_from_bank_account |
transfer_from_nominal_account | - (mandatory for type = transfer_from_nominal_account ) | object | Information about a transfer from an escrow account |
transfer_from_bank_account | - (mandatory for type = transfer_from_bank_account ) | object | Information about a transfer from a settlement account |
internet_banking
Details on payments via payment systems.
Name | Mandatory | Type | Description |
---|---|---|---|
type | + | string | Payment system. Possible values: sber_pay |
sber_pay | + | object | SberPay payment system transaction details |
notification_list
The array contains data for informing the Federal Tax Service about statuses 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) |
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 |
number
Token and tokenized card details.
Name | Required | Type | Description |
---|---|---|---|
token | + | string | Token |
info | + | object | Card information |
participant_details
Payout participant details.
Name | Mandatory | Type | Description |
---|---|---|---|
sender | - | object | Sender's details |
recipient | - | object | Recipient's details |
payee
Recipient data for tax payments with extended parameters.
Name | Required | Type | Description |
---|---|---|---|
bik | + | string | Recipient bank's BIK |
account | + | string | Account number |
account_eks | + | string | Unified Treasury Account |
name | + | string | Recipient name |
inn | + | string | Recipient's INN, 10 digits |
payer
Sender data for tax payments with extended parameters.
Name | Required | Type | Description |
---|---|---|---|
kpp | + | string | Sender's KPP, 9 digits |
inn | + | string | Sender's INN, 10 digits |
payment_details
The description of the method for performing the payment.
Name | Mandatory | Type | Description |
---|---|---|---|
type | + | string | Payment method type. Possible values: card , recurrent , internal_transfer , faster_payment_system , wallet |
card | - (mandatory for type = card ) | object | Bank card details |
recurrent | - (mandatory for type = recurrent ) | object | Details for repeating the payment using the token |
internal_transfer | - (mandatory for type = internal_transfer ) | object | Internal transfer details |
faster_payment_system | - (mandatory for type = faster_payment_system ) | object | Payment via FPS |
wallet | - (mandatory for type = wallet ) | object | Payment via wallet |
payment_method
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 , tax , recurrent , tokenized_card |
card | - (mandatory for type = card ) | object | Recipient's bank card |
bank_account | - (mandatory for type = bank_account ) | object | Recipient's bank account |
wallet | - (mandatory for type = wallet ) | object | Recipient's electronic wallet |
tax | - (mandatory for type = tax ) | object | Payouts to the Russian Federal Tax Agency |
recurrent | - (mandatory for type = recurrent ) | object | Payout with token |
tokenized_card | - (mandatory for type = tokenized_card ) | object | Payout with tokenized card number |
payment_options
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 |
payments
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 | - | object | The recipient's data in your system, e.g. the login that lets you verify the recipient on your side. |
payment_method | + | object | The method of receiving the payout |
amount_details | + | object | Amount |
amounts | - | object | Transaction fee |
fiscalization_details | - | object | Fiscalization details |
participant_details | - | object | 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 list |
transaction_info | - | object | Transaction details |
metadata | - | * | Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks |
error | - | object | Error description |
Payout statuses (status
)
in_progress
– the payment is being processed.pending
– awaiting your confirmation (session/confirm
) or cancellation (session/cancel
).succeeded
– the payout has been completed successfully.failed
– the payout has not gone through because of an error.
period
Tax period description.
Name | Mandatory | Type | Description |
---|---|---|---|
type | + | string | Period type. Possible values: month , quarter |
number | + | number | Depends on the period type. Number from 1 to 12 for month , number from 1 to 4 for quarter |
year | + | string | Year, 4 digits. Example: 2021 |
professional_income_taxpayer
Fiscalization details for the self-employed.
Name | Mandatory | Type | Description |
---|---|---|---|
services | + | array | List of services provided (maximum 6) |
tax_reference | + | string | Self-employed person's INN |
receipt | - | object | Fiscalization receipt. Returned in notifications |
payer_type | - | string | Payer type (who pays the self-employed). Possible values: legal , individual , foreign |
payer_tax_number | - (mandatory for payer_type = legal ) | string | Payer's INN |
payer_name | - (mandatory for payer_type = legal ) | string | Payer name |
Payer type payer_type
Payer type. Possible values:
legal
– legal entityindividual
– individual personforeign
– non-resident of Russia
public_token
Information about a public token.
Name | Mandatory | Type | Description |
---|---|---|---|
token | + | string | Token |
qr
QR code for payments via FPS.
Name | Mandatory | Type | Description |
---|---|---|---|
content | + | string | Link to QR code |
img | + | string | QR code body |
receipt
The data of the receipt created during fiscalization.
Name | Mandatory | Type | Description |
---|---|---|---|
id | + | string | Receipt identifier |
link | - | string | Receipt link |
recipient
(recipient of a payout from an escrow account)
Information about the recipient of a payout from an escrow account.
Parent objects: transfer_details
.
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 |
inn | - | string | Bank's INN (for cash and settlement only) |
kpp | - | string | Bank's KPP (for cash and settlement only) |
recipient
(payout recipient details)
Payout recipient details. Which details are necessary depend upon the method of receiving the payout.
Parent objects: participant_details
.
Name | Mandatory | Type | Description |
---|---|---|---|
full_name | - (mandatory for payouts to any cards) | string | Full ame |
first_name | - | string | First name |
last_name | - | string | Last name |
middle_name | - | string | Patronymic 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_iso3 | - | string | The country (ISO-3166-1 alpha-3) |
account | - | string | Sender's escrow account |
recurrent
(token for recurring payments or payouts)
Object with a token for recurring payments or payouts.
Parent objects: payment_method
.
Name | Mandatory | Type | Description |
---|---|---|---|
token | + | string | Token |
recurrent
(information about a token for recurring payments or payouts)
Object with information about a token for recurring payments or payouts. More information about recurring payments and token settings.
Parent objects: acquiring_payments
, payment_details
.
Name | Mandatory | Type | Description |
---|---|---|---|
token | + | string | Token |
created_at | + (not mandatory for payment_details ) | string | Creation date in ISO 8601 format |
finished_at | + (not mandatory for payment_details ) | string | Completion date in ISO 8601 format. The setting isn't processed by the Bank |
is_active | + (not mandatory for payment_details ) | bool | Possible to conduct the operation with this token: true – allowed, false – not allowed |
initiator | - | string | Recurring payment type. Possible values: merchant – MIT payment (by default), client – CIT payment |
recurrent_token
Object with a token for recurring payments or payouts.
Name | Mandatory | Type | Description |
---|---|---|---|
token | + | string | Token |
redirect
User redirect data.
Name | Mandatory | Type | Description |
---|---|---|---|
url | + | string | Redirect address including GET parameters |
base_url | + | string | Redirect address |
method | + | string | Submission 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
andparams
objects.- Redirect the user to the redirect address specified in
base_url
using the method from themethod
parameter and including all the required parameters in the URL or request body.
refunds
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 | + | object | The amount of the refund |
created_at | + | string | Creation date |
finished_at | - | string | Completion date |
is_chargeback | - | bool | Whether the refund is made within a chargeback |
transaction_info | - | object | Transaction details |
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.
resend_sms
Data for requesting a new code.
Name | Mandatory | Type | Description |
---|---|---|---|
rest_of_attempts | + | string | Number of the code request attempts left |
allowed_from | + | string | Time starting from which a new code can be requested |
callback_url | + | string | Address to which to send a new code request |
ru
Russian bank account details (region: ru).
Name | Mandatory | Type | Description |
---|---|---|---|
bik | - (mandatory for payouts without a token) | string | Recipient’s Bank Identification Code |
account | - (mandatory for payouts without a token) | string | Recipient's bank account |
token | - (mandatory for payouts with a token) | string | Bank account token |
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 |
sber_pay
SberPay payment details.
Name | Mandatory | Type | Description |
---|---|---|---|
phone | - | string | Phone number to send PUSH or SMS to. Format: 7********** |
channel | + | ENUM | SberPay payment channel. Options: app , mobile_web , web |
self_employed_widget
Settings for the widget used for linking self-employed people to Bank 131.
Name | Mandatory | Type | Description |
---|---|---|---|
tax_reference | - (if phone is passed) | string | Self-employed person's INN |
phone | - (if tax_reference is passed) | string | Self-employed person's phone number |
sender
(escrow payer details)
Information about the payer of a payout from an escrow account.
Parent objects: transfer_details
.
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 |
inn | - | string | Bank's INN (for cash and settlement only) |
kpp | - | string | Bank's KPP (for cash and settlement only) |
sender
(payout payer details)
Payout payer details. Which details are necessary depend upon the method of receiving the payout.
Parent objects: participant_details
.
Name | Mandatory | Type | Description |
---|---|---|---|
full_name | - | string | Full ame |
first_name | - | string | First name |
last_name | - | string | Last name |
middle_name | - | string | Patronymic 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_iso3 | - | string | The country (ISO-3166-1 alpha-3) |
account | - (mandatory for making payouts from an escrow account) | string | Sender's escrow account |
services
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.
Name | Mandatory | Type | Description |
---|---|---|---|
name | + | string | Service name (up to 256 characters) |
amount_details | + | object | Service price |
quantity | - | integer | Number of services provided. Default value: 1 |
- Note: The product of the service price and the number of services provided must equal the amount of the payout.
session
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 | 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 | - | object | 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 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:
- confirm – you need to confirm the operation (
session/confirm
) or cancel it (session/cancel
). - capture – you need to perform the debit (
session/capture
) or cancel it (session/cancel
).
tax
Data for tax payment.
Name | Required | Type | Description |
---|---|---|---|
type | + | string | Tax type or payment method. Options: tax_short , tax_full |
tax_full | - (mandatory for type = tax_full ) | object | Data for tax payment with an extended set of parameters |
tax_details | - (mandatory for type = tax_short ) | object | Data for tax payment with a minimal set of parameters |
tax_details
Data for tax payments.
Name | Required | Type | Description |
---|---|---|---|
period | - (required for payments with an extended set of fields) | string | Period. Input format described below |
period | - (used only for type = tax_short ) | object | Tax period |
kbk | - (required for payments with an extended set of fields) | string | Budget classification code, 20 digits |
oktmo | - (required for payments with an extended set of fields) | string | All-Russian Classifier of Territories of Municipal Formations, 8 or 11 digits |
payment_reason | - (required for payments with an extended set of fields) | string | Payment reason. Input format described below |
document_number | - (required for payments with an extended set of fields) | string | Document number. Input format described below |
document_date | - (required for payments with an extended set of fields) | string | Document 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.
tax_full
Data for tax payment with an extended set of parameters.
Name | Required | Type | Description |
---|---|---|---|
uin | + | string | Unique identifier of the charge. Always 0 for tax payments |
description | + | string | Purpose of the payment |
tax_details | + | string | Payment data for tax payment |
payer | + | object | Sender's data for tax payment |
payee | + | object | Recipient's data for tax payment |
tokenize_widget
Settings for the tokenization widget.
Name | Mandatory | Type | Description |
---|---|---|---|
access | + | bool | Identifies whether this public key can use the tokenization widget. |
tokenized_card
A card token.
Name | Required | Type | Description |
---|---|---|---|
token | + | string | Token |
total_balance
Balance information.
Name | Mandatory | Type | Description |
---|---|---|---|
opening | + | int | Opening balance on the statement start date |
closing | + | int | Closing balance on the statement end date |
total_turnover
Information on funds movement.
Name | Mandatory | Type | Description |
---|---|---|---|
debet | + | int | Total debits over the period covered by the statement |
credit | + | int | Total credits over the period covered by the statement |
transaction_info
Transaction information.
Name | Mandatory | Type | Description |
---|---|---|---|
rrn | + | string | Retrieval Reference Number (a unique identifier generated for a bank transaction) |
ern | - | string | Acquirer Reference Number (a unique number assigned to credit card transactions) |
auth_code | - | string | Authorization code |
transactions
An array with information on transactions.
Name | Mandatory | Type | Description |
---|---|---|---|
amount | + | int | Top-up amount (non-negative values only) |
base_amount | - | int | Transaction 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 | + | string | Transaction currency |
payment_date | + | date | Transaction date |
bank_system_id | + | string | Payment 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 | - | string | Transaction identifier. It is specified for payments sent via the API |
session_id | - | string | Session identifier. It is specified for payments sent via the API |
purpose | + | string | Payment purpose |
counter_party | + | object | Payer information |
type | + | string | Transaction type. Possible values: credit (for replenishment operations), debet (for write-off operations) values |
transfer_details
Information about a transfer.
Name | Mandatory | Type | Description |
---|---|---|---|
payment_method | + | object | The method of receiving the payout |
customer | + | object | Information about a payer |
recipient | + | object | Information about a recipient |
purpose | + | string | Payout purpose in the following format: <description>; card:<card mask> |
amount | + | object | Amount |
transfer_from_bank_account
Information on a transfer from a settlement account.
Name | Mandatory | Type | Description |
---|---|---|---|
description | + | string | Description |
transfer_from_nominal_account
Information on a transfer from an escrow account.
Name | Mandatory | Type | Description |
---|---|---|---|
description | + | string | Description |
wallet
Electronic wallet details.
Name | Mandatory | Type | Description |
---|---|---|---|
type | + | string | Wallet type. Possible values: yoomoney |
yoomoney | - | object | YooMoney (Yandex.Money) wallet details |
wallets
Your guarantee payment balance details (this balance is used to perform payouts).
Name | Mandatory | Type | Description |
---|---|---|---|
id | + | string | Balance identifier |
amount_details | + | object | Current balance |
yoomoney
YooMoney (Yandex.Money) wallet details.
Name | Mandatory | Type | Description |
---|---|---|---|
account | + | string | YooMoney wallet number, 11 to 20 digits. Example: 4100175017397 |
description | - | string | Payment description (up to 128 characters) |