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 |
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 | 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 |
status
)
Payout statuses (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 |
status
)
Payment statuses (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 |
status
)
Refund statuses (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 |
---|---|---|---|
- | 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 entityindividual
— natural 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 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 |