Skip to main content

Methods

During request processing, the system validates the input data, ensures the required headers are present, and confirms that the user has the appropriate rights to perform the operations.

info

In the documentation, the mandatory status of parameters is specified for each transaction, but you are not required to pass them in the body of this particular request. You can pass them in advance—when creating a session.

Example of sending a payout request:

  • If the session/create request was sent empty, the payout request (session/start/payout) must contain all the mandatory parameters.
  • If the session/create request contained all the mandatory parameters specified for the transaction, the payout request (session/start/payout) can be empty or contain only those parameters the values of which you want to override.
  • If the session/create request contained some of the mandatory parameters, the payout request (session/start/payout) must contain the remaining ones.
  • If you create a session and a payout in a single request (session/init/payout), pass all required parameters right away.

Performing operations​

recurrent/disable​

Deactivating a token​

A method for disabling a token for recurring payments. To do this, 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 anymore.

After the token is disabled, the token expiration setting finished_at may contain a date referring to the year 2000. Ignore it.

Endpoint​

/api/v1/recurrent/disable

Request parameters​

NameMandatoryTypeDescription
recurrent+objectToken
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+objectToken information
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,
    "type": "recurrent_token"
  },
  "status": "ok"
}

session/cancel​

Canceling an operation​

A method for canceling a payout or a payment after receiving a ready_to_confirm or ready_to_capture webhook from Bank 131.

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 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",
    "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​

A method for debiting previously held funds after receiving a ready_to_capture webhook from Bank 131. You can debit the amount fully or partially.

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
Response examples
{
  "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"
        }
      }]
    }]
  }
}

session/confirm​

Confirming an operation​

A method for confirming a payout or a payment after receiving a ready_to_confirm or ready_to_capture webhook from Bank 131. The request must be sent within 4 hours of the operation being created; otherwise, a confirm_timeout error is returned.

Endpoint​

/api/v1/session/confirm

Request parameters​

NameMandatoryTypeDescription
session_id+stringSession identifier
confirm_information- (mandatory for operations with settlement and escrow accounts, as well as for money transfers)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 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",
    "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​

Creating a payment session​

A method for creating a payment session. Returns session_id—the session identifier that Bank 131 uses to determine which session a request belongs to.

This method is mandatory for payments via the widget, as session_id is required to generate a public token. The token links the card details entered by the user to a specific session. Without it, Bank 131 cannot determine which payment the entered details and webhooks relate to.

If you accept payments via FPS, be sure to pass faster_payment_system in payment_details.

You can create a session and start a payout/payment at the same time using the session/init method. We do not recommend using this method.

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- (mandatory for payouts)objectInformation about the participants (the sender and the recipient)
customer- (mandatory for payments)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/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​

Creating a session with a simultaneous payment​

A method for running a payment without creating a session separately. In this case, you pass all the data at once.

The response contains the parameters of the created session with the payment information (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​

We do not recommend using this method.

Creating a single-request payment​

A method for running a payment with a single request. Suitable if you do not use the widget.

When using this method, webhooks are not sent. The payment result is returned in the response to this same request.

Learn more about single-request payments >

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 the object descriptions.

NameMandatoryTypeDescription
payment_details+objectPayment data
  type+stringPayment method type. Possible values: card
  card+objectBank card details
    type+stringMethod of card information transmission. Value: bank_card
    bank_card+objectCard 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​

Creating a session with a simultaneous payout​

A method for running a payout without creating a session separately. In this case, you pass all the data at once.

The response contains the parameters of the created session and 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
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",
    "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​

Creating a session with a simultaneous payout with fiscalization​

A method for running a payout to a self-employed person with fiscalization, without creating a session separately. In this case, you pass all the data at once, including the information for fiscalization.

The response contains the parameters of the created session and 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": "Vector LLC",
        "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": "Vector LLC",
          "services": [{
            "name": "Service description",
            "amount_details": {
              "amount": 10000,
              "currency": "rub"
            }
          }]
        }
      },
      "metadata": "order123",
      "participant_details": {
        "recipient": {
          "full_name": "Ivanov Ivan"
        }
      }
    }]
  }
}

session/refund​

Creating a refund​

A method for returning money to the user after a successful payment. You can return the amount fully or partially. A refund cannot be canceled—before sending the request, make sure that it is really necessary.

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

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 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_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​

Starting a payment​

A method for starting a payment within an existing session. In the request, you can pass the missing parameters or replace the ones 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/payment \
  -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​

Starting a payout​

A method for starting a payout within an existing session. In the request, you can pass the missing parameters or replace the ones that have already been passed.

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
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",
    "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​

Starting a payout with fiscalization​

A method for starting a payout to a self-employed person with fiscalization within an existing session. In the request, you can pass the missing data or replace the ones that have already been passed.

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": "Vector LLC",
        "services": [{
          "name": "Goods delivery",
          "amount_details": {
            "amount": 5000,
            "currency": "rub"
          }
        }]
      }
    }
  }'

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",
    "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 LLC"
        }
      }
    }]
  }
}

token​

Getting a token to work with the widgets​

A method for getting a public token required to work with the widgets. It is valid for 24 hours and is intended for a single operation.

In the request, specify the type of widget for which you need to get the token.

Endpoint​

/api/v1/token

Request parameters​

NameMandatoryTypeDescription
tokenize_widget-objectData required by the tokenization widget
acquiring_widget-objectData required by the payment form widget
sber_pay_widget-objectData required by the SberPay widget
Details

An example of a token request for a payout that obtains card details via the widget

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
    }
  }'
An example of how to get 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"
    }
  }'
An example of how to get a token to perform a payment via SberPay
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 '{
    "sber_pay_widget": {
      "session_id": "ps_77872830",
      "phone": "79680000000",
      "return_url": "https://131.ru"
    }
  }'

Response parameters​

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

tokenize​

Tokenizing a bank account number​

A method for tokenizing a bank account (for a 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": "40817***9535"
  }
}

tokenize/elements​

Tokenizing a card number​

A method for tokenizing a bank card number. As a result, the card number is stored in the Bank 131 system, and you receive a token for making multiple payouts to this card. The token has no expiration date.

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 parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
data+objectCard data
error-objectError
Response examples
{
  "status": "ok",
  "data": {
    "number": {
      "token": "adb0eb0ac3f1f5f627f15aa8ca47b13483325ec42baab5e87cbff5f784dca919",
      "info": {
        "masked_card_number": "424242******4242",
        "card_network": "visa",
        "card_type": "visa"
      }
    }
  }
}

Information​

fps/banks​

Getting a list pf FPS member banks​

A method for getting a list of banks with their names and identifiers for sending payouts via the Faster Payments 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​

Verifying an FPS recipient​

A method for checking 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​

Checking the balance​

A method for getting your settlement or escrow 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 POST \
  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​

Getting a bank statement​

A method for getting bank statements for your settlement or escrow account opened in rubles for a day.

Endpoint​

/api/v1/report/account_statement

Request parameters​

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

The date_from and date_to values must match.

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

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+arrayInformation 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​

Getting session information​

A method for obtaining full information about the payment session. For example, you can check the payout status or find out whether the held amount can be debited.

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
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",
    "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"
    }]
  }
}

token/info​

Getting token information​

A method for getting information about a token: both about the linked payment method and about its technical parameters.

With this method you can get the following information:

  • for a card – masked card number and payment system type
  • for an account – masked account number
  • for the token itself – token type, creation date and time, expiration date, active/inactive status at the moment of inquiry

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 a card number hash and receive information about it.

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"
  }
}

wallet/balance​

Checking the balance​

A method for getting the current balance of your collateral account. Use it to make sure there is enough money for payouts and refunds. If the amount is insufficient, top up the account.

note

You can find your acquiring balance information in your online banking service account in the Statements section.

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 examples
{
  "status": "ok",
  "wallets": [{
    "id": "131",
    "amount_details": {
      "amount": 13100,
      "currency": "rub"
    }
  }]
}

Self-employed people​

self_employed/onboarding/create​

Creating a connection request​

A method for creating a connection request to connect a self-employed person to Bank 131.

Request endpoint​

/api/v1/self_employed/onboarding/create

Request parameters​

ParameterMandatoryTypeDescription
return_url-stringURL to redirect the self-employed person after connecting
Request example
curl -X POST \
  https://demo.bank131.ru/api/v1/self_employed/onboarding/create \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "return_url": "https://131.ru/"
  }'

Response parameters​

ParameterMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
onboarding+objectConnection request data
npd_status+stringFederal Tax Service (NPD) status
binding_status+booleanSelf-employed person connection status. Values: true — connected, false — not connected
description-stringPopulated if the connection fails
Response example
{
  "status": "ok",
  "onboarding": {
    "id": "019fd6ca-b080-798e-a1bf-eb7dc096e1de",
    "redirect_url": "https://smz.131.ru/onboarding/019fd6ca-b080-798e-a1bf-eb7dc096e1de",
    "onboarding_status": "created",
    "kyc_status": "not_started"
  },
  "npd_status": "not_started",
  "binding_status": false,
  "description": "ok"
}

self_employed/onboarding/status​

Checking the connection status​

A method for checking the connection status.

Request endpoint​

/api/v1/self_employed/onboarding/status

Request parameters​

ParameterMandatoryTypeDescription
id+stringConnection request identifier
Request example
curl -X POST \
  https://demo.bank131.ru/api/v1/self_employed/onboarding/status \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "id": "019fd6ca-b080-798e-a1bf-eb7dc096e1de"
  }'

Response parameters​

ParameterMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
onboarding+objectConnection request data
npd_status+stringFederal Tax Service (NPD) status
binding_status+booleanSelf-employed person connection status. Values: true — connected, false — not connected
description-stringPopulated if the connection fails
Response example
{
  "status": "ok",
  "onboarding": {
    "id": "019fd6ca-b080-798e-a1bf-eb7dc096e1de",
    "redirect_url": "https://smz.131.ru/onboarding/019fd6ca-b080-798e-a1bf-eb7dc096e1de",
    "onboarding_status": "created",
    "kyc_status": "not_started"
  },
  "npd_status": "not_started",
  "binding_status": false,
  "description": "ok"
}

npd/accruals and npd/request/status​

Checking the self-employed person's tax debt and bonus in detail​

A method for getting detailed information about tax arrears and bonus amount for a self-employed person.

The request consists of two steps:

  1. Send an npd/accruals request, passing a self-employed person's tax ID, 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.

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"
}

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​

Checking the number of unread notifications from the Federal Tax Service for the self-employed​

A method for getting the number of unread notifications from the Federal Tax Service to the self-employed.

The request consists of two steps:

  1. Send an npd/notifications/count request, passing a self-employed person's tax ID, 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. If the status is pending, retry the request later.

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"
}

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​

Sending a notification to the Federal Tax Service regarding the delivery of a notification to the self-employed​

A method for informing the Federal Tax Service that notifications were delivered to a self-employed person. This method must be used after the npd/notifications/read method.

The request consists of two steps:

  1. Send an npd/notifications/mark_as_delivered request, passing a self-employed person's tax ID, 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.

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"
}

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​

Fetching detailed information on unread notifications from the Federal Tax Service for the self-employed​

A method for getting detailed information on unread notifications from the Federal Tax Service to the self-employed.

The request consists of two steps:

  1. Send an npd/notifications/read request, passing a self-employed person's tax ID, 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. If the status is pending, retry the request later.

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"
}

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​

Informing the Federal Tax Service regarding the reading of a notification by the self-employed​

A method for informing the Federal Tax Service that notifications were read by the self-employed. The method must be used after the npd/notifications/mark_as_delivered method.

The request consists of two steps:

  1. Send an npd/notifications/update request, passing a self-employed person's tax ID, 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.

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"
}

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​

Checking the self-employed person's tax debt and bonus​

A method for getting general information about tax arrears and bonus amount for the self-employed.

The request consists of two steps:

  1. Send an npd/taxpayer/account_status request, passing a self-employed person's tax ID, 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.

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"
}

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​

Verifying a self-employed person's data​

A method for verifying 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 steps:

  1. Send an npd/taxpayer/check_personal_info request, passing a self-employed person's tax ID, full name, and phone number, and receive the request_id identifier in response.
  2. Send an npd/request/status request with this identifier. In response, you will receive a list of inconsistent parameters if any. If the status is pending, retry the request later.

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"
}

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/create/nominal​

Creating a payment session​

A method for creating a payment session for a payout to a bank account. It returns session_id—a session identifier used by Bank 131 to determine the session associated with a request.

Use this method if you get the bank account details for a payout through a widget and send the payout as a separate request within the created session.

You can create a session and start a payout at the same time using the session/init/payout/nominal method. We do not recommend this approach.

Endpoint​

/api/v1/session/create/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://demo.bank131.ru/api/v1/session/create/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_12345",
    "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": 300,
        "currency": "rub"
      },
      "paymentMetadata": {},
      "participant_details": {
        "sender": {
          "account": "40702810300200000013"
        },
        "recipient": {
          "beneficiary_id": "1234567890"
        }
      }
    }]
  }
}

session/init/payout/nominal​

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

A method for making a payout to a bank account, including via FPS, without creating a session separately. In this case, you pass all the data at once.

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://demo.bank131.ru/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": {
        "system_type": "ru",
        // for FPS payouts, use the faster_payment_system object
        "ru": {
          "bik": "044525974",
          "account": "40817810400003869535",
          "full_name": "Ivanov Ivan Ivanovich",
          "description": "Funds transfer according to contract No. 5015553111 Ivanov Ivan Ivanovich VAT exempt"
        }
      }
    },
    "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_12345",
    "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": 300,
        "currency": "rub"
      },
      "paymentMetadata": {},
      "participant_details": {
        "sender": {
          "account": "40702810300200000013"
        },
        "recipient": {
          "beneficiary_id": "1234567890"
        }
      }
    }]
  }
}

session/multi/create/nominal​

Creating a payment session​

A method for creating a payment session for a payout to a card. It returns session_id—a session identifier used by Bank 131 to determine the session associated with a request.

Use this method if you get the card details for a payout through a widget and send the payout as a separate request within the created session.

You can create a session and start a payout at the same time using the session/multi/init/payment/nominal method. We do not recommend this approach.

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-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": 30000,
      "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_12345",
    "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": 30000,
        "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": 30000,
        "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 to a bank card​

A method for making a payout to a bank card without creating a session separately. In this case, you pass all the data at once.

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+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": 30000,
      "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_12345",
    "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": 30000,
        "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": 30000,
        "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 to a bank card​

A method for starting a payout within an already created session. In the request, you can pass the missing parameters or replace the ones already passed.

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+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": 30000,
      "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_12345",
    "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": 30000,
        "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": 30000,
        "currency": "RUB"
      },
      "metadata": {
        "key": "value"
      },
      "participant_details": {
        "sender": {
          "full_name": "Ivan Ivanovich Ivanov"
        },
        "recipient": {
          "full_name": "Ivan Ivanovich Ivanov",
          "reference": "1234"
        }
      }
    }]
  }
}

session/start/payout/nominal​

Starting a payout to a bank account​

A method for starting a payout to a bank account, including via FPS, within an already created session. In the request, you can pass the missing parameters or replace the ones already passed.

Endpoint​

/api/v1/session/start/payout/nominal

Request parameters​

NameMandatoryTypeDescription
session_id+stringPayment session identifier
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://demo.bank131.ru/api/v1/session/start/payout/nominal \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-SIGN: signature' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -d '{
    "session_id": "ps_12345",
    "payment_method": {
      "type": "bank_account",
      "bank_account": {
        "system_type": "ru",
        // for FPS payouts, use the faster_payment_system object
        "ru": {
          "bik": "044525974",
          "account": "40817810400003869535",
          "full_name": "Ivanov Ivan Ivanovich",
          "description": "Funds transfer according to contract No. 5015553111 Ivanov Ivan Ivanovich VAT exempt"
        }
      }
    },
    "amount_details": {
      "amount": 30000,
      "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_12345",
    "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": 30000,
        "currency": "rub"
      },
      "paymentMetadata": {},
      "participant_details": {
        "sender": {
          "account": "40702810300200000013"
        },
        "recipient": {
          "beneficiary_id": "1234567890"
        }
      }
    }]
  }
}

Settlement account​

session/create/rko​

Creating a payment session​

A method for creating a payment session for a payout to a bank account.It returns session_id—a session identifier used by Bank 131 to determine the session associated with a request.

Use this method if you get the bank account details for a payout through a widget and send the payout as a separate request within the created session.

You can create a session and start a payout at the same time using the session/init/payout/rko method. We do not recommend this approach.

Endpoint​

/api/v1/session/create/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
fiscalization_details-objectFiscalization details; only for payouts to the self-employed
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/create/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": 10000,
      "currency": "rub"
    },
    "participant_details": {
      "sender": {
        "account": "40702810900000000011"
      }
    }
  }'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-objectSession details
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",
    "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/init/payout/rko​

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

A method for making payouts from a settlement account to a bank account, including via FPS, without creating a session separately. In this case, you pass all the data 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
fiscalization_details-objectFiscalization details; only for payouts to the self-employed
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": 10000,
      "currency": "rub"
    },
    "participant_details": {
      "sender": {
        "account": "40702810900000000011"
      }
    }
  }'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Possible values: error, ok
session-objectSession details
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",
    "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​

Creating a payment session​

A method for creating a payment session for a payout to a card. It returns session_id—a session identifier used by Bank 131 to determine the session associated with a request.

Use this method if you get the card details for a payout through a widget and send the payout as a separate request within the created session.

You can create a session and start a payout at the same time using the session/multi/init/payment/rko method. We do not recommend this approach.

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": 10000,
      "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_3230",
    "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": 10000,
        "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": 10000,
        "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/rko​

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

A method for making a payout to a bank card without creating a session separately. In this case, you pass all the data at once.

Endpoint​

/api/v1/session/multi/init/payment/rko

Request parameters​

NameMandatoryTypeDescription
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)
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/init/payment/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": "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": 10000,
      "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_3230",
    "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": 10000,
        "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": 10000,
        "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​

Starting a payout to a bank card​

A method for starting a payout within an already created session. In the request, you can pass the missing parameters or replace the ones already passed.

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)
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/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": 10000,
      "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_12345",
    "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": 10000,
        "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": 10000,
        "currency": "RUB"
      },
      "metadata": {
        "key": "value"
      },
      "participant_details": {
        "sender": {
          "full_name": "Ivan Ivanovich Ivanov"
        },
        "recipient": {
          "full_name": "Ivan Ivanovich Ivanov",
          "reference": "1234"
        }
      }
    }]
  }
}

session/start/payout/rko​

Starting a payout to a bank account​

A method for starting a payout to a bank account within an existing session. In the request, you can pass the missing parameters or replace the ones already passed.

Endpoint​

/api/v1/session/start/payout/rko

Request parameters​

NameMandatoryTypeDescription
session_id+stringPayment session identifier
payment_method+objectPayment details (bank account)
amount_details+objectAmount in kopecks. To send 100 rubles, specify 10000
participant_details+objectSender's details
fiscalization_details-objectFiscalization details; only for payouts to the self-employed
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/start/payout/rko  \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "session_id": "ps_3230",
    "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": 10000,
      "currency": "rub"
    },
    "participant_details": {
      "sender": {
        "account": "40702810900000000011"
      }
    }
  }'

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": "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"
    }]
  }
}

Money transfers​

calculate​

Calculating currency conversion for a money transfer​

A method for calculating currency conversion for a money transfer.

The currency exchange rate can be calculated as follows:

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

Endpoint​

/api/v1/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 inverse exchange rate
    currency+stringISO 4217 currency code. Case insensitive. The rub value is mandatory in either of the following objects: source.currency or destination.currency
  destination+objectAmount and currency to be paid to the recipient
    amount+numberAmount in decimal format (kopecks) to calculate the inverse exchange rate, or the null value to calculate the direct exchange rate
    currency+stringISO 4217 currency code. Case insensitive. The rub value is mandatory in either of the following objects: source.currency or destination.currency
Request examples
curl -X POST \
  https://demo.bank131.ru/api/v1/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+objectExchange 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
  destination+objectAmount and currency to be paid to the recipient
    amount+numberCalculated amount to be received
    currency+stringISO 4217 currency code. Case insensitive
  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 inverse exchange rate
    currency+stringISO 4217 currency code. Case insensitive
  destination+objectAmount and currency to be paid to the recipient (passed in the request)
    amount+numberAmount in decimal format (kopecks) to calculate the inverse exchange rate, or the null value to calculate the direct exchange rate
    currency+stringISO 4217 currency code. Case insensitive
  rate+objectExchange rate
    fx_rate+numberRatio of the currency to ruble (of the target currency to the write-off currency), displayed to 4 decimals. Example: 75.0145
    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
    }
  }
}

session/multi/init​

Creating a multisession with a simultaneous cross-border transfer start​

A method for creating a multisession and starting a cross-border transfer—debiting funds from the sender and paying them out to the recipient without creating a session separately.

Endpoint​

/api/v2/session/multi/init

Request parameters​

NameMandatoryTypeDescription
payment_list+arrayList of outgoing transactions from the sender
  amount_details+objectPayout amount details. This value mirrors payout_list.amount_details
    amount+numberAmount in decimal format (kopecks). To send 100 rubles, specify 10000
    currency+stringISO 4217 currency code. Case insensitive
  customer+objectData about the user (payout recipient or payment sender) in your system
    reference+stringIdentifier of the user (payout recipient or payment sender) in your system
  participant_details+objectInformation on transfer participants
    sender+objectSender details
      first_name+stringFirst name
      last_name+stringLast name
      middle_name-stringPatronymic name
      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
      identity_document+objectSender's identity document
        id_type+stringType of the sender's identity document. Possible values:
- Passport of a citizen of the Russian Federation
- Non-resident ID
        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 non-resident identity document expiration 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
      citizenship_country_iso3+stringSender's country of citizenship according to ISO 3166-1 alpha-3
      contacts+arraySender'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). Only for transfers to Turkey with cash pick-up
          operator_code-stringOperator's code of the phone number. Only for transfers to Turkey with cash pick-up
          short_number-stringPhone number without the operator's code. Only for transfers to Turkey with cash pick-up
      country_iso3+stringCountry code (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
  payment_options-objectPayment parameters
    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. Pass the bank card token in payment_details
  payment_details+objectWrite-off details
    type+stringType of payment method. Possible values:
- card — bank card
- recurrent — transaction with previously saved card details
    card-objectBank card details для type = card
    recurrent-objectBank card token data для type = recurrent
payout_list+arrayList of incoming transactions to the recipient
  amount_details+objectPayout amount details. This value mirrors payment_list.amount_details
    amount+numberAmount in decimal format (kopecks). To send 100 rubles, specify 10000
    currency+stringISO 4217 currency code. Case insensitive
  participant_details+objectInformation on transfer participants
    recipient+objectRecipient details
      first_name+stringFirst name
      last_name+stringLast name
      middle_name-stringPatronymic name
      tax_reference-stringRecipients's INN (12 digits)
      date_of_birth-stringRecipients's date of birth in the YYYY-MM-DD format. Make sure the recipient is 18 years old or older
      identity_document-objectRecipient's identity document
        id_type+stringType of the recipient's identity document. Possible values:
- Passport of a citizen of the Russian Federation
- Non-resident ID
        id_number+stringRecipient's identity document series and number (without spaces)
        issue_date+stringRecipient's identity document issue date in the YYYY-MM-DD format
        id_expiration_date-stringRecipient's non-resident identity document expiration date in the YYYY-MM-DD format
        division_code-stringCode of the division that issued the recipient's identity document. Required if available in the document
        issued_by-stringName of the division that issued the recipient's identity document. Required if available in the document
      citizenship_country_iso3+stringRecipient's country of citizenship according to ISO 3166-1 alpha-3
      contacts+arrayRecipient'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
          country_iso3-stringRecipient's phone number country code (ISO 3166-1 alpha-3). Only for transfers to Turkey with cash pick-up
          operator_code-stringOperator's code of the phone number. Only for transfers to Turkey with cash pick-up
          short_number-stringPhone number without the operator's code. Only for transfers to Turkey with cash pick-up
      purpose-stringTransfer purpose. If recipient.country_iso3 = AZE:
- gift
- donation
- support
- education
- other
      country_iso3-stringCountry code (ISO 3166-1 alpha-3)
      postal_code-stringPostal code of the recipient's place of registration
      state-stringState or region of the recipient's place of registration
      city-stringLocality of the recipient's place of registration
      street-stringStreet of the recipient's place of registration
      building-stringBuilding number of the recipient's place of registration
      flat-stringApartment of the recipient's place of registration
  payout_details+objectPayout details
    type+stringTransfer receiving options. Options:
- card (to a bank card)
- bank_account (IBAN)
- tokenized_card (to previously saved card details)
- moneysend (in cash)
    card-objectBank card details for type = card
    bank_account-objectIBAN for type = bank_account
    tokenized_card-objectBank card token data for type = tokenized_card
    moneysend-objectPass the object for cash transfers, always empty: {}
Request examples
curl -X POST \
  https://demo.bank131.ru/api/v2/session/multi/init   \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "payment_list": [{
      "amount_details": { // The same as in the payout_list, the amount and currency should be the same
        "amount": 37700,
        "currency": "TJS"
      },
      "customer": {
        "reference": "lucky"
      },
      "participant_details": {
        "sender": {
          "citizenship_country_iso3": "TRY",
          "first_name": "Ольга",
          "last_name": "Зайцева",
          "middle_name": "Александровна",
          "country_iso3": "RUS",
          "state": "Московская область",
          "city": "Уренгой",
          "postal_code": "119900",
          "street": "Конаковская",
          "building": "99",
          "flat": "1",
          "date_of_birth": "1998-03-15",
          "identity_document": {
            "id_type": "Паспорт иностранного гражданина",
            "id_number": "8008 579120",
            "issue_date": "2020-03-01"
          },
          "contacts": {
            "phone": {
              "full_number": "+79376151530",
              "country_iso3": "TJK",
              "operator_code": "937",
              "short_number": "6151530"
            },
            "email": "sender@test.com"
          }
        }
      },
      "payment_options": {
        "return_url": "https://www.131.ru/"
      },
      "payment_details": {
        "type": "card",
        "card": {
          "type": "bank_card",
          "bank_card": {
            "number": "4111111111111111"
          }
        }
      }
    }],
    "payout_list": [{ // The same as in the payment_list, the amount and currency should be the same
      "amount_details": {
        "amount": 37700,
        "currency": "TJS"
      },
      "participant_details": {
        "recipient": {
          "first_name": "Sidor",
          "last_name": "Sidorov",
          "middle_name": "Sidorovich",
          "date_of_birth": "2000-11-08",
          "country_iso3": "TJK",
          "citizenship_country_iso3": "TJK",
          "contacts": {
            "phone": {
              "full_number": "+43523452345",
              "country_iso3": "TJK",
              "operator_code": "352",
              "short_number": "3452345"
            },
            "email": "recipient@test.tr"
          }
        }
      },
      "payout_details": {
        "type": "card",
        "card": {
          "type": "bank_card",
          "bank_card": {
            "number": "2204320396205389"
          }
        }
      }
    }]
  }'

Response parameters​

NameMandatoryTypeDescription
status+stringStatus. Options: error, ok
session+objectPayment session
error-objectError
Response examples
{
  "status": "ok",
  "session": {
    "id": "ps_3808365",
    "status": "in_progress",
    "created_at": "2025-08-08T12:39:15.668563Z",
    "updated_at": "2025-08-08T12:39:16.388348Z",
    "payout_list": [{
      "id": "po_955259",
      "status": "in_progress",
      "created_at": "2025-08-08T12:39:16.439833Z",
      "payout_details": {
        "type": "card",
        "card": {
          "brand": "mir",
          "last4": "5389",
          "country_iso3": "RUS"
        }
      },
      "amount_details": {
        "amount": 37700,
        "currency": "TJS"
      },
      "amounts": {},
      "payment_metadata": {},
      "participant_details": {
        "recipient": {
          "full_name": "Sidor Sidorov Sidorovich",
          "first_name": "Sidor",
          "last_name": "Sidorov",
          "middle_name": "Sidorovich",
          "country_iso3": "TJK",
          "date_of_birth": "2000-11-08",
          "citizenship_country_iso3": "TJK",
          "contacts": {
            "phone": {
              "full_number": "+43523452345",
              "country_iso3": "TJK",
              "operator_code": "352",
              "short_number": "3452345"
            },
            "email": "recipient@test.tr"
          }
        }
      }
    }],
    "payment_list": [{
      "id": "pm_2765898",
      "status": "in_progress",
      "created_at": "2025-08-08T12:39:16.439730Z",
      "customer": {
        "reference": "lucky"
      },
      "payment_details": {
        "type": "card",
        "card": {
          "brand": "visa",
          "last4": "1111",
          "country_iso3": "POL"
        }
      },
      "amount_details": {
        "amount": 37700,
        "currency": "TJS"
      },
      "amounts": {},
      "participant_details": {
        "sender": {
          "full_name": "Ольга Зайцева Александровна",
          "first_name": "Ольга",
          "last_name": "Зайцева",
          "middle_name": "Александровна",
          "country_iso3": "RUS",
          "city": "Уренгой",
          "postal_code": "119900",
          "building": "99",
          "date_of_birth": "1998-03-15",
          "street": "Конаковская",
          "flat": "1",
          "state": "Московская область",
          "identity_document": {
            "id_type": "Паспорт иностранного гражданина",
            "id_number": "8008 579120",
            "issue_date": "2020-03-01"
          },
          "citizenship_country_iso3": "TRY",
          "contacts": {
            "phone": {
              "full_number": "+79376151530",
              "country_iso3": "TJK",
              "operator_code": "937",
              "short_number": "6151530"
            },
            "email": "sender@test.com"
          }
        }
      },
      "payment_options": {
        "return_url": "https://www.131.ru/",
        "recurrent": false
      }
    }]
  }
}