Skip to main content

Verification of beneficiaries before payouts

For security purposes, Bank 131 is required to identify the beneficiaries associated with an escrow account. The API only supports verification for individual beneficiaries who are resident recipients. To verify other beneficiaries, submit the data to the Bank in an Excel file by any convenient means.

Verification via the API​

Server address​

For testing: https://kyc-stage.bank131.ru/

For live transactions: https://kyc.bank131.ru/

Learn more about the request format >

Request signature​

First set up your EECDS:

  1. Get the enhanced encrypted and certified digital signature (EECDS) from any verification center. Non-resident individuals can sign their requests using RSA Keys.

    For testing, you can create a certificate in the CryptoPro Test Verification Center.

  2. Install CryptoPro CSP and add your certificate to the vault (for example, check this guide for Windows).
  3. Provide Bank 131 with the list of IP addresses you will use to send requests from.
  4. Send the public signature key to your Bank 131 manager so we can identify your requests.

You can now sign your requests as follows:

  1. Take the payload content, sort by key alphabetically, and write to the file using the UTF-8 encoding.
Example of writing payload content to a file
import json

payload = {...}

payload_bytes = bytes(json.dumps(payload, sort_keys=True) + '\r\n', encoding='utf-8')

with open('payload_bytes.jsonb', 'wb') as f:
    f.write(payload_bytes)

  1. Sign the file with CryptoPro. You can use the cryptcp utility.
Example of file signing
cryptcp -sign -display -thumbprint <signature key fingerprint> -detached payload_json.json payload_json.sig
  1. Pass the signature from payload_json.sig in the signature field of the request.

Sending data for verification​

Send a check request with the individual's data. You will get a request ID in the response. Use it to see the verification result.

Request parameters​

NameMandatoryTypeDescription
type+stringRecipient type: FL_RESIDENT
last_name+stringLast name
first_name+stringFirst Name
patronymic-stringPatronymic
birthday+stringDate of birth in the following format: DD.MM.YYYY. Should be 18 years old or older
birthplace+stringPlace of birth
citizenship+stringCitizenship in ISO 3166-1 alpha-2 format
inn+stringINN: 12 digits
phone_number+stringPhone number (any format)
email+stringValid email address
documents+arrayRussian passport: PASSPORT_RF
  type+stringDocument type: PASSPORT_RF for Russian passport
  number+stringPassport series and number in the following format: 1234567890
  issuer+stringIssuing division
  issuer_date+stringDate of issue in the following format: DD.MM.YYYY
  issuer_code+stringSubdivision code
address+stringAddress of registration
postcode-stringZIP code
agent_contract_number+stringNumber of the agency agreement with the recipient
agent_contract_date+stringDate of the agency agreement with the recipient in the following format: DD.MM.YYYY. Must be less than or equal to the current date
beneficial_owners+stringInformation on beneficiary owners. Always: No BO
public_officials+stringStatus as a public official. Always: No
Request example
curl -X POST \
  https://kyc.bank131.ru/api/v2/check \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \
  -H 'X-PARTNER-SIGN: signature' \
  -d '{
    "type": "FL_RESIDENT",
    "last_name": "Dmitriev",
    "first_name": "Ivan",
    "patronymic": "Ivanovich",
    "birthday": "01.01.1970",
    "birthplace": "Novgorod",
    "citizenship": "RU",
    "inn": "065553161159",
    "phone_number": "+79000000000",
    "email": "name@email.com",
    "documents": [{
      "type": "PASSPORT_RF ",
      "number": "0234567890",
      "issuer": "UFMS Russia",
      "issuer_date": "01.01.2010",
      "issuer_code": "123-000"
    }],
    "address": "Novgorod, Pribrezhnaya str., 53",
    "postcode": "365826",
    "agent_contract_number": "123456789-0",
    "agent_contract_date": "01.01.2020",
    "beneficial_owners": "No BO",
    "public_officials": "No"
  }'

Response parameters​

NameMandatoryTypeDescription
status+stringIdentification status. Possible options: ok, error
data-DataResponse details
  id-numbercheck request ID
  description-stringRequest status description
error-ErrorError details
  code+stringError code
  description+stringError description
Response examples 
{
  "status": "ok",
  "data": {
    "id": "7",
    "description": "request added to queue"
  }
}
Response example for a test request

For testing, the value of the status field sent in the response strictly depends on the last digit in ID number of the passport_number field sent in the request.

Last digit in passport_numberstatus value
Even, including 0ok
Odderror

Verification results​

To get the verification result, use the check/{id} method. In the request, specify the ID you received in the response to the check request. Result processing may take anywhere from 10 minutes to 2 days.

Request parameters​

The request body is empty.

Request example
curl -X GET \
  https://kyc.bank131.ru/api/v2/check/7 \
  -H 'Content-Type: application/json' \
  -H 'X-PARTNER-PROJECT: your_project_name' \

Response parameters​

NameMandatoryTypeDescription
status+stringIdentification status. Possible options: ok, pending, error
data-DataResponse details
  id-numbercheck request ID
  description-stringRequest status description
error-ErrorError details
  code+stringError code
  description+stringError description
Response examples 
{
  "status": "ok",
  "data": {
    "id": "7",  // check request ID
    "description": "valid"
  }
}

Error codes and statuses​

HTTP response codes​

CodeDescriptionWhat you can do
200Correct requestCheck status
422Request errorSee error.description for details:
- request_body_validation_error — error in the request body
- request_header_validation_error — x-partner-project header missing
500Error on Bank 131's sideTry again later

Response statuses​

Response statuses are passed in the status field.

StatusDescriptionРешение
okRequest processed successfullyCheck data
pendingRequest is being processedTo find out the result, retry the request later
errorRequest processing errorCheck error

Error codes​

Errors are passed in the error object:

  • code — error code
  • description — error description
CodeDescriptionWhat you can do
invalid_signЗапрос с указанным идентификатором подписан некорректноVerify the request signature is properly generated
passport_validation_failureПо данным МДВ предоставленный паспорт признан недействительным The passport is invalid. Check the passport data
passport_validation_failureВ базе данных МВД отсутствуют сведения о предоставленном паспортеNo information about the passport was found. Check the passport data
inn_validation_failureПо данным ФНС предоставленный паспорт не соответствует предоставленному ИННThe INN value is not linked to the passport specified. Check the INN
already_existsЗапрос на проверку с теми же данными был направлен ранееYou have already submitted these data for identification. To see the result, send a check{id} request with the previous verification's ID that you received in the data.id field
request_not_foundНе найден запрос с указанным идентификаторомThe request with the given ID was not found. Check the ID
partner_project_not_foundНе найден проект с указанным в заголовке идентификаторомThe project ID sent in the X-PARTNER-PROJECT header does not exist. Check the ID
birthday_validation_failureВозраст проверяемого лица ниже допустимого порогаThe verified subject must be an adult. If you receive this error when working with a nominal account, contact your manager
validation_errorRequest validation error. Example: 1 validation error for Request.body → payload → documents → 2 → expire_date. Document MIGRATION_CARD is expired (type=value_error)Invalid formats and/or controls in values. For detailed information see the description field
Response examples 
{
  "status": "error",
  "error": {
    "code": "passport_validation_failure",
    "description": "По данным МДВ предоставленный паспорт признан недействительным"
  }
}