Mandarin

# Mandarin.ID

Mandarin.ID is a service for simplified identification of individuals using API. Confirmation of data is carried out through SMEV within the framework of the requirements of 115-FZ; To connect, you need an identification agreement with a partner bank. A general description of the process is on separate page.

# Interaction scheme

The process includes two checks that are performed in parallel, and each of which has its own status.

  1. Verification of the first name, patronymic, last name, series and number of the passport, SNILS and TIN (one of two is enough: SNILS or TIN, but it is possible to transfer both) is done through SMEV.
  2. Mobile phone number verification is performed by sending an SMS code. It is carried out only if you have provided the mobile phone number of an individual (in the parameterphone).

Both checks take some time. Immediately after initialization, the boolean parameterspersonVerificationFinishedAndphoneVerificationFinishedhave meaningsfalse. Upon completion of personal data verificationpersonVerificationFinishedtakes on the valuetrue, after checking the phone numberphoneVerificationFinishedalso becomes equaltrue.

When verification of the corresponding data is completed, the boolean parameterpersonVerifiedindicates the correctness of personal data, boolean parameterphoneVerified- the correctness of the mobile phone number (if it was transferred). When both parameters have a valuetrue, then the simplified identification is considered passed.

If both SNILS and TIN were transferred, then they are checked in parallel. In the current implementation, the boolean parameterpersonVerifiedtakes the value of the result of the check that completed first.

Simplified authentication requests use the standard Mandarin authentication method. Requests with both combat and test authentication data always include a request to SMEV with real personal data, and the actual sending of SMS, and therefore are combat.

IMPORTANT!

By default, the simplified identification functionality is disabled. Write to Support Service (opens new window) to gain access to simplified identification.
The SMEV system provides the test result, usually within 10 minutes. But the verification time may increase due to reasons beyond Mandarin's control.

Simplified Identification Diagram

TESTING

Data for testing is located in the Mandarin.ID section.

# Initializing the identification process

The request to initialize the identification process must include both the SNILS parameter and the TIN parameter, and one of these two parameters may be empty. If you want to use both INN and SNILS, then you need to add a field with the client’s date of birth. Only the passport data of a citizen of the Russian Federation can be transferred as the series and number of the passport.

If the request is successfully registered, you will synchronously receive a session identifierid, which must be used in the following queries. If an optional parameter was passedphone, then an SMS message with a code to confirm the phone number will be sent to the mobile number specified in it.

Parameter Type Required Description
firstName string Yes Name.
patronymic string Yes Surname.
lastName string Yes Surname.
passportSeries string Yes Russian Federation passport series.
passportNumber string Yes Russian passport number.
snils string Yes SNILS number (may be empty if the TIN is filled in).
inn string Yes TIN number (may be empty if SNILS is filled out).
phone string No Mobile number,
in the format+79001234567.
gender string Yes Gender (sex): Male (male), Female (female)
birthDate string Yes Date of birth in format"2021-02-23", parameter is required if SNILS is used in the request

Request for identification with SNILS

curl --request POST \
  --url https://secure.mandarinpay.com/api/v2/personidentification \
  --header 'content-type: application/json' \
  --header 'x-auth: {{x_auth}}' \
  --data '{
  "firstName": "Иван",
  "patronymic": "Иванович",
  "lastName": "Иванов",
  "passportSeries": "1111",
  "passportNumber": "111111",
  "snils": "19033603123",
  "inn": "",
  "phone": "+79001234567",
  "gender": "Male",
  "birthDate": "1997-02-23"
}'

Request for identification with TIN

curl --request POST \
  --url https://secure.mandarinpay.com/api/v2/personidentification \
  --header 'content-type: application/json' \
  --header 'x-auth: {{x_auth}}' \
  --data '{
  "firstName": "Иван",
  "patronymic": "Иванович",
  "lastName": "Иванов",
  "passportSeries": "1111",
  "passportNumber": "111111",
  "snils": "",
  "inn": "501716749325",
  "phone": "+79001234567",
  "gender": "Male"
}'

Request for identification with TIN and SNILS

curl --request POST \
  --url https://secure.mandarinpay.com/api/v2/personidentification \
  --header 'content-type: application/json' \
  --header 'x-auth: {{x_auth}}' \
  --data '{
  "firstName": "Иван",
  "patronymic": "Иванович",
  "lastName": "Иванов",
  "passportSeries": "1111",
  "passportNumber": "111111",
  "snils": "19033603123",
  "inn": "501716749325",
  "phone": "+79001234567",
  "gender": "Male",
  "birthDate": "1997-02-23"
}'

Response if the request was successfully created (200 OK)

{
	"id": "794d3cc7-a2b4-4579-9173-bafc7d7dc29d"
}

Response if the request has not been created (400 Bad request)

{
	"error": "Invalid request" 
}

# Sending SMS code

The request to send an SMS code for verification is performed only in the scenario with verification of a mobile phone number.

It includesidsession (in the address) received in the previous request, and SMS code (in the body of the request). If the request is successfully registered, you will synchronously receive the same session IDid.

If you provided a mobile phone number, but the user entered the SMS code incorrectly, then at the status check stage you will receive"phoneVerified": false. Then you can resend this request by passing the sameidand a new SMS code entered by the user until you receive"phoneVerified": true.

IMPORTANT!

The current version of the protocol allows up to 5 (inclusive) attempts to transmit an SMS code. If the limit is exceeded, the identification process must be initialized again.

Parameter Type Required Description
smsCode string Yes SMS code.

Request with SMS code sent for verification

curl --request PUT \
  --url https://secure.mandarinpay.com/api/personidentification/794d3cc7-a2b4-4579-9173-bafc7d7dc29d \
  --header 'content-type: application/json' \
  --header 'x-auth: {{x_auth}}' \
  --data '{
  "smsCode": "123456"
}'

Response if the request was successfully created (200 OK)

{
	"id": "794d3cc7-a2b4-4579-9173-bafc7d7dc29d"
}

Response if of error (400 Bad request)

{
	"error": "Invalid request" 
}

# Checking identification status

The identification status check request includesidsession (in address).

The response contains the session identifier, indicators of the end of both checks, and indicators of the correctness of the data provided.

In rare cases, SMEV may respond with a delay; for this reason, the status of the request may be pending for a long time. In this case, we recommend checking the status again.

Request Identification Status

curl --request GET \
  --url https://secure.mandarinpay.com/api/personidentification/v2/794d3cc7-a2b4-4579-9173-bafc7d7dc29d \
  --header 'x-auth: {{x_auth}}'

Response if the request is completed successfully (200 OK)

{
	"id": "794d3cc7-a2b4-4579-9173-bafc7d7dc29d",
	"phoneVerified": true,
	"phoneVerificationFinished": true,
	"personVerified": true,
	"personVerificationFinished": true,
	"personVerificationError": null,
    "Inn": {
        "Status": "Valid",
        "Description": "Сведения соответствуют"
    },
    "Snils": {
        "Status": "NotProcessed",
        "Description": "Не указан СНИЛС, проверка не производилась"
    },
    "Passport": {
        "Status": "Valid",
        "Description": "Сведения соответствуют"
    },
    "PassportDeferred": {
        "Status": "Valid",
        "Description": "Сведения соответствуют"
    }
}

Response if the request is pending (200 OK)```json { "id": "e2c3c860-1d68-427c-a16d-9666e0ffb706", "phoneVerified": null, "phoneVerificationFinished": false, "personVerified": null, "personVerificationFinished": false, "personVerificationError": null, "inn": { "status": "NotProcessed", "description": "Не указан ИНН, проверка не производилась" }, "snils": { "status": "Processing", "description": "В обработке" }, "passport": { "status": "Valid", "description": "Сведения соответствуют" }, "passportDeferred": null }


**Response if of error (`400 Bad request`)**

```json
{
	"error": "Invalid request" 
}

Description of response structure

The synchronous response contains the following information:

Parameter Description
id Session ID.
phoneVerificationFinished true- SMS code verification completed,
false- SMS code verification has not been completed.
phoneVerified An SMS message with a code was sent to the user's phone.
null- the user did not enter the code,
true- the user entered the correct code,
false- the user entered an incorrect code.
personVerificationFinished true- personal data verification completed,
false- personal data verification has not been completed.
personVerified null- personal data verification has not been completed,
true- personal data is correct,
false- personal data is incorrect.
personVerificationError A line describing the error from the SMEV if it exists.
If there are no errors, it is empty.
inn An object containing TIN verification data.
inn.status TIN verification status.
inn.description Expanded description of TIN verification status.
snils An object containing SNILS verification data.
snils.status SNILS verification status.
snils.description Expanded description of the SNILS verification status.
passport An object containing passport verification data.
passport.status Passport verification status.
passport.description Expanded description of passport verification status.

# Obtaining information about the status of a mobilized

Creating a mobilized status request

Parameter Type Required Description
firstName string Yes Name
lastName string Yes Last name
patronymic string Yes Middle name
dateOfBirth string Yes Date of birth in DD.MM.YYYY format
inn string Yes* TIN number (*not indicated in case of passport verification)
passport string Yes* Passport series and number without space (*not indicated in case of verification by TIN)
dateOfDocument string Yes* Date of issue of the document in the format DD.MM.YYYY (*required when specifying passport)

Passport verification:

curl --request POST \
  --url https://secure.psp.io/api/mobilizations \
  --header 'content-type: application/json' \
  --header 'x-auth: {{x_auth}}' \
  --data '{
  "firstName": "Полиграф",
  "lastName": "Шариков",
  "patronymic": "Полиграфович",
  "dateOfBirth": "07.09.1997",
  "passport": "1111222222",
  "dateOfDocument": "07.09.1977"
}'

Check by TIN:

curl --request POST \
  --url https://secure.psp.io/api/mobilizations \
  --header 'content-type: application/json' \
  --header 'x-auth: {{x_auth}}' \
  --data '{
  "firstName": "Полиграф",
  "lastName": "Шариков",
  "patronymic": "Полиграфович",
  "dateOfBirth": "07.09.1997",
  "inn": "164441234567"
}'

Response if the request was created successfully

{
  "ExtId": "34b63379-66ce-4496-9091-0ffef"
}

Checking the status of the request for mobilized status

Parameter Type Required Description
extId string Yes Request ID
curl --request GET \
  --url https://secure.psp.io/api/mobilizations/34b63379-66ce-4496-9091-0ffef \
  --header 'x-auth: {{x_auth}}'
```**Response if the request was created successfully**```json
{
    "extId": "34b63379-66ce-4496-9091-0ffef",
    "orderId": "958477919",
    "actualDate": "2023-07-07T00:00:00+00:00",
    "isMobilized": false,
    "status": "Processed",
    "description": "Операция завершена"
}

← Self-employed →