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 |
status
)
Payment session statuses (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_action
)
Next steps (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 |
status
)
Payout statuses (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 |
status
)
Payment statuses (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 |
status
)
Refund statuses (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 |
---|---|---|---|
- | 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 entityindividual
— individual personforeign
— 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 |
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) |