Skip to main content

Methods

When processing requests, the system checks for valid input parameters, the presence of the necessary headers, and rights to perform operations.

Performing operations​

fiscalization​

Fiscalization without payment​

This request can be used to register the payment to the self-employed with the Federal Tax Agency and get a link to the receipt. The payment itself does not need to be paid (this can be done before or after, by any method).

To send a request for fiscalization, you first need to create a payment session and obtain a session ID (session_id).

Endpoint​

/api/v1/fiscalization

Request parameters​

NameMandatoryTypeDescription
session_id+stringPayment session identifier
fiscalization_details+objectFiscalization details
payment_method-objectPayout details (card, customer account, etc.)
amount_details-objectAmount
participant_details-objectInformation on payout participants
customer-objectRecipient's data in your system
metadata-*Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks
Request example
curl -X POST \
https://demo.bank131.ru/api/v1/fiscalization \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_2704",
  "fiscalization_details": {
    "professional_income_taxpayer": {
      "tax_reference": "123456789012",
      "payer_type": "legal",
      "payer_tax_number": "3316004777",
      "payer_name": "OOO Vector",
      "services": [
        {
          "name": "Goods delivery",
          "amount_details": {
            "amount": 5000,
            "currency": "rub"
          }
        },
        {
          "name": "Component delivery",
          "amount_details": {
            "amount": 5000,
            "currency": "rub"
          }
        }
      ]
    }
  }
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-objectPayment session
error-objectError
Successful response example
{
  "status": "ok",
  "session": {
    "id": "ps_2704",
    "status": "in_progress",
    "created_at": "2021-05-27T08:13:33.736384Z",
    "updated_at": "2021-05-27T08:13:33.871729Z",
    "payments": [
      {
        "id": "po_2705",
        "status": "in_progress",
        "created_at": "2021-05-27T08:13:33.860754Z",
        "amount_details": {
          "amount": 15000,
          "currency": "rub"
        },
        "fiscalization_details": {
          "professional_income_taxpayer": {
            "services": [
              {
                "name": "Goods delivery",
                "amount_details": {
                  "amount": 5000,
                  "currency": "rub"
                },
                "quantity": 2
              },
              {
                "name": "Component delivery",
                "amount_details": {
                  "amount": 5000,
                  "currency": "rub"
                },
                "quantity": 1
              }
            ],
            "tax_reference": "123456789012",
            "payer_type": "legal",
            "payer_tax_number": "3316004777",
            "payer_name": "ООО Vector"
          }
        }
      }
    ]
  }
}

recurrent/disable​

Disable token for recurring payments​

You can disable a token with this request. Send the token in the request, in the response you will get is_active: false. This means you cannot perform recurring payments with this token.

After the token has disabled, the token expiration setting finished_at may contain a weird date of the year 2000. This value won't affect anything, so please disregard it.

Endpoint​

/api/v1/recurrent/disable

Request parameters​

NameMandatoryTypeDescription
recurrent+objectObject with a token
Request example
curl -X POST \
https://demo.bank131.ru/api/v1/recurrent/disable \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "recurrent": {
    "token": "97417d4a9a23da9c2401c510a3fc45c2d1752f68ac9fd2a366698d70293b6427"
  }
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
recurrent+objectObject with a token
Response example
{
  "recurrent": {
    "token": "97417d4a9a23da9c2401c510a3fc45c2d1752f68ac9fd2a366698d70293b6427",
    "created_at": "2020-07-14T13:17:11+03:00",
    "finished_at": "2020-07-31T16:05:42+03:00",
    "is_active": false
  },
  "status": "ok"
}

session/cancel​

Operation cancellation​

This request can be sent when Bank 131 is ready to perform the operation (a payout or a payment). For example, perhaps you've received a ready_to_confirm or a ready_to_capture webhook.

If you do not want to perform the operation, you can cancel it by sending a session/cancel.

If everything looks good, send a request to confirm the operation (session/confirm) or a request to debit the amount being put on hold (session/capture).

Endpoint​

/api/v1/session/cancel

Request parameters​

NameMandatoryTypeDescription
session_id+stringSession identifier
Request example
curl -X POST \
https://demo.bank131.ru/api/v1/session/cancel \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_3230"
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-objectPayment session
error-objectError
Response example
{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "payments": [
      {
        "id": "po_2018",
        "status": "pending",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [
            {
              "email": "user@gmail.com"
            }
          ]
        },
        "payment_method": {
          "type": "card",
          "card": {
            "last4": "4242",
            "brand": "visa"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "metadata": "good"
      }
    ]
  }
}

session/capture​

Debiting amounts put on hold​

This request can be used if you are sending delayed capture payments. These payments are performed in two stages: first, the money is put on hold (for example, on the user's bank card), and then it is debited in response to your request.

The request can be sent when Bank 131 is ready to debit the money and has sent you a ready_to_capture webhook.

If you want to debit the amount put on hold, send a session/capture. You can debit the full amount on hold, or a portion of it.

To cancel the debit, send a (session/cancel).

Endpoint​

/api/v1/session/capture

Request parameters​

NameMandatoryTypeDescription
session_id+stringBank 131 session identifier
amount_details-objectAmount to be debited. Can be less than the amount on hold, but greater than 0. If not specified, the full amount of the payment will be debited
Request example
curl -X POST \
https://demo.bank131.ru/api/v1/session/capture \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_3230"
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-objectPayment session
error-objectError
Successful response example
{
    "status": "ok",
    "session": {
        "id": "ps_3230",
        "status": "in_progress",
        "created_at": "2024-05-27T02:03:00.000000Z",
        "updated_at": "2024-05-27T02:03:00.000000Z",
        "acquiring_payments": [
            {
                "id": "pm_1313",
                "status": "succeeded",
                "created_at": "2024-05-27T02:03:00.000000Z",
                "finished_at": "2024-05-27T02:03:00.000000Z",
                "customer": {
                    "reference": "lucky"
                },
                "payment_details": {
                    "type": "card",
                    "card": {
                        "brand": "visa",
                        "last4": "4242"
                    }
                },
                "amount_details": {
                    "amount": 10000,
                    "currency": "usd"
                },
                "refunds": [
                    {
                        "id": "rf_23",
                        "status": "in_progress",
                        "created_at": "2024-05-27T02:03:00.000000Z",
                        "amount_details": {
                            "amount": 10000,
                            "currency": "usd"
                        }
                    }
                ]
            }
        ]
    }
}
Unsuccessful response example
{
    "error": {
        "code": "error code",
        "description": "error description"
    },
    "status": "error"
}

session/confirm​

Operation confirmation​

This request can be sent when Bank 131 is ready to perform the operation (a payout or a payment). For example, perhaps you've received a ready_to_confirm webhook.

You'll need to check the operation parameters and make a decision. If everything looks good, confirm the operation by sending a session/confirm to Bank 131. If something is not right, cancel the operation by sending a (session/cancel) to Bank 131.

Endpoint​

/api/v1/session/confirm

Request parameters​

NameMandatoryTypeDescription
session_id+stringSession identifier
confirm_information- (mandatory for the transactions with an escrow account or when requier_confirm_information = true)objectTransaction confirmation information
Request example
curl -X POST \
https://demo.bank131.ru/api/v1/session/confirm \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_3230"
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-objectPayment session
error-objectError
Response example
{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "payments": [
      {
        "id": "po_2018",
        "status": "pending",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [
            {
              "email": "user@gmail.com"
            }
          ]
        },
        "payment_method": {
          "type": "card",
          "card": {
            "last4": "4242",
            "brand": "visa"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "metadata": "good"
      }
    ]
  }
}

session/create​

Payment session creation​

Creates a payment session on Bank 131's side.

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

Use this request if you need to request the data necessary to perform a payout or a payment from the user. For example, call the tokenization widget, show it to the user and get tokenized card details, and then send the payout request with those details.

If you are ready to provide all the data needed to perform the operation in the request, you can use the method whereby the payout (session/start/payout) or the payment (session/start/payment) starts immediately once the session has been created. In this case, you do not need to start the operation with a separate request.

The response contains the parameters of the created session.

Endpoint​

/api/v1/session/create

Request parameters​

NameMandatoryTypeDescription
payment_method-objectPayment details (card, customer account, etc.)
payment_details-objectTransfer details
amount_details-objectAmount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000
fiscalization_details-objectFiscalization details; only for payouts to the self-employed
participant_details-objectInformation about the participants (the sender and the recipient)
customerMandatory for paymentsobjectRecipient's data in your system
metadata-*Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks
Request example
curl -X POST \
https://demo.bank131.ru/api/v1/session/create \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "amount_details": {
    "amount": 10000,
    "currency": "rub"
  },
  "metadata": "order123"
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-objectPayment session
error-objectError
Response examples
{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "created",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z"
  }
}

session/init/payment​

Session creation with simultaneous payout initiation​

Can be used if you are ready to pass all the parameters needed for the payment at once.

The response contains the parameters of the session created and an object with information about the payment (acquiring_payments/payment_list).

Endpoint​

/api/v1/session/init/payment

Request parameters​

NameMandatoryTypeDescription
payment_details+objectPayment data
amount_details+objectAmount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000
participant_details-objectParticipants information
customer+objectClient data in your system
payment_options-objectAdditional payment parameters
metadata-*Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks
Request example
curl -X POST \
https://demo.bank131.ru/api/v1/session/init/payment \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_details": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "4242424242424242",
        "expiration_month": "05",
        "expiration_year": "22",
        "security_code": "123"
      }
    }
  },
  "amount_details": {
    "amount": 10000,
    "currency": "rub"
  },
  "customer": {
    "reference": "lucky"
  },
  "payment_options": {
    "return_url": "https://131.ru"
  }
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-objectPayment session
error-objectError
Response examples
{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "acquiring_payments": [
      {
        "id": "pm_203",
        "status": "in_progress",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_details": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "4242"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "payment_options": {
          "return_url": "https://131.ru"
        }
      }
    ]
  }
}

session/init/payment/sync​

Please be aware that we do not recommend implementing this method unless you have already used it before.

One-request payment​

This method allows sending a payment request and getting a response right away. Use it if you are ready to submit all payment parameters in this request.

The response contains the parameters of the session created and the acquiring_payments/payment_list object with the payment result and information.

Endpoint​

/api/v1/session/init/payment/sync

Request parameters​

Only required request parameters are listed here. You can find additional parameters by following the links in object descriptions.

NameMandatoryTypeDescription
payment_details+objectPayment data
  type+stringPayment method type. Possible values: card
  card+objectObject containing bank card details
    type+stringMethod of card information transmission. Value: bank_card
    bank_card+objectObject with open card information
      number+stringCard number
      expiration_month+stringMonth of card expiration, MM. Example: 01
      expiration_year+stringYear of card expiration, YY. Example: 22
      security_code+stringCVC/CVV code
amount_details+objectPayment amount
  amount+intAmount in ruble decimal format. The value must be greater than zero. To pay 100 rubles, specify 10000
  currency+stringISO 4217 currency code. Case insensitive. Always: rub
participant_details-objectParticipants information
customer+objectInformation about payment sender on your side
  reference+stringPayment sender ID in your system
payment_options+objectAdditional payment parameters
  return_url+stringURL to which the user is redirected after the payment has been performed. The URL must be valid
metadata-*Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks
Request example
curl -X POST \
https://proxy.bank131.ru/api/v1/session/init/payment/sync \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_details": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "4242424242424242",
        "expiration_month": "01",
        "expiration_year": "22",
        "security_code": "123"
      }
    }
  },
  "amount_details": {
    "amount": 10000,
    "currency": "rub"
  },
  "customer": {
    "reference": "lucky"
  },
  "payment_options": {
    "return_url": "https://131.ru"
  }
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-objectPayment session
error-objectError
Response examples
{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "accepted",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "acquiring_payments": [
      {
        "id": "pm_203",
        "status": "succeeded",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_details": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "4242"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "payment_options": {
          "return_url": "https://131.ru"
        }
      }
    ]
  }
}

session/init/payout​

Session creation with simultaneous payout initiation​

This request can be used if you are ready to pass all the parameters needed for the payout at once, for example when transferring a payout to a Russian bank account.

The response contains the parameters of the session created and an object with the information about the payout (payments/payout_list).

Endpoint​

/api/v1/session/init/payout

Request parameters​

NameMandatoryTypeDescription
payment_method+objectPayment details (card, customer account, etc.)
amount_details+objectAmount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000
fiscalization_details-objectFiscalization details
participant_details-objectInformation about the participants (the sender and the recipient)
customer-objectRecipient's data in your system
metadata-*Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks
Request example
curl -X POST \
https://demo.bank131.ru/api/v1/session/init/payout \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_method": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "4242424242424242"
      }
    }
  },
  "amount_details": {
    "amount": 1000,
    "currency": "rub"
  },
  "participant_details": {
    "recipient": {
      "full_name": "Ivanov Ivan"
    }
  }
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-objectPayment session
error-objectError
Successful response example
{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "payments": [
      {
        "id": "po_2018",
        "status": "in_progress",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [
            {
              "email": "user@gmail.com"
            }
          ]
        },
        "payment_method": {
          "type": "card",
          "card": {
            "last4": "4242",
            "brand": "visa"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "metadata": "good"
      }
    ]
  }
}

session/init/payout/fiscalization​

Session creation and payout start, with additional check that all the fiscalization data has been provided​

Can be used for payouts to self-employed people if you are ready to provide all the information about the self-employed person and the details necessary to create the payout at once, for example when transferring a payout to a Russian bank account.

The response contains the parameters of the session created and an object with the information about the payout (payments/payout_list) with the data necessary to send the receipt.

Endpoint​

/api/v1/session/init/payout/fiscalization

NameMandatoryTypeDescription
payment_method-objectPayment details (card, customer account, etc.)
amount_details-objectAmount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000
fiscalization_details-objectFiscalization details
participant_details-objectInformation about the participants (the sender and the recipient)
customer-objectRecipient's data in your system
metadata-*Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks
Request example
curl -X POST \
https://proxy.bank131.ru/api/v1/session/init/payout/fiscalization \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "fiscalization_details": {
    "professional_income_taxpayer": {
      "tax_reference": "590000000000",
      "payer_type": "legal",
      "payer_tax_number": "3300000000",
      "payer_name": "OOO Vector",
      "services": [
        {
          "name": "Service description",
          "amount_details": {
            "amount": 10000,
            "currency": "rub"
          }
        }
      ]
    }
  },
  "payment_method": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "4242424242424242"
      }
    }
  },
  "amount_details": {
    "amount": 10000,
    "currency": "rub"
  },
  "metadata": "order123",
  "participant_details": {
    "recipient": {
      "full_name": "Ivanov Ivan"
    }
  }
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-objectPayment session
error-objectError
Response examples
{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "created",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "payments": [
      {
        "id": "po_2909",
        "status": "in_progress",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "payment_method": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "4242"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "fiscalization_details": {
          "professional_income_taxpayer": {
            "tax_reference": "590000000000",
            "payer_type": "legal",
            "payer_tax_number": "3300000000",
            "payer_name": "OOO Vector",
            "services": [
              {
                "name": "Service description",
                "amount_details": {
                  "amount": 10000,
                  "currency": "rub"
                }
              }
            ]
          }
        },
        "metadata": "order123",
        "participant_details": {
          "recipient": {
            "full_name": "Ivanov Ivan"
          }
        }
      }
    ]
  }
}

session/refund​

Refund​

You can use this request to return money to the user after a successful payment.

After completing the refund, Bank 131 will send you a payment_refunded webhook.

Endpoint​

/api/v1/session/refund

Request parameters​

NameMandatoryTypeDescription
session_id+stringIdentifier of a successful payment session which needs to be refunded
amount_details-objectAmount of the refund. If not specified, the refund will be made for the full amount of the payment
metadata-*Additional information
Request example
curl -X POST \
https://demo.bank131.ru/api/v1/session/refund \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_3230"
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-objectPayment session
error-objectError
Response example
{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "acquiring_payments": [
      {
        "id": "pm_2705",
        "status": "succeeded",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "finished_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_details": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "4242"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "refunds": [
          {
            "id": "rf_23",
            "status": "in_progress",
            "created_at": "2018-05-27T02:03:00.000000Z",
            "amount_details": {
              "amount": 10000,
              "currency": "rub"
            }
          }
        ]
      }
    ]
  }
}

session/start/payment​

Payment start​

This request can be used to start a payment within an existing session. In the parameters, you can pass the data necessary to perform the payment or change pieces of data that have already been passed.

Endpoint​

/api/v1/session/start/payment

Request parameters​

NameMandatoryTypeDescription
session_id+stringPayment session identifier
payment_details-objectPayment data
amount_details-objectAmount
participant_details-objectInformation about the participants (the payer and the recipient)
customer-objectPayment sender information in your system
payment_options-objectAdditional payment settings
metadata-*Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks
Request example
curl -X POST \
https://demo.bank131.ru/api/v1/session/start \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_3230",
  "payment_details": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "4242424242424242",
        "expiration_month": "01",
        "expiration_year": "26",
        "security_code": "123"
      }
    }
  },
  "amount_details": {
    "amount": 10000,
    "currency": "rub"
  },
  "customer": {
    "reference": "lucky"
  },
  "payment_options": {
    "return_url": "https://www.131.ru"
  },
  "metadata": "good"
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-objectPayment session
error-objectError
Response examples
{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2024-08-21T06:21:36.913863Z",
    "updated_at": "2024-08-21T06:21:56.832509Z",
    "acquiring_payments": [
      {
        "id": "pm_3232",
        "status": "in_progress",
        "created_at": "2024-08-21T06:21:56.846204Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_details": {
          "type": "card",
          "card": {
            "last4": "4242",
            "brand": "visa",
            "country_iso3": "RUS"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "payment_options": {
          "return_url": "https://www.131.ru"
        },
        "metadata": "good"
      }
    ]
  }
}

session/start/payout​

Payout start​

This request can be used to start a payout within an existing session. In the parameters, you can pass the data necessary to perform the payout or change pieces of data that have already been passed.

If you are using the payout widget to get the user's tokenized bank card details, you can pass them using this request.

Endpoint​

/api/v1/session/start/payout

Request parameters​

NameMandatoryTypeDescription
session_id+stringPayment session identifier
payment_method-objectPayout details (card, customer account, etc.)
amount_details-objectAmount
participant_details-objectInformation on payout participants
customer-objectRecipient's data in your system
metadata-*Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks
Request example
curl -X POST \
https://demo.bank131.ru/api/v1/session/start/payout \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_3230"
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-objectPayment session
error-objectError
Successful response example
{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "payments": [
      {
        "id": "po_2018",
        "status": "in_progress",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [
            {
              "email": "user@gmail.com"
            }
          ]
        },
        "payment_method": {
          "type": "card",
          "card": {
            "last4": "4242",
            "brand": "visa"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "metadata": "good"
      }
    ]
  }
}

session/start/payout/fiscalization​

Payout start, with check that all fiscalization data has been provided​

This request can be used to start a payout within an existing session. In the parameters, you can pass the data necessary to perform the payout or change pieces of data that have already been passed.

If you are using the payout widget to get the user's tokenized bank card details, you can pass them using this request.

Endpoint​

/api/v1/session/start/payout/fiscalization

Request parameters​

NameMandatoryTypeDescription
session_id+stringPayment session identifier
payment_method-objectPayment details (card, customer account, etc.)
amount_details-objectAmount
fiscalization_details-objectFiscalization details
participant_details-objectInformation on payout participants
customer-objectRecipient's data in your system
metadata-*Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks
Request example
curl -X POST \
https://demo.bank131.ru/api/v1/session/start/payout/fiscalization \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_3230",
  "fiscalization_details": {
    "professional_income_taxpayer": {
      "tax_reference": "590000000000",
      "payer_type": "legal",
      "payer_tax_number": "330000000000",
      "payer_name": "OOO Vector",
      "services": [
        {
          "name": "Goods delivery",
          "amount_details": {
            "amount": 5000,
            "currency": "rub"
          }
        }
      ]
    }
  }
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-objectPayment session
error-objectError
Successful response example
{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "payments": [
      {
        "id": "po_203",
        "status": "in_progress",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "payment_method": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "4242"
          }
        },
        "amount_details": {
          "amount": 5000,
          "currency": "rub"
        },
        "fiscalization_details": {
          "professional_income_taxpayer": {
            "services": [
              {
                "name": "Goods delivery",
                "amount_details": {
                  "amount": 5000,
                  "currency": "rub"
                },
                "quantity": 1
              }
            ],
            "tax_reference": "590613976192",
            "payer_type": "legal",
            "payer_tax_number": "3316004710",
            "payer_name": "ООО Vector"
          }
        }
      }
    ]
  }
}

token​

Generation of a token to work with widgets​

The token is needed to access Bank 131's JavaScript library. You can generate it using this request and use it to work with widgets.

The token is valid for 24 hours. It can be used for a single operation. When sending a request, you should pass the working parameters with widgets that you are going to use with that token.

Endpoint​

/api/v1/token

Request parameters​

NameMandatoryTypeDescription
tokenize_widget-objectData required by the tokenization widget
self_employed_widget-objectData required by the self-employed registration widget
acquiring_widget-objectData required by the payment form widget
An example of how to create a token to perform a payout which involves obtaining card details via the widget and linking a self-employed person
curl -X POST \
https://demo.bank131.ru/api/v1/token \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "tokenize_widget": {
    "access": true
  },
  "self_employed_widget": {
    "tax_reference": "111111111111"
  }
}'
An example of a request to create a token to perform a payment through a payment form
curl -X POST \
https://demo.bank131.ru/api/v1/token \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "acquiring_widget": {
    "session_id": "ps_123456"
  }
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
public_token-stringPublic token
error-objectError
Response examples
{
  "status": "ok",
  "public_token": "e065c2f1328e74156a883c00e210a4b1b1451782bbfdd18ae8d05715e05d8539"
}

token/info​

Receiving information via token​

Operations with bank cards are often carried out with tokenized values. For payouts and payments through widgets, a public token is created. A token ca also be created for recurring payments.

For any payment token you can get information:

  • About the bank card for which that token was created – this will be the hidden card number and payment system.
  • About the token itself – type of token, time of creation, expiration date, active or inactive at the moment of inquiry.

This method can be used, for example, to learn the hidden card number and show the user which card the funds will be debited from. Or if you need to check the token expiration date.

Endpoint​

/api/v1/token/info

Request parameters​

NameMandatoryTypeDescription
type+stringType of request. Options: card, public_token, recurrent_token, bank_account_ru
card- (mandatory for type = card)objectBank card details
public_token- (mandatory for type = public_token)objectToken details
recurrent_token- (mandatory for type = recurrent_token)objectToken details
bank_account_ru- (mandatory for type = bank_account_ru)objectBank account details
Information request examples

You send tokenized bank card details and receive a hidden card and payment system.

curl -X POST \
https://demo.bank131.ru/api/v1/token/info \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "type": "card",
  "card": {
    "type": "encrypted_card",
    "encrypted_card": {
      "number_hash": "card_number_hash (token)"
    }
  }
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
info-objectInformation about the token, depending on the type of request (type): tokenized bank card, public token, token for recurring payments or payouts, or bank account token
error-objectError
Response examples
{
  "status": "ok",
  "info": {
    "number_hash": "card_number_hash",
    "brand": "visa",
    "last4": "4242",
    "type": "card"
  }
}

tokenize​

This method is used for tokenizing a bank account (payout). Use it to get a token and a masked account number. The token received in the response does not expire.

You can tokenize any account that passes verification against a specified range of accounts. Otherwise, the “Enter a different account number” error will be returned.

Endpoint​

/api/v1/tokenize

Request parameters​

NameMandatoryTypeDescription
type+stringBank account type
bank_account_ru+objectRussian bank account details
  bik+stringBank BIK
  account+stringAccount number
Request example
curl -X POST \
https://proxy-stage.bank131.ru/api/v1/tokenize \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "type": "bank_account_ru",
  "bank_account_ru": {
    "bik": "044525974",
    "account": "40817810400003869535"
  }
}'

Response parameters​

NameMandatoryTypeDescription
status+stringBank account type
token-stringToken
data-objectMasked user account data object
error-objectError
Response examples
{
  "status": "ok",
  "token": "2c6ebe1368407b922057efee0fed58360dae1d28af50fa6734bb54c61a763c24",
  "data": {
    "masked_account": "40702***0025"
  }
}

tokenize/elements​

Use this method to get a tokenized card number when you are not allowed to store card details on your side.

To start using this method, please contact your manager in Bank 131.

Endpoint​

/api/v1/tokenize/elements

Request parameters​

NameMandatoryTypeDescription
card_elements+objectCard number
Request example
curl -X POST \
https://proxy-stage.bank131.ru/api/v1/tokenize/elements \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "card_elements": [
    {
      "ref": "number",
      "type": "card_number",
      "card_number": "4242424242424242"
    }
  ]
}'
Response example
{
  "status": "ok",
  "data": {
    "number": {
      "token": "adb0eb0ac3f1f5f627f15aa8ca47b13483325ec42baab5e87cbff5f784dca919",
      "info": {
        "masked_card_number": "424242******4242",
        "card_network": "visa",
        "card_type": "visa"
      }
    }
  }
}

Information​

fps/banks​

You can use this request to get a list of names and identifiers of banks-recipients of the Faster Payment System.

Endpoint​

/api/v1/fps/banks

Request example
curl -X GET
https://demo.bank131.ru/api/v1/fps/banks \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{}'
Response example
{
  "banks": [
    {
      "id": "100000000243",
      "eng_name": "National Standard Bank",
      "ru_name": "Национальный стандарт"
    },
    {
      "id": "100000000056",
      "eng_name": "Khlynov",
      "ru_name": "Хлынов"
    },
    ...
  ]
}

fps/customer_verification​

You can use this request to check whether a recipient is registered in the Faster Payment System (FPS). If the user is found in the FPS, the session will have a successful status, otherwise the session will be canceled. This operation is free of charge and is confirmed automatically (ready_to_confirm is not sent).

Endpoint​

/api/v1/fps/customer_verification

Request parameters​

NameMandatoryTypeDescription
payment_method+objectPayment details (card, customer account, etc.)
participant_details+objectInformation about the participants (the sender and the recipient)
Request example
curl -X POST \
https://demo.bank131.ru/api/v1/fps/customer_verification \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_method": {
    "type": "bank_account",
    "bank_account": {
      "system_type": "faster_payment_system_verification",
      "faster_payment_system_verification": {
        "phone": "79261234567",
        "bank_id": "100000000069"
      }
    }
  },
  "participant_details": {
    "recipient": {
      "first_name": "Иван",
      "last_name": "Иванов",
      "middle_name": "Иванович"
    }
  }
}

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-objectPayment session
error-objectError
Response examples
{
  "status": "ok",
  "session": {
    "id": "ps_109941",
    "status": "in_progress",
    "created_at": "2022-03-01T11:57:31.652396Z",
    "updated_at": "2022-03-01T11:57:31.861329Z",
    "payments": [
      {
        "id": "po_31668",
        "status": "in_progress",
        "created_at": "2022-03-01T11:57:31.895773Z",
        "payment_method": {
          "type": "bank_account",
          "bank_account": {
            "system_type": "faster_payment_system_verification",
            "faster_payment_system_verification": {
              "phone": "79261234567",
              "bank_id": "100000000069"
            }
          }
        },
        "participant_details": {
          "recipient": {
            "first_name": "Иван",
            "last_name": "Иванов",
            "middle_name": "Иванович"
          }
        }
      }
    ]
  }
}

report/account_balance​

Use this method to get your settlement or escrow account balance. More on account balance.

Endpoint​

/api/v1/report/account_balance

Request parameters​

NameMandatoryTypeDescription
account_number+stringAccount number. The account number must start as follows: 40702, 40703, 40802, 40807, 40701
Request example
curl -X GET \
https://demo.bank131.ru/api/v1/report/account_balance \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "account_number": "40702810400000000333"
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Options: error, ok
account_number-stringAccount number
account_currency-stringAccount currency according to ISO 4217. Example: RUB
balance-objectBalance details
error-objectError
Response examples
{
  "status": "ok",
  "account_number": "40702810400000000333",
  "account_currency": "RUB",
  "balance": {
    "current_balance": 20900
  }
}

report/account_statement​

Use this method to get bank statements for your settlement or escrow account opened in rubles. Statements can only be generated for a day. To learn more, click here.

Endpoint​

/api/v1/report/account_statement

Request parameters​

NameMandatoryTypeDescription
date_from+dateStatement start date. Example: 2023-06-01
date_to+dateStatement end date. Example: 2023-06-01
account_number+stringAccount number (20 digits) for which you request a statement

The date_from and date_to values must match.

Request example
curl -X GET \
https://demo.bank131.ru/api/v1/report/account_statement \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
  "date_from": "2023-06-01",
  "date_to": "2023-06-01",
  "account_number": "40702810600200000014"
}

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Options: error, ok
method+objectMethod data
  name+stringMethod name (account_statement)
  account_statement+objectStatement details
    date_from+dateStatement start date
    date_to+dateStatement end date
    account_number+stringAccount number (20 digits) for which the statement is generated
    total_turnover+objectInformation on funds movement
      debet+intTotal debits over the period covered by the statement
      credit+intTotal credits over the period covered by the statement
    total_balance+objectBalance information
      opening+intOpening balance on the statement start date
      closing+intClosing balance on the statement end date
    transactions+objectInformation on transactions
      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+objectCounterparty details
        kpp-stringCounterparty's KPP
        inn-stringCounterparty's INN
        name+stringCounterparty's name
        account_number+stringCounterparty's account number
        bank_code+stringCounterparty's bank BIK
      type+stringTransaction type. Possible values: credit (for replenishment operations), debet (for write-off operations) values
Successful response example
{
  "status": "ok",
  "method": {
    "name": "account_statement",
    "account_statement": {
      "date_from": "2022-11-12T18:19:32.487+0000",
      "date_to": "2022-11-13T18:19:32.487+0000",
      "account_number": "40703810500000000025",
      "total_turnover": {
        "debet": 0,
        "debet_base": null,
        "credit": 100,
        "credit_base": null
      },
      "total_balance": {
        "opening": 0,
        "opening_base": null,
        "closing": 100,
        "closing_base": null
      },
      "transactions": [
        {
          "amount": 10000,
          "base_amount": null,
          "currency": "RUB",
          "payment_date": "2022-11-13",
          "bank_system_id": "2080040097819020",
          "transaction_id": "c7b923ec-844f-4d98-ad02-795d62fe1989",
          "session_id": "ps_3230",
          "purpose": "Account replenishment",
          "counter_party": {
            "kpp": "165501001",
            "inn": "1655415696",
            "name": "Fee for money transfer processing services",
            "account_number": "70606810600004710401",
            "bank_code": "049205131"
          },
          "type": "credit"
        }
      ]
    }
  }
}
Unsuccessful response examples

date_from does not match date_to

{
  "status": "error",
  "error": {
    "description": "Invalid input request parameters:  (max interval is 1 day)",
    "code": "invalid_request"
  }
}

date_from is greater than date_to

{
  "status": "error",
  "error": {
    "description": "Invalid input request parameters:  (date_to must be greater than date_from);  (max interval is 1 day)",
    "code": "invalid_request"
  }
}

Invalid date in date_from

{
  "status": "error",
  "error": {
    "description": "Invalid value in date_from",
    "code": "invalid_request"
  }
}

Invalid date in date_to

{
  "status": "error",
  "error": {
    "description": "Invalid value in date_to",
    "code": "invalid_request"
  }
}

session/status​

Obtaining session information​

You can send this request if you want to obtain full information about the payment session. For example, you can check whether the payout was completed, or check if you are able to debit the amount put on hold during a card payment.

The response contains the payment session with details about all the operations performed during it.

Endpoint​

/api/v1/session/status

Request parameters​

NameMandatoryTypeDescription
session_id+stringPayment session identifier
Request example
curl -X POST \
https://demo.bank131.ru/api/v1/session/status \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_3230"
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-objectPayment session
error-objectError
Successful response example
{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "next_action": "confirm",
    "payments": [
      {
        "id": "po_2018",
        "status": "in_progress",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [
            {
              "email": "user@gmail.com"
            }
          ]
        },
        "payment_method": {
          "type": "card",
          "card": {
            "last4": "4242",
            "brand": "visa",
            "bin": "220220"
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "transaction_info": {
          "rrn": "425307614918",
          "auth_code": "057441"
        },
        "metadata": "good"
      }
    ]
  }
}

wallet/balance​

You can use this request to check your current Bank 131 deposit balance.

note

This method can be used for payouts only. You can find your acquiring balance information in your remote banking service account in the Statements section, provided that compensations are paid to your Bank 131 account.

This is necessary in order to make sure there is enough money on the balance:

  • for payouts
  • for returns

If the amount is insufficient, you can top up your deposit.

The request does not return the information about your escrow account balance. You may find this information in your remote banking service account in the Accounts section or use the report/account_balance method.

Endpoint​

/api/v1/wallet/balance

Request parameters​

NameMandatoryTypeDescription
request_datetime+stringTimestamp of the request in ISO 8601
Request example
curl -X POST \
https://demo.bank131.ru/api/v1/wallet/balance  \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "request_datetime": "2019-10-14T19:53:00+03:00"
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
wallets-objectList of guarantee payment accounts available at Bank 131
error-objectError
Response example
{
  "status": "ok",
  "wallets": [
    {
      "id": "131",
      "amount_details": {
        "amount": 13100,
        "currency": "rub"
      }
    }
  ]
}

Self-employed people​

 

check and request/status​

Checking the status of a self-employed person​

This request allows you to check whether an individual is self-employed or not using their INN.

The requests consists of two parts:

  1. Send a check request, passing the individual's INN in the tax_reference parameter, and wait for a request_id identifier in response.
  2. Send a request/status request with this identifier. The response will tell you whether the INN is registered with the Federal Tax Agency as belonging to a self-employed person and whether it is linked to Bank 131.

The check request should not be sent more than once every 30 seconds.

The endpoint to which the check request is sent​

/api/v1/npd/check

Request parameters for check​

NameMandatoryTypeDescription
tax_reference+stringIndividual's INN
Request example for check
curl -X POST \
https://demo.bank131.ru/api/v1/npd/check   \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "tax_reference": "123456789012"
}'

Response parameters for check​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
request_id+stringRequest identifier
Response example for check
{
  "status": "ok",
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}

The endpoint to which the request/status request is sent​

/api/v1/npd/request/status

Request parameters for request/status​

NameMandatoryTypeDescription
request_id+stringIdentifier from the check request
Request example for request/status
curl -X POST \
https://demo.bank131.ru/api/v1/npd/request/status  \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}'

Response parameters for request/status​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
is_professional_income_taxpayer-boolShows whether the individual is self-employed
is_linked-boolShows whether the self-employed person is linked to Bank 131
error-objectError
Examples of responses to request/status for check
{
  "status": "ok",
  "is_professional_income_taxpayer": true,
  "is_linked": true
}

npd/accruals and npd/request/status​

The method allows to obtain detailed information about tax accruals and bonus amount for the self-employed.

The request consists of two parts:

  1. Send an npd/accruals request, passing a self-employed person's details, and receive the request_id identifier in response.
  2. Send an npd/request/status request with this identifier. In response, you will receive detailed information about tax accruals and bonus amount for the self-employed.

The endpoint to send the npd/accruals request​

/api/v1/npd/accruals

Request parameters for npd/accruals​

NameMandatoryTypeDescription
tax_reference_list+arrayList of tax reference numbers (INN). Limited to 100 INNs per single request
Request example for npd/accruals
curl -X POST \
https://demo.bank131.ru/api/v1/npd/accruals  \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "tax_reference_list": [
    "111111111111"
  ]
}'

Response parameters for npd/accruals​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
request_id-stringIdentifier
Response example for npd/accruals
{
  "status": "ok",
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}

The endpoint to send the npd/request/status request​

/api/v1/npd/request/status

Request parameters for npd/request/status​

NameMandatoryTypeDescription
request_id+stringIdentifier passed in response at npd/accruals
Request example for npd/request/status
curl -X POST \
https://demo.bank131.ru/api/v1/npd/request/status  \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}'

Response parameters for npd/request/status​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
accruals-jagged array
  tax_charge_list-arrayList of various taxes accrued
    amount-stringAccrued amount
    due_date-stringPayment due date
    tax_period_id-stringTax period identifier. The value format: YYYYMM
    oktmo-stringRussian National Classification of Municipal Territories (OKTMO) of the activity region
    kbk-stringBudgetary classification code
    paid_amount-stringAmount of payments received in Automated Information System (AIS) Tax 3 by this accrual
    create_time-stringDate and time of the tax accrual
    id-stringInternal identifier of the tax accrual in the Self-employment tax (NPD) Payment order (PP)
  krsb_list-arrayDebt data by the fiscal compliance card
    debt-stringDebt amount by the fiscal compliance card
    penalty-stringPenalty amount by the fiscal compliance card
    overpayment-stringOverpayment amount by the fiscal compliance card
    oktmo-stringRussian National Classification of Municipal Territories (OKTMO) of the activity region related to the fiscal compliance card (KRSB)
    kbk-stringBudgetary classification code related to the fiscal compliance card (KRSB)
    tax_organ_code-stringCode of the tax authority related to the fiscal compliance card (KRSB)
    update_time-stringDate / Time of card revision in the Self-employment tax (NPD) Payment order (PP)
    id-stringInternal identifier of the card in the Self-employment tax (NPD) Payment order (PP)
  inn-stringTax reference number (INN)
Response example for npd/request/status
{
  "status": "ok",
  "accruals": [
    {
      "tax_charge_list": [
        {
          "amount": "",
          "due_date": "",
          "tax_period_id": "",
          "oktmo": "",
          "kbk": "",
          "paid_amount": "",
          "create_time": "",
          "id": ""
        }
      ],
      "krsb_list": [
        {
          "debt": "",
          "penalty": "",
          "overpayment": "",
          "oktmo": "",
          "kbk": "",
          "tax_organ_code": "",
          "update_time": "",
          "id": ""
        }
      ],
      "inn": "111111111111"
    }
  ]
}

npd/notifications/count and npd/request/status​

The method allows to obtain the number of unread notifications the Federal Tax Service sent to the self-employed.

The request consists of two parts:

  1. Send an npd/notifications/count request, passing a self-employed person's details, and receive the request_id identifier in response.
  2. Periodically send an npd/request/status request with this identifier. In response, you will receive the number of unread notifications. The pending status indicates that you must repeat the request.

The endpoint to send the npd/notifications/count request​

/api/v1/npd/notifications/count

Request parameters for npd/notifications/count​

NameMandatoryTypeDescription
tax_reference_list+arrayList of tax reference numbers (INN) (limited to 1000 per single request)
Request example for npd/notifications/count
curl -X POST \
https://demo.bank131.ru/api/v1/npd/notifications/count  \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "tax_reference_list": [
    "123456789012"
  ]
}'

Response parameters for npd/notifications/count​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
request_id+stringIdentifier
Response example for npd/notifications/count
{
  "status": "ok",
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}

The endpoint to send the npd/request/status request​

/api/v1/npd/request/status

Request parameters for npd/request/status​

NameMandatoryTypeDescription
request_id+stringIdentifier passed in response at npd/notifications/count
Request example for npd/request/status
curl -X POST \
https://demo.bank131.ru/api/v1/npd/request/status  \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}'

Response parameters for npd/request/status​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
info-arrayNumber of notifications
Response example for npd/request/status
{
  "status": "ok",
  "info": [
    {
      "tax_reference": "123456789012",
      "count": 0
    }
  ]
}

npd/notifications/mark_as_delivered and npd/request/status​

The method allows to inform the Federal Tax Service that notifications were delivered to a self-employed person. This method must be used after the notifications/read method.

The request consists of two parts:

  1. Send an npd/notifications/mark_as_delivered request, passing a self-employed person's details, and receive the request_id identifier in response;
  2. Send an npd/request/status request with this identifier. In response, you will receive the status of the delivery.

The endpoint to send the npd/notifications/mark_as_delivered request​

/api/v1/npd/notifications/mark_as_delivered

Request parameters for npd/notifications/mark_as_delivered​

NameMandatoryTypeDescription
notification_list+arrayInformation about notifications
Request example for npd/notifications/mark_as_delivered
curl -X POST \
https://demo.bank131.ru/api/v1/npd/notifications/mark_as_delivered  \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "notification_list": [
    {
      "message_id_list": [
        "123",
        "234"
      ],
      "tax_reference": "123456789012"
    }
  ]
}'

Response parameters for npd/notifications/mark_as_delivered​

NameMandatoryTypeDescription
request_id+stringIdentifier
Response example for npd/notifications/mark_as_delivered
{
  "status": "ok",
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}

The endpoint to send the npd/request/status request​

/api/v1/npd/request/status

Request parameters for npd/request/status​

NameMandatoryTypeDescription
request_id+stringIdentifier passed in response at npd/notifications/read
Request example for npd/request/status
curl -X POST \
https://demo.bank131.ru/api/v1/npd/request/status \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}'

Response parameters for npd/request/status​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
Response example for npd/request/status
{
  "status": "ok"
}

npd/notifications/read and npd/request/status​

The method allows to obtain the detailed information about unread notifications the Federal Tax Service sent to the self-employed.

The request consists of two parts:

  1. Send an npd/notifications/read request, passing a self-employed person's details, and receive the request_id identifier in response.
  2. Periodically send an npd/request/status request with this identifier. In response, you will receive detailed information about unread notifications. The pending status indicates that you must repeat the request.

The endpoint to send the npd/notifications/read request​

/api/v1/npd/notifications/read

Request parameters for npd/notifications/read​

NameMandatoryTypeDescription
tax_reference_list+arrayList of tax reference numbers (INN)
get_read+booleanSend the already read notifications in response. Possible values: true – send; false – do not send
get_archived+booleanSend the archived notifications in response. Possible values: true – send; false – do not send
Request example for npd/notifications/read
curl -X POST \
https://demo.bank131.ru/api/v1/npd/notifications/read \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "tax_reference_list": [
    "123456789012"
  ],
  "get_read": false,
  "get_archived": false
}'

Response parameters for npd/notifications/read​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
request_id+stringIdentifier
Response example for npd/notifications/read
{
  "status": "ok",
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}

The endpoint to send the npd/request/status request​

/api/v1/npd/request/status

Request parameters for npd/request/status​

NameMandatoryTypeDescription
request_id+stringIdentifier passed in response at npd/notifications/read
Request example for npd/request/status
curl -X POST \
https://demo.bank131.ru/api/v1/npd/request/status \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}'

Response parameters for npd/request/status​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
info-array List of parameters for each tax reference number (INN)
Response example for npd/request/status
{
  "status": "ok",
  "info": [
    {
      "tax_reference": "123456789012",
      "notifications": [
        {
          "id": "132313",
          "title": "131.ru is asking for permission to act on your behalf",
          "message": "131.ru has asked you for permission to perform certain operations on your behalf. You can view the list of the operations and grant the permission by clicking <b>Allow</b>, or deny by clicking <b>Deny</b>",
          "status": "NEW",
          "created_at": "2023-03-22T13:29:55+00:00"
        }
      ]
    }
  ]
}

npd/notifications/update and npd/request/status​

The method allows to inform the Federal Tax Service that notifications were read by the self-employed. The method must be used after the notifications/mark_as_delivered method.

The request consists of two parts:

  1. Send an npd/notifications/update request, passing a self-employed person's details, and receive the request_id identifier in response.
  2. Send an npd/request/status request with this identifier. In response, you will receive the status of the request.

The endpoint to send the npd/notifications/update request​

/api/v1/npd/notifications/update

Request parameters for npd/notifications/update​

NameMandatoryTypeDescription
notification_list+arrayInformation about notifications
Request example for npd/notifications/update
curl -X POST \
https://demo.bank131.ru/api/v1/npd/notifications/update \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "notification_list": [
    {
      "tax_reference": "123456789012"
    }
  ]
}'

Response parameters for npd/notifications/update​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
request_id-stringIdentifier
Response example for npd/notifications/update
{
  "status": "ok",
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}

The endpoint to send the npd/request/status request​

/api/v1/npd/request/status

Request parameters for npd/request/status​

NameMandatoryTypeDescription
request_id+stringIdentifier passed in response at npd/notifications/update
Request example for npd/request/status
curl -X POST \
https://demo.bank131.ru/api/v1/npd/request/status \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}'

Response parameters for npd/request/status​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
Response example for npd/request/status
{
  "status": "ok"
}

npd/taxpayer/account_status and npd/request/status​

The method allows to obtain general information about tax accruals and bonus amount for the self-employed.

The request consists of two parts:

  1. Send an npd/taxpayer/account_status request, passing a self-employed person's details, and receive the request_id identifier in response.
  2. Send an npd/request/status request with this identifier. In response, you will receive general information about tax accruals and bonus amount for the self-employed.

The endpoint to send the npd/taxpayer/account_status request​

/api/v1/npd/taxpayer/account_status

Request parameters for npd/taxpayer/account_status​

NameMandatoryTypeDescription
tax_reference+stringTax reference number (INN). Limited to 1 INN per single request
Request example for npd/taxpayer/account_status
curl -X POST \
https://demo.bank131.ru/api/v1/npd/taxpayer/account_status \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "tax_reference": "123456789012"
}'

Response parameters for npd/taxpayer/account_status​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
request_id-stringIdentifier
Response example for npd/taxpayer/account_status
{
  "status": "ok",
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}

The endpoint to send the npd/request/status request​

/api/v1/npd/request/status

Request parameters for npd/request/status​

NameMandatoryTypeDescription
request_id+stringIdentifier passed in response at npd/taxpayer/account_status
Request example for npd/request/status
curl -X POST \
https://demo.bank131.ru/api/v1/npd/request/status \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}'

Response parameters for npd/request/status​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
bonus_amount-stringBonus amount
unpaid_amount-stringTotal unpaid amount
debt_amount-stringUnpaid debt, included into total unpaid amount
Response example for npd/request/status
{
  "status": "ok",
  "bonus_amount": "9972.3624",
  "unpaid_amount": "0",
  "debt_amount": "0"
}

npd/taxpayer/check_personal_info and npd/request/status​

Verification of the self-employed data​

This request allows to verify with the Federal Tax Service if there is any inconsistency in data (INN, full name, phone number) provided by a self-employed person.

The request consists of two parts:

  1. Send an npd/taxpayer/check_personal_info request, passing a self-employed person's INN, full name, and phone number, and receive the request_id identifier in response.
  2. Periodically send an npd/request/status request with this identifier. In response, you will receive a list of inconsistent parameters, if there is any. The pending status indicates that you must repeat the request.

The endpoint to send the npd/taxpayer/check_personal_info request​

/api/v1/npd/taxpayer/check_personal_info

Request parameters for npd/taxpayer/check_personal_info​

NameMandatoryTypeDescription
first_name+stringFirst name
second_name+stringFamily name
patronymic+stringPatronymic name
tax_reference+stringTax reference number (INN)
phone+stringPhone number in the "7ХХХХХХХХХХ" format
Request example for npd/taxpayer/check_personal_info
curl -X POST \
https://demo.bank131.ru/api/v1/npd/taxpayer/check_personal_info  \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "status": "ok",
  "bonus_amount": "9972.3624",
  "unpaid_amount": "0",
  "debt_amount": "0"
}'

Response parameters for npd/taxpayer/check_personal_info​

NameMandatoryTypeDescription
request_id+stringIdentifier
Response example for npd/taxpayer/check_personal_info
{
  "status": "ok",
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}

The endpoint to send the npd/request/status request​

/api/v1/npd/request/status

Request parameters for npd/request/status​

NameMandatoryTypeDescription
request_id+stringIdentifier passed in response at npd/taxpayer/check_personal_info
Request example for npd/request/status
curl -X POST \
https://demo.bank131.ru/api/v1/npd/request/status  \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "request_id": "07adcced-8eb8-49c6-82ce-c3ded0b5bda6"
}'

Response parameters for npd/request/status​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok, pending
success-boolInconsistency in data. true - consistent data; false - inconsistent data
violations-array[string]Parameters with inconsistent data. Possible values: "first_name", "second_name", "patronymic", "tax_reference", "phone"
error-objectError
Response example for npd/request/status
{
  "status": "ok",
  "success": false,
  "violations": [
    "first_name",
    "second_name",
    "phone"
  ]
}

Escrow account​

session/init/payout/nominal​

Creating a session with a simultaneous payout to a bank account​

You can use this request to send payouts from an escrow account to a bank account.

Endpoint​

api/v1/session/init/payout/nominal

Request parameters​

NameMandatoryTypeDescription
payment_method+objectPayment details
amount_details-objectAmount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000
participant_details+objectInformation about the participants (the sender and the recipient)
fiscalization_details-objectFiscalization details; only for payouts to the self-employed
metadata-*Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks
Request examples
curl -X POST \
https:// api/v1/session/init/payout/nominal \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-SIGN: signature' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-d '{
  "payment_method": {
    "type": "bank_account",
    "bank_account": {
      "ru": {
        "bik": "044525974",
        "account": "40817810400003869535",
        "full_name": "Ivanov Ivan Ivanovich",
        "description": "Funds transfer according to contract No. 5015553111 Ivanov Ivan Ivanovich VAT exempt"
      },
      "system_type": "ru"
    }
  },
  "amount_details": {
    "amount": 300,
    "currency": "rub"
  },
  "participant_details": {
    "sender": {
      "account": "40702810300200000013"
    },
    "recipient": {
      "beneficiary_id": "1234567890"
    }
  }
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Valid values: error, ok
session-objectPayment session
error-objectError
Response examples
{
  "status": "ok",
  "session": {
    "id": "ps_287403",
    "status": "in_progress",
    "created_at": "2023-05-10T16:58:43.586072Z",
    "updated_at": "2023-05-10T16:58:43.705620Z",
    "payments": [
      {
        "id": "po_72265",
        "status": "in_progress",
        "created_at": "2023-05-10T16:58:43.781934Z",
        "payment_method": {
          "type": "bank_account",
          "bank_account": {
            "system_type": "ru",
            "ru": {
              "bik": "049205131",
              "account": "40702810900000000001",
              "full_name": "Company name",
              "description": "Funds transfer according to contract No. 1 of 01.09.2021 VAT exempt",
              "is_fast": false,
              "kpp": "156605001",
              "inn": "3111104710"
            }
          }
        },
        "amount_details": {
          "amount": 200,
          "currency": "rub"
        },
        "paymentMetadata": {},
        "participant_details": {
          "sender": {
            "account": "40702810300200000013"
          },
          "recipient": {
            "beneficiary_id": "1234567890"
          }
        }
      }
    ]
  }
}

session/multi/create/nominal​

Creating a payment session​

Creates a payment session on Bank 131's side.

Payment operations can only be performed within a session. One or more operations can be performed within the session.

Use this request if you need to request the data necessary to perform a payout or a payment from the user. For example, call the tokenization widget, show it to the user and get tokenized card details, and then send the payout request with those details.

If you are ready to provide all the data needed to perform the operation in the request, you can use the session/multi/init/payment/nominal method whereby the payout starts immediately once the session has been created. In this case, you do not need to start the operation with a separate request.

The response contains the parameters of the created session.

Endpoint​

/api/v1/session/multi/create/nominal

Request parameters​

NameMandatoryTypeDescription
payment_details+objectTransfer details
payment_method+objectPayment details (card, customer account, etc.)
fiscalization_details-objectFiscalization details; only for payouts to the self-employed
participant_details- (mandatory for the payouts to card)objectInformation about the participants (the sender and the recipient)
amount_details-objectAmount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000
customer+objectRecipient's data in your system
metadata-*Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks
Request example
curl -X POST \
https://demo.bank131.ru/api/v1/session/multi/create/nominal  \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_details": {
    "type": "internal_transfer",
    "internal_transfer": {
      "type": "transfer_from_nominal_account",
      "transfer_from_nominal_account": {
        "description": "test payout"
      }
    }
  },
  "payment_method": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "4242424242424242"
      }
    }
  },
  "participant_details": {
    "recipient": {
      "full_name": "Ivan Ivanovich Ivanov",
      "beneficiary_id": "123412341234"
    },
    "sender": {
      "full_name": "Ivan Ivanovich Ivanov",
      "beneficiary_id": "123412341234"
    }
  },
  "amount_details": {
    "amount": 1011,
    "currency": "RUB"
  },
  "customer": {
    "reference": "test"
  }
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-objectPayment session
error-objectError
Response examples
{
  "status": "ok",
  "session": {
    "id": "ps_72974",
    "status": "in_progress",
    "created_at": "2021-08-06T11:34:51.274416Z",
    "updated_at": "2021-08-06T11:34:51.466550Z",
    "payments": [
      {
        "id": "po_25657",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.545329Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_method": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "0002"
          }
        },
        "amount_details": {
          "amount": 1011,
          "currency": "RUB"
        },
        "metadata": {
          "key": "value"
        },
        "participant_details": {
          "sender": {
            "full_name": "Ivan Ivanovich Ivanov"
          },
          "recipient": {
            "full_name": "Ivan Ivanovich Ivanov",
            "reference": "1234"
          }
        }
      }
    ],
    "acquiring_payments": [
      {
        "id": "pm_15174",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.545232Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_details": {
          "type": "internal_transfer",
          "internal_transfer": {
            "type": "transfer_from_nominal_account",
            "transfer_from_nominal_account": {
              "description": "test payout",
              "card_mask": "400000******0002"
            }
          }
        },
        "amount_details": {
          "amount": 1011,
          "currency": "RUB"
        },
        "metadata": {
          "key": "value"
        },
        "participant_details": {
          "sender": {
            "full_name": "Ivan Ivanovich Ivanov"
          },
          "recipient": {
            "full_name": "Ivan Ivanovich Ivanov",
            "reference": "1234"
          }
        }
      }
    ]
  }
}

session/multi/init/payment/nominal​

Creating a session with a simultaneous payout​

This request can be used if you are ready to pass all the parameters needed for the payout at once, for example when transferring a payout to a Russian bank account.

The response contains the parameters of the session created and an object with information about the payment (acquiring_payment/payment_list).

Endpoint​

/api/v1/session/multi/init/payment/nominal

Request parameters​

NameMandatoryTypeDescription
payment_details+objectTransfer details
payment_method+objectPayment details (card, customer account, etc.)
fiscalization_details-objectFiscalization details; only for payouts to the self-employed
participant_details- (mandatory for the payouts to card)objectInformation about the participants (the sender and the recipient)
amount_details-objectAmount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000
customer+objectRecipient's data in your system
metadata-*Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks
Request example
curl -X POST \
https://demo.bank131.ru/api/v1/session/multi/init/payment/nominal \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_details": {
    "type": "internal_transfer",
    "internal_transfer": {
      "type": "transfer_from_nominal_account",
      "transfer_from_nominal_account": {
        "description": "test payout"
      }
    }
  },
  "payment_method": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "4242424242424242"
      }
    }
  },
  "participant_details": {
    "recipient": {
      "full_name": "Ivan Ivanovich Ivanov",
      "beneficiary_id": "123412341234"
    },
    "sender": {
      "full_name": "Ivan Ivanovich Ivanov",
      "beneficiary_id": "123412341234"
    }
  },
  "amount_details": {
    "amount": 1011,
    "currency": "RUB"
  },
  "customer": {
    "reference": "test"
  }
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Valid values: error, ok
session-objectPayment session
error-objectError
Response examples
{
  "status": "ok",
  "session": {
    "id": "ps_72974",
    "status": "in_progress",
    "created_at": "2021-08-06T11:34:51.274416Z",
    "updated_at": "2021-08-06T11:34:51.466550Z",
    "payments": [
      {
        "id": "po_25657",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.545329Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_method": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "0002"
          }
        },
        "amount_details": {
          "amount": 1011,
          "currency": "RUB"
        },
        "metadata": {
          "key": "value"
        },
        "participant_details": {
          "sender": {
            "full_name": "Ivan Ivanovich Ivanov"
          },
          "recipient": {
            "full_name": "Ivan Ivanovich Ivanov",
            "reference": "1234"
          }
        }
      }
    ],
    "acquiring_payments": [
      {
        "id": "pm_15174",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.545232Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_details": {
          "type": "internal_transfer",
          "internal_transfer": {
            "type": "transfer_from_nominal_account",
            "transfer_from_nominal_account": {
              "description": "test payout",
              "card_mask": "400000******0002"
            }
          }
        },
        "amount_details": {
          "amount": 1011,
          "currency": "RUB"
        },
        "metadata": {
          "key": "value"
        },
        "participant_details": {
          "sender": {
            "full_name": "Ivan Ivanovich Ivanov"
          },
          "recipient": {
            "full_name": "Ivan Ivanovich Ivanov",
            "reference": "1234"
          }
        }
      }
    ]
  }
}

session/multi/start/payment/nominal​

Starting a payout​

This request can be used to start a payout within an existing session. In the parameters, you can pass the data necessary to perform the payout. Or you can change pieces of data that have already been passed.

If you are using the widget for getting the user's tokenized bank card details, you can pass them using this request.

Endpoint​

/api/v1/session/multi/start/payment/nominal

Request parameters​

NameMandatoryTypeDescription
session_id+stringPayment session identifier
payment_details-objectTransfer details
payment_method-objectPayment details (card, customer account, etc.)
fiscalization_details-objectFiscalization details; only for payouts to the self-employed
participant_details- (mandatory for the payouts to card)objectInformation about the participants (the sender and the recipient)
amount_details-objectAmount. Transmitted in the ruble decimal format. To send 100 rubles, specify 10000
customer-objectRecipient's data in your system
metadata-*Additional information. Any data you need in order to perform the operation. Returned in responses and webhooks
Request example
curl -X POST \
https://demo.bank131.ru/api/v1/session/multi/start/payment/nominal  \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_12345",
  "payment_details": {
    "type": "internal_transfer",
    "internal_transfer": {
      "type": "transfer_from_nominal_account",
      "transfer_from_nominal_account": {
        "description": "test payout"
      }
    }
  },
  "payment_method": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "4242424242424242"
      }
    }
  },
  "participant_details": {
    "recipient": {
      "full_name": "Ivan Ivanovich Ivanov"
    },
    "sender": {
      "full_name": "Ivan Ivanovich Ivanov"
    }
  },
  "amount_details": {
    "amount": 1011,
    "currency": "RUB"
  },
  "customer": {
    "reference": "test"
  }
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-objectPayment session
error-objectError
Response examples
{
  "status": "ok",
  "session": {
    "id": "ps_72974",
    "status": "in_progress",
    "created_at": "2021-08-06T11:34:51.274416Z",
    "updated_at": "2021-08-06T11:34:51.466550Z",
    "payments": [
      {
        "id": "po_25657",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.545329Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_method": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "0002"
          }
        },
        "amount_details": {
          "amount": 1011,
          "currency": "RUB"
        },
        "metadata": {
          "key": "value"
        },
        "participant_details": {
          "sender": {
            "full_name": "Ivan Ivanovich Ivanov"
          },
          "recipient": {
            "full_name": "Ivan Ivanovich Ivanov",
            "reference": "1234"
          }
        }
      }
    ],
    "acquiring_payments": [
      {
        "id": "pm_15174",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.545232Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_details": {
          "type": "internal_transfer",
          "internal_transfer": {
            "type": "transfer_from_nominal_account",
            "transfer_from_nominal_account": {
              "description": "test payout",
              "card_mask": "400000******0002"
            }
          }
        },
        "amount_details": {
          "amount": 1011,
          "currency": "RUB"
        },
        "metadata": {
          "key": "value"
        },
        "participant_details": {
          "sender": {
            "full_name": "Ivan Ivanovich Ivanov"
          },
          "recipient": {
            "full_name": "Ivan Ivanovich Ivanov",
            "reference": "1234"
          }
        }
      }
    ]
  }
}

Settlement account​

session/init/payout/rko​

The method creates a session with starting a payout from a settlement account to a bank account at once.

Endpoint​

/api/v1/session/init/payout/rko

Request parameters​

NameMandatoryTypeDescription
payment_method+objectPayment details (bank account)
amount_details+objectAmount in kopecks. To send 100 rubles, specify 10000
participant_details+objectSender's details
metadata-*Any additional details required for the transaction. The details return within responds and webhooks.
Request example
curl -X POST \
https://demo.bank131.ru/api/v1/session/init/payout/rko  \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_method": {
    "type": "bank_account",
    "bank_account": {
      "system_type": "ru",
      "ru": {
        "bik": "049205131",
        "account": "40702810300000000006",
        "full_name": "Acme",
        "inn": "1234567890",
        "kpp": "165801002",
        "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt"
      }
    }
  },
  "amount_details": {
    "amount": 212,
    "currency": "rub"
  },
  "participant_details": {
    "sender": {
      "account": "40702810900000000011"
    }
  }
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-objectSession details
error-objectError
Response example
{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2018-05-27T02:03:00.000000Z",
    "updated_at": "2018-05-27T02:03:00.000000Z",
    "payments": [
      {
        "id": "po_2018",
        "status": "in_progress",
        "created_at": "2018-05-27T02:03:00.000000Z",
        "customer": {
          "reference": "user123",
          "contacts": [
            {
              "email": "user@gmail.com"
            }
          ]
        },
        "payment_method": {
          "type": "bank_account",
          "bank_account": {
            "system_type": "ru",
            "ru": {
              "bik": "049205131",
              "account": "40702810300000000006",
              "full_name": "Acme ",
              "inn": "1234567890",
              "kpp": "165801002",
              "description": "Description of payment"
            }
          }
        },
        "amount_details": {
          "amount": 10000,
          "currency": "rub"
        },
        "metadata": "good"
      }
    ]
  }
}

session/multi/create/rko​

Creates a payment session on Bank 131's side.

Payment operations can only be performed within a session. One or more operations can be performed within the session.

Use this request if you need to request the data necessary to perform a payout or a payment from the user. For example, call the tokenization widget, show it to the user and get tokenized card details, and then send the payout request with those details.

If you are ready to provide all the data needed to perform the operation in the request, you can use the (/api/v1/session/multi/init/payment/rko) method whereby the payout starts immediately once the session has been created. In this case, you do not need to start the operation with a separate request.

The response contains the parameters of the created session.

Endpoint​

/api/v1/session/multi/create/rko

NameMandatoryTypeDescription
payment_details+objectTransaction details
payment_method+objectPayment details (bank card, bank account, etc.)
fiscalization_details-objectFiscalization details. Mandatory for payouts to the self-employed.
participant_details- (mandatory for payouts to bank cards)objectTransaction participants details (sender and recipient)
amount_details-objectAmount in kopecks. To send 100 rubles, specify 10000
customer-objectRecipient's details in your system
metadata-*Any additional details required for the transaction. The details return within responds and webhooks
Request example
curl -X POST \
https://demo.bank131.ru//api/v1/session/multi/create/rko   \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_details": {
    "type": "internal_transfer",
    "internal_transfer": {
      "type": "transfer_from_bank_account",
      "transfer_from_bank_account": {
        "description": "Wire for agreement № 5015553111 Ivanov Ivan Ivanovich VAT exempt"
      }
    }
  },
  "payment_method": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "****************"
      }
    }
  },
  "participant_details": {
    "sender": {
      "full_name": "Ivan Ivanovich Ivanov"
    },
    "recipient": {
      "full_name": "Ivan Ivanovich Ivanov"
    }
  },
  "amount_details": {
    "amount": 293400,
    "currency": "RUB"
  },
  "customer": {
    "reference": "123456789012"
  }
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-objectPayment session details
error-objectError
Response examples
{
  "status": "ok",
  "session": {
    "id": "ps_72974",
    "status": "in_progress",
    "created_at": "2021-08-06T11:34:51.274416Z",
    "updated_at": "2021-08-06T11:34:51.466550Z",
    "payments": [
      {
        "id": "po_25657",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.545329Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_method": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "0002"
          }
        },
        "amount_details": {
          "amount": 1011,
          "currency": "RUB"
        },
        "metadata": {
          "key": "value"
        },
        "participant_details": {
          "sender": {
            "full_name": "Ivan Ivanovich Ivanov"
          },
          "recipient": {
            "full_name": "Ivan Ivanovich Ivanov",
            "reference": "1234"
          }
        }
      }
    ],
    "acquiring_payments": [
      {
        "id": "pm_15174",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.545232Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_details": {
          "type": "internal_transfer",
          "internal_transfer": {
            "type": "transfer_from_bank_account",
            "transfer_from_bank_account": {
              "description": "test payout",
              "card_mask": "400000******0002"
            }
          }
        },
        "amount_details": {
          "amount": 1011,
          "currency": "RUB"
        },
        "metadata": {
          "key": "value"
        },
        "participant_details": {
          "sender": {
            "full_name": "Ivan Ivanovich Ivanov"
          },
          "recipient": {
            "full_name": "Ivan Ivanovich Ivanov",
            "reference": "1234"
          }
        }
      }
    ]
  }
}

session/multi/start/payment/rko​

Payout start​

This request can be used to start a payout within an existing session. In the parameters, you can pass the data necessary to perform the payout. Either, you can change pieces of data that have already been passed.

If you are using the payout widget to get the user's tokenized bank card details, you can pass them using this request.

Endpoint​

/api/v1/session/multi/start/payment/rko

Request parameters​

NameMandatoryTypeDescription
session_id+stringPayment session id
payment_details-objectTransaction details
payment_method-objectPayment details (bank card, bank account, etc.)
customer-objectRecipient's details in your system
amount_details-objectAmount in kopecks. To send 100 rubles, specify 10000
fiscalization_details-objectFiscalization details. Mandatory for payouts to the self-employed.
participant_details- (mandatory when making a payout to a bank card)objectTransaction participants details (sender and recipient)
Request example
curl -X POST \
https://demo.bank131.ru/api/v1/session/multi/start/payment/rko   \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_12345",
  "payment_details": {
    "type": "internal_transfer",
    "internal_transfer": {
      "type": "transfer_from_bank_account",
      "transfer_from_bank_account": {
        "description": "test payout"
      }
    }
  },
  "payment_method": {
    "type": "card",
    "card": {
      "type": "bank_card",
      "bank_card": {
        "number": "4242424242424242"
      }
    }
  },
  "participant_details": {
    "recipient": {
      "full_name": "Ivan Ivanovich Ivanov"
    },
    "sender": {
      "full_name": "Ivan Ivanovich Ivanov"
    }
  },
  "amount_details": {
    "amount": 1011,
    "currency": "RUB"
  },
  "customer": {
    "reference": "test"
  }
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-objectPayment session details
error-objectError
Response examples
{
  "status": "ok",
  "session": {
    "id": "ps_72974",
    "status": "in_progress",
    "created_at": "2021-08-06T11:34:51.274416Z",
    "updated_at": "2021-08-06T11:34:51.466550Z",
    "payments": [
      {
        "id": "po_25657",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.545329Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_method": {
          "type": "card",
          "card": {
            "brand": "visa",
            "last4": "0002"
          }
        },
        "amount_details": {
          "amount": 1011,
          "currency": "RUB"
        },
        "metadata": {
          "key": "value"
        },
        "participant_details": {
          "sender": {
            "full_name": "Ivan Ivanovich Ivanov"
          },
          "recipient": {
            "full_name": "Ivan Ivanovich Ivanov",
            "reference": "1234"
          }
        }
      }
    ],
    "acquiring_payments": [
      {
        "id": "pm_15174",
        "status": "in_progress",
        "created_at": "2021-08-06T11:34:51.545232Z",
        "customer": {
          "reference": "lucky"
        },
        "payment_details": {
          "type": "internal_transfer",
          "internal_transfer": {
            "type": "transfer_from_bank_account",
            "transfer_from_bank_account": {
              "description": "test payout",
              "card_mask": "400000******0002"
            }
          }
        },
        "amount_details": {
          "amount": 1011,
          "currency": "RUB"
        },
        "metadata": {
          "key": "value"
        },
        "participant_details": {
          "sender": {
            "full_name": "Ivan Ivanovich Ivanov"
          },
          "recipient": {
            "full_name": "Ivan Ivanovich Ivanov",
            "reference": "1234"
          }
        }
      }
    ]
  }
}

Money transfers​

bpa/session/init/payment​

This method is used to initiate the transfer.

Endpoint​

/api/v1/bpa/session/init/payment

Request parameters​

NameMandatoryTypeDescription
payment_details+objectTransfer details
amount_details-objectPayment details
participant_details-objectInformation about the participants
cash_details+objectAdditional information on the cash payment
Request example
curl -X POST \
https://demo.bank131.ru/api/v1/bpa/session/init/payment   \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_details": {
    "type": "moneysend",
    "moneysend": {}
  },
  "amount_details": {
    "amount": 1000,
    "currency": "rub"
  },
  "participant_details": {
    "sender": {
      "citizenship_country_iso3": "AUS",
      "first_name": "Ivan",
      "last_name": "Ivanov",
      "middle_name": "Ivanovich",
      "country_iso3": "RUS",
      "state": "New York",
      "city": "Kazan",
      "postal_code": "420000",
      "street": "Nekrasova",
      "building": "1",
      "flat": "131",
      "tax_reference": "123456789012",
      "date_of_birth": "2010-01-01",
      "contacts": {
        "phone": {
          "full_number": "+79371234567",
          "country_iso3": "RUS",
          "operator_code": "937",
          "short_number": "1234567"
        },
        "email": "test@test.com"
      },
      "identity_document": {
        "id_type": "Паспорт гражданина Российской Федерации",
        "id_number": "123456789",
        "issue_date": "2020-01-01",
        "id_expiration_date": "2030-01-01",
        "division_code": "165-065",
        "issued_by": "OVD Kazani"
      },
      "documents_foreigner": {
        "id_type": "Виза",
        "issued_by": "OVD Kazani",
        "issue_date": "2020-01-01",
        "id_expiration_date": "2030-01-01"
      },
      "service_point": {
        "id": "1",
        "name": "point_on_lenina",
        "country_iso3": "RUS",
        "state": "Moscow",
        "city": "Moscow",
        "oktmo": "36634436111",
        "street": "Lenin avenue",
        "house": "1",
        "terminal_id": "123124"
      },
      "source_of_money": "salary",
      "description": "salary transfers"
    },
    "recipient": {
      "first_name": "Ivan",
      "last_name": "Sidorov",
      "middle_name": "Ivanovich",
      "date_of_birth": "2010-01-01",
      "currency": "TRY",
      "contacts": {
        "phone": {
          "full_number": "+79377654321",
          "country_iso3": "RUS",
          "operator_code": "937",
          "short_number": "7654321"
        },
        "email": "test@test.com"
      }
    }
  },
  "cash_details": {
    "shift": "11"
  }
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-objectPayment session details
error-objectError
Response examples
{
  "status": "ok",
  "session": {
    "id": "ps_592245",
    "status": "in_progress",
    "created_at": "2022-11-15T15:38:50.255803Z",
    "updated_at": "2022-11-15T15:38:50.336303Z",
    "acquiring_payments": [
      {
        "id": "pm_296251",
        "status": "in_progress",
        "created_at": "2022-11-15T15:38:50.357833Z",
        "payment_details": {
          "type": "moneysend",
          "moneysend": {}
        },
        "amount_details": {
          "amount": 978,
          "currency": "rub"
        },
        "participant_details": {
          "sender": {
            "citizenship_country_iso3": "AUS",
            "first_name": "Ivan",
            "last_name": "Ivanov",
            "middle_name": "Ivanovich",
            "country_iso3": "RUS",
            "state": "New York",
            "city": "Kazan",
            "postal_code": "420000",
            "street": "Nerkasova",
            "building": "1",
            "flat": "131",
            "tax_reference": "123456789012",
            "date_of_birth": "2010-01-01",
            "contacts": {
              "phone": {
                "full_number": "+79371234567",
                "country_iso3": "RUS",
                "operator_code": "937",
                "short_number": "1234567"
              },
              "email": "test@test.com"
            },
            "identity_document": {
              "id_type": "Паспорт гражданина Российской Федерации",
              "id_number": "123456789",
              "issue_date": "2020-01-01",
              "id_expiration_date": "2030-01-01",
              "division_code": "165-065",
              "issued_by": "OVD Kazani"
            },
            "documents_foreigner": {
              "id_type": "Виза",
              "issued_by": "OVD Kazani",
              "issue_date": "2020-01-01",
              "id_expiration_date": "2030-01-01"
            },
            "service_point": {
              "id": "1",
              "name": "point_on_lenina",
              "country_iso3": "RUS",
              "state": "Moscow",
              "city": "Moscow",
              "oktmo": "36634436111",
              "street": "Lenin avenue",
              "house": "1",
              "terminal_id": "123124"
            },
            "source_of_money": "salary",
            "description": "salary transfers"
          },
          "recipient": {
            "first_name": "Ivan",
            "last_name": "Sidorov",
            "middle_name": "Ivanovich",
            "date_of_birth": "2010-01-01",
            "currency": "TRY",
            "contacts": {
              "phone": {
                "full_number": "+79376151530",
                "country_iso3": "RUS",
                "operator_code": "937",
                "short_number": "7654321"
              },
              "email": "test@test.com"
            }
          }
        }
      }
    ]
  }
}

cash/payout/session/init​

This method is used to initiate the payout of funds to the recipient or refund of the transfer to the sender. The set of parameters is the same in both cases. To refund the transfer to the sender, pass the same details for the sender (participant_details.sender) and the recipient (participant_details.recipient) of the transfer in the request.

Note that the received transfer code must be wrapped in BASE64 and put in the tcn_code_encoded parameter.

Endpoint​

/api/v1/cash/payout/session/init

Request parameters​

NameMandatoryTypeDescription
tcn_code_encoded+stringTransaction code received from the recipient and wrapped in BASE64. Example: “MzU4MDctMjM1ODk=”
payment_method+objectPayment details. Pass the moneysend value.
amount_details-objectPayment details
participant_details-objectInformation about the participants
cash_details+objectAdditional information on the cash payment
Request example
curl -X POST \
https://demo.bank131.ru/api/v1/cash/payout/session/init   \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "tcn_code_encoded": "NTkyMjM3LTg5MjEzNDk5",
  "payment_method": {
    "type": "moneysend",
    "moneysend": {}
  },
  "cash_details": {
    "shift": "159"
  },
  "amount_details": {
    "amount": 1000,
    "currency": "rub"
  },
  "participant_details": {
    "recipient": {
      "citizenship_country_iso3": "AUS",
      "first_name": "Ivan",
      "last_name": "Sidorov",
      "middle_name": "Ivanovich",
      "country_iso3": "RUS",
      "state": "New York",
      "city": "Kazan",
      "postal_code": "420000",
      "street": "Nerkasova",
      "building": "1",
      "flat": "131",
      "tax_reference": "123456789012",
      "date_of_birth": "2008-01-01",
      "identity_document": {
        "id_type": "Паспорт гражданина Российской Федерации",
        "id_number": "123456789",
        "issue_date": "2020-01-01",
        "id_expiration_date": "2030-01-01",
        "division_code": "165-065",
        "issued_by": "OVD Kazani"
      },
      "documents_foreigner": {
        "id_type": "Виза",
        "issued_by": "OVD Kazani",
        "issue_date": "2020-01-01",
        "id_expiration_date": "2030-01-01"
      },
      "service_point": {
        "id": "1",
        "name": "point_on_lenina",
        "country_iso3": "RUS",
        "state": "Moscow",
        "city": "Moscow",
        "oktmo": "36634436111",
        "street": "Lenin avenue",
        "house": "1",
        "terminal_id": "123124"
      },
      "source_of_money": "salary",
      "description": "salary transfers",
      "contacts": {
        "phone": {
          "full_number": "+79377654321",
          "country_iso3": "RUS",
          "operator_code": "937",
          "short_number": "7654321"
        },
        "email": "test@test.com"
      }
    },
    "sender": {
      "first_name": "Ivan",
      "last_name": "Ivanov",
      "middle_name": "Ivanovich",
      "contacts": {
        "phone": {
          "full_number": "+79371234567",
          "country_iso3": "RUS",
          "operator_code": "937",
          "short_number": "1234567"
        },
        "email": "test@test.com"
      }
    }
  }
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-objectPayment session details
error-objectError
Response examples
{
  "status": "ok",
  "session": {
    "id": "ps_3230",
    "status": "in_progress",
    "created_at": "2022-11-01T02:03:00.000000Z",
    "updated_at": "2022-11-01T02:03:00.000000Z",
    "payments": [
      {
        "id": "po_2018",
        "status": "in_progress",
        "created_at": "2022-11-01T02:03:00.000000Z",
        "payment_method": {
          "type": "moneysend"
        },
        "participant_details": {
          "recipient": {
            "citizenship_country_iso3": "AUS",
            "first_name": "Ivan",
            "last_name": "Sidorov",
            "middle_name": "Ivanovich",
            "country_iso3": "RUS",
            "state": "New York",
            "city": "Kazan",
            "postal_code": "420000",
            "street": "Nekrasova",
            "building": "1",
            "flat": "131",
            "tax_reference": "123456789012",
            "date_of_birth": "2010-01-01",
            "contacts": {
              "phone": {
                "full_number": "+79377654321",
                "country_iso3": "RUS",
                "operator_code": "937",
                "short_number": "7654321"
              },
              "email": "test@test.com"
            },
            "identity_document": {
              "id_type": "Паспорт гражданина Российской Федерации",
              "id_number": "123456789",
              "issue_date": "2020-01-01",
              "id_expiration_date": "2030-01-01",
              "division_code": "165-065",
              "issued_by": "OVD Kazani"
            },
            "documents_foreigner": {
              "id_type": "Виза",
              "issued_by": "OVD Kazani",
              "issue_date": "2020-01-01",
              "id_expiration_date": "2030-01-01"
            },
            "service_point": {
              "id": "1",
              "name": "point_on_lenina",
              "country_iso3": "RUS",
              "state": "Moscow",
              "city": "Moscow",
              "oktmo": "36634436111",
              "street": "Lenin avenue",
              "house": "1",
              "terminal_id": "123124"
            },
            "source_of_money": "salary",
            "description": "salary transfers",
            "customer_verification": {
              "first_name": "Ivan",
              "last_name": "Ivanov",
              "middle_name": "Ivanovich",
              "date_of_birth": "2010-01-01",
              "contacts": {
                "phone": {
                  "full_number": "+79371234567",
                  "country_iso3": "RUS",
                  "operator_code": "937",
                  "short_number": "1234567"
                },
                "email": "test@test.com"
              }
            }
          },
          "sender": {
            "first_name": "Ivan",
            "last_name": "Ivanov",
            "middle_name": "Ivanovich",
            "contacts": {
              "phone": {
                "full_number": "+79371234567",
                "country_iso3": "RUS",
                "operator_code": "937",
                "short_number": "1234567"
              },
              "email": "test@test.com"
            }
          }
        }
      }
    ]
  }
}

bpa/calculate​

This method is used to calculate currency exchange rates for money transfers.

A currency exchange can only be made from rub to another currency or from another currency to rub, so it is required to pass the currency = rub value either in source or in destination in the amounts object.

There are two ways to calculate the currency exchange rate for a money transfer:

  • Direct rate: specify the amount to be sent in rubles and calculate the amount to be received in the target currency.
  • Indirect rate: specify the amount to be received in the target currency and calculate the amount to be sent in rubles.

Endpoint​

/api/v1/bpa/calculate

Request parameters​

NameMandatoryTypeDescription
amounts+objectExchange amount and currency
  source+objectAmount and currency to write off of the sender
    amount+numberAmount in decimal format (kopecks) to calculate the direct exchange rate, or the null value to calculate the indirect exchange rate
    currency+stringISO 4217 currency code. Case insensitive. Options: rub, try, uzs
  destination+objectAmount and currency to be paid to the recipient
    amount+numberAmount in decimal format (kopecks) to calculate the indirect exchange rate, or the null value to calculate the direct exchange rate
    currency+stringISO 4217 currency code. Case insensitive. Options: rub, try, uzs
Request examples
curl -X POST \
https://demo.bank131.ru/api/v1/bpa/calculate   \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "amounts": {
    "source": {
      "amount": 357912,
      "currency": "RUB"
    },
    "destination": {
      "amount": null,
      "currency": "TRY"
    }
  }
}

Response parameters​

NameMandatoryTypeDescription
amounts+objectConversion rate calculation
  source+objectAmount and currency to write off of the sender
    amount+numberAmount calculated in the sender's currency (rubles)
    currency+stringISO 4217 currency code. Case insensitive. Options: rub
  destination+objectAmount and currency to be paid to the recipient
    amount+numberCalculated amount to be received
    currency+stringISO 4217 currency code. Case insensitive. Options: try, uzs
  transfer_fee+objectSender's fee for money transfer
    amount+numberFee amount to be paid by the sender for the money transfer
    currency+stringISO 4217 currency code. Case insensitive. Options: rub
  sms_fee+objectSender's fee for SMS notification to the recipient
    amount+numberFee amount to be paid for SMS notification to the recipient
    currency+stringISO 4217 currency code. Case insensitive. Options: rub
  payment+objectTotal amount to write off of the sender
    amount+numberTotal amount to be written off the sender including all fees. Calculated as source + transfer_fee + sms_fee
    currency+stringISO 4217 currency code. Case insensitive. Options: rub
exchanges+objectExchange rate data
  source+objectAmount and currency to write off of the sender passed in the request
    amount+numberAmount in decimal format (kopecks) to calculate the direct exchange rate, or the null value to calculate the indirect exchange rate
    currency+stringISO 4217 currency code. Case insensitive. Options: rub, try, uzs
  destination+objectAmount and currency to be paid to the recipient passed in the request
    amount+numberAmount in decimal format (kopecks) to calculate the indirect exchange rate, or the null value to calculate the direct exchange rate
    currency+stringISO 4217 currency code. Case insensitive. Options: rub, try, uzs
  rate+objectExchange rate
    fx_rate+numberRatio of the currency to ruble (of the target currency to the write-off currency)
    quantity+numberQuantity of currency units. Some currencies are calculated in tens, hundreds or thousands of units, the current rates are available on the Bank of Russia website
error-objectError
Response examples
{
  "amounts": {
    "source": {
      "amount": 357913,
      "currency": "RUB"
    },
    "destination": {
      "amount": 131426,
      "currency": "TRY"
    },
    "transfer_fee": {
      "amount": 0,
      "currency": "RUB"
    },
    "sms_fee": {
      "amount": 0,
      "currency": "RUB"
    },
    "payment": {
      "amount": 5400,
      "currency": "RUB"
    }
  },
  "exchanges": {
    "source": {
      "amount": 357912,
      "currency": "RUB"
    },
    "destination": {
      "amount": null,
      "currency": "TRY"
    },
    "rate": {
      "fx_rate": 2.7233,
      "quantity": 1
    }
  }
}

bpa/session/multi/init/payment​

This method is designed to initiate a cross-border transfer.

The transfer can be made from card to card, via IBAN number, or for cash pickup through a banking payment agent.

Endpoint​

/api/v2/bpa/session/multi/init/payment

Request parameters​

NameMandatoryTypeDescription
payment_options-objectParameters for making a payment
  return_url-stringURL to redirect the user after payment completion. The URL must be valid
  recurrent-boolWhether to make the payment using a saved token
payment_details_multi+arrayPayment method
  type+stringType of payment method. Possible values: card
  card+objectBank card details
    type+stringMethod of card information transmission. Value: tokenized_card
    tokenized_card+objectTokenized card number
      token+stringToken
    recurrent-objectData for repeating the transfer with a previously saved token
      token-stringToken
      initiator-stringType of recurring payment: client—a CIT payment
payout_details_multi+arrayTransfer receipt method
  type+stringTransfer receipt type. Options:
- card – for receiving to a bank card or cash withdrawal,
- bank_account – for receiving by IBAN,
- moneysend – for cash receipt
  card- (mandatory for type = card)objectBank card data
    type-stringMethod of card information transmission. Value: tokenized_card
    tokenized_card-objectTokenized card number
      token-stringToken
    recurrent-objectData for repeating the transfer with a previously saved token
      token-stringToken
      initiator-stringType of recurring payment: client — CIT payment
    bank_account- (mandatory for type = bank_account)objectRecipient's bank account
      iban- (mandatory for the payouts by IBAN)objectRecipient's IBAN
        account+stringRecipient's IBAN number
    moneysend- (mandatory for type = moneysend)objectPass the object for cash transfers, always empty: {}
    system_type- (mandatory for the payouts by IBAN)stringPossible values: iban
    country+stringPayout destination country according to ISO 3166-1 alpha-3
participant_details+objectInformation on the sender and the recipient
  sender+objectSender details
    citizenship_country_iso3+stringSender's country of citizenship according to ISO 3166-1 alpha-3
    first_name+stringFirst name
    last_name+stringLast name
    middle_name-stringPatronymic name
    address+objectSender's address
      structured_address+objectSender's structured address
        country_iso3+stringCountry (ISO 3166-1 alpha-3)
        postal_code-stringPostal code of the sender's place of registration
        state-stringState or region of the sender's place of registration
        city+stringLocality of the sender's place of registration
        street-stringStreet of the sender's place of registration
        building+stringBuilding number of the sender's place of registration
        flat-stringApartment of the sender's place of registration
    tax_reference-stringSender's INN (12 digits)
    date_of_birth+stringSender's date of birth in the YYYY-MM-DD format. Make sure the sender is 18 years old or older
    contacts-objectSender's contacts
      email-stringSender's email
      phone-objectSender's phone number details
        full_number+stringSender's full phone number in the +<country code><number> format
        country_iso3+stringSender's phone number country code (ISO 3166-1 alpha-3)
        operator_code+stringOperator's code of the phone number
        short_number+stringPhone number without the operator's code
    identity_document- (обязателен, если не передается documents_foreigner)objectSender's identity document
      id_type+stringType of the sender's identity document. Possible values: Passport of a citizen of the Russian Federation
      id_number+stringSender's identity document series and number (without spaces)
      issue_date+stringSender's identity document issue date in the YYYY-MM-DD format
      division_code-stringCode of the division that issued the sender's identity document. Required if available in the document
      issued_by-stringName of the division that issued the sender's identity document. Required if available in the document
    documents_foreigner-objectNon-resident sender's identity document details. Required for non-residents only
      id_number+stringSender's identity document series and number (without spaces)
      issue_date+stringSender's identity document issue date in the YYYY-MM-DD format
      id_expiration_date-stringSender's identity document expiration date in the YYYY-MM-DD format
  recipient+objectRecipient details
    first_name- (mandatory for the transfers in cash or by IBAN)stringFirst name
    last_name- (mandatory for the transfers in cash or by IBAN)stringLast name
    middle_name-stringPatronymic name
    citizenship_country_iso3+stringRecipient's country of citizenship according to ISO 3166-1 alpha-3
    date_of_birth-stringRecipient's date of birth in the YYYY-MM-DD format. Make sure the recipient is 18 years old or older
    contacts-objectRecipient's contacts
      email-stringRecipient's email
      phone-objectRecipient's phone number details
        full_number+stringRecipient's full phone number in the +<country code><number> format
source_of_money-objectSource of the sender's funds
  source+stringSource of the sender's funds
  description-stringAdditional information
calculate+objectConversion information
  amounts+objectExchange amount and currency
    source+objectAmount and currency to write off of the sender
      amount+numberAmount in decimal format (kopecks) to calculate the exchange rate
      currency+stringISO 4217 currency code. Case insensitive
    destination+objectAmount and currency to be paid to the recipient
      amount+numberAmount in decimal format (kopecks) to calculate the exchange rate
      currency+stringISO 4217 currency code. Case insensitive
Request examples
curl -X POST \
https://demo.bank131.ru/api/v2/bpa/session/multi/init/payment   \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_details_multi": [
    {
      "type": "card",
      "card": {
        "type": "tokenized_card",
        "tokenized_card": {
          "token": "6e9f60d7cb764803e153a2fdb04e5d17c"
        }
      }
    }
  ],
  "payout_details_multi": [
    {
      "type": "bank_account",
      "bank_account": {
        "iban": {
          "account": "TR 33 0006 1005 1978 6457 8413 26"
        }
      },
      "system_type": "iban",
      "country": "TUR"
    }
  ],
  "calculate": {
    "amounts": {
      "source": {
        "amount": 357912,
        "currency": "RUB"
      },
      "destination": {
        "amount": null,
        "currency": "TRY"
      }
    }
  },
  "participant_details": {
    "sender": {
      "citizenship_country_iso3": "RUS",
      "first_name": "Ольга",
      "last_name": "Пахмутова",
      "middle_name": "Семёновна",
      "address": {
        "structured_address": {
          "country_iso3": "RUS",
          "postal_code": "192300",
          "state": "Новосибирская",
          "city": "Уренгой",
          "street": "Конаковская",
          "building": "1",
          "flat": "31"
        }
      },
      "date_of_birth": "1998-03-15",
      "identity_document": {
        "id_type": "Паспорт гражданина Российской Федерации",
        "id_number": "8008 579120",
        "issue_date": "2020-03-01",
        "division_code": "213-432",
        "issued_by": "ОВД ПО Кировскому району"
      },
      "contacts": {
        "phone": {
          "full_number": "+79376151530"
        }
      }
    },
    "recipient": {
      "citizenship_country_iso3": "TUR",
      "first_name": "Yusuf",
      "last_name": "Bayındır",
    }
  }
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Options: error, ok
session-objectPayment session
error-objectError
Response examples
{
  "status": "ok",
  "session": {
    "id": "ps_592245",
    "status": "in_progress",
    "created_at": "2022-11-15T15:38:50.255803Z",
    "updated_at": "2022-11-15T15:38:50.336303Z",
    "acquiring_payments": [
      {
        "id": "pm_296251",
        "status": "in_progress",
        "created_at": "2022-11-15T15:38:50.357833Z",
        "payment_details": {
          "type": "card",
          "card": {
            "type": "tokenized_card",
            "tokenized_card": {
              "token": "6e9f60d7cb764803e153a2fdb04e5d17c"
            }
          }
        },
        "calculate": {
          "amounts": {
            "source": {
              "amount": null,
              "currency": "RUB"
            },
            "destination": {
              "amount": 46943404,
              "currency": "KGS"
            }
          }
        },
        "participant_details": {
          "sender": {
            "citizenship_country_iso3": "RUS",
            "first_name": "Ольга",
            "last_name": "Пахмутова",
            "middle_name": "Семёновна",
            "address": {
              "structured_address": {
                "country_iso3": "RUS",
                "postal_code": "192300",
                "state": "Новосибирская",
                "city": "Уренгой",
                "street": "Конаковская",
                "building": "1",
                "flat": "31"
              }
            },
            "date_of_birth": "1998-03-15",
            "identity_document": {
              "id_type": "Паспорт гражданина Российской Федерации",
              "id_number": "8008 579120",
              "issue_date": "2020-03-01",
              "division_code": "213-432",
              "issued_by": "ОВД ПО Кировскому району"
            },
            "contacts": {
              "phone": {
                "full_number": "+79376151530"
              }
            }
          },
          "recipient": {
            "citizenship_country_iso3": "TUR",
            "first_name": "Yusuf",
            "last_name": "Bayındır"
          }
        }
      }
    ],
    "payments": [
      {
        "id": "po_2040",
        "status": "in_progress",
        "created_at": "2024-07-02T12:13:24.894376Z",
        "payment_method": {
          "type": "card",
          "card": {
            "type": "tokenized_card",
            "tokenized_card": {
              "token": "839d41cf716afcb01d581d2827e4472"
            },
          },
          "country": "TUR"
        },
        "calculate": {
          "amounts": {
            "source": {
              "amount": null,
              "currency": "RUB"
            },
            "destination": {
              "amount": 46943404,
              "currency": "KGS"
            }
          }
        },
        "participant_details": {
          "sender": {
            "citizenship_country_iso3": "RUS",
            "first_name": "Ольга",
            "last_name": "Пахмутова",
            "middle_name": "Семёновна",
            "address": {
              "structured_address": {
                "country_iso3": "RUS",
                "postal_code": "192300",
                "state": "Новосибирская",
                "city": "Уренгой",
                "street": "Конаковская",
                "building": "1",
                "flat": "31"
              }
            },
            "date_of_birth": "1998-03-15",
            "identity_document": {
              "id_type": "Паспорт гражданина Российской Федерации",
              "id_number": "8008 579120",
              "issue_date": "2020-03-01",
              "division_code": "213-432",
              "issued_by": "ОВД ПО Кировскому району"
            },
            "contacts": {
              "phone": {
                "full_number": "+79376151530"
              }
            }
          },
          "recipient": {
            "citizenship_country_iso3": "TUR",
            "first_name": "Yusuf",
            "last_name": "Bayındır"
          }
        }
      }
    ],
  }
}

Other methods​

sberpay/push​

Method to send PUSH/SMS notifications to customers for SberPay transactions.

Endpoint​

/api/v1/sberpay/push

Request parameters​

NameMandatoryTypeDescription
session_id+stringSession ID
phone+stringPhone number to send PUSH or SMS
Request example
curl -X GET
https://proxy.bank131.ru/api/v1/sberpay/push \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "session_id": "ps_75459435",
  "phone": "+79638594ххх"
}'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
error-objectError description
Response examples
{
  "status": "ok"
}