Mandarin

# Simplified identification

# Interaction scheme

Simplified identification of an individual is a procedure to confirm the authenticity of the data of an individual. 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 individual's mobile phone number (in the phone parameter).

Both checks take some time. Immediately after initialization, the boolean parameters personVerificationFinished and phoneVerificationFinished have the values false. Upon completion of personal data verification, personVerificationFinished becomes equal to true, upon completion of verification of the phone number, phoneVerificationFinished also becomes equal to true.

When verification of the relevant data is completed, the personVerified boolean parameter indicates the correctness of the personal data, the phoneVerified boolean parameter indicates the correctness of the mobile phone number (if transmitted). When both parameters have the value true, the simplified identification is considered passed.

If both SNILS and TIN were transferred, then they are checked in parallel. In the current implementation, the personVerified boolean parameter takes 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 (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 requests for simplified identification are located in a separate section.

# Initialize 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. 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 the session identifier id, which must be used in subsequent requests. If the optional phone parameter was passed, 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: male, female

Request for identification using SNILS

POST https://secure.mandarinpay.com/api/v2/personidentification/person

{
	"firstName": "Ivan",
	"patronymic": "Ivanovich",
	"lastName": "Ivanov",
	"passportSeries": "1111",
	"passportNumber": "111111",
	"snils": "19033603123",
	"inn": "",
	"phone": "+79001234567",
    "gender": "male"
}

Request for identification by TIN

POST https://secure.mandarinpay.com/api/v2/personidentification/person

{
	"firstName": "Ivan",
	"patronymic": "Ivanovich",
	"lastName": "Ivanov",
	"passportSeries": "1111",
	"passportNumber": "111111",
	"snils": "",
	"inn": "501716749325",
	"phone": "+79001234567",
    "gender": "male"
}

Request for identification using SNILS and TIN

POST https://secure.mandarinpay.com/api/v2/personidentification/person

{
	"firstName": "Ivan",
	"patronymic": "Ivanovich",
	"lastName": "Ivanov",
	"passportSeries": "1111",
	"passportNumber": "111111",
	"snils": "19033603123",
	"inn": "501716749325",
	"phone": "+79001234567",
    "gender": "male"
}

Response if the request was created successfully (200 OK)

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

Response if the request is not created (400 Bad request)

{
	"error": "Invalid request" 
}

# Send 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 includes the session id (in the address) received in the previous request, and the SMS code (in the body of the request). If the request is successfully registered, you will synchronously receive the same session identifier id.

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 repeat sending this request, passing the same id and the 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

PUT https://secure.mandarinpay.com/api/personidentification/{id}

{
	"smsCode": "123456"
}

Response if the request was created successfully (200 OK)

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

Response in case of error (400 Bad request)

{
	"error": "Invalid request" 
}

# Checking identification status

The request to check the identification status includes the session id (in the 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

GET https://secure.mandarinpay.com/api/personidentification/v2/{id}

Response if the request is completed successfully (200 OK)

{
	"id": "794d3cc7-a2b4-4579-9173-bafc7d7dc29d",
	"phoneVerified": true,
	"phoneVerificationFinished": true,
	"personVerified": true,
	"personVerificationFinished": true,
	"personVerificationError": ""
}

Response if the request is pending (200 OK)

{
	"id": "e2c3c860-1d68-427c-a16d-9666e0ffb706",
	"phoneVerified": null,
	"phoneVerificationFinished": false,
	"personVerified": null,
	"personVerificationFinished": false,
	"personVerificationError": null,
	"inn": {
		"status": "NotProcessed",
		"description": "НеTIN was not specified, no verification was performed"
	},
	"snils": {
		"status": "Processing",
		"description": "Processing"
	},
	"passport": {
		"status": "Valid",
		"description": "The information matches"
	},
	"passportDeferred": null
}

Response in case of error (400 Bad request)

{
"error": "Invalid request"
}

Description of response structure

The synchronous response contains the following information:

Parameter Description
id Session ID.
phoneVerificationFinished true - SMS code verification is completed,
false - SMS code verification is not 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 the wrong code.
personVerificationFinished true - verification of personal data is completed,
false - verification of personal data is not completed.
personVerified null - verification of personal data has not been completed,
true - personal data is correct,
false - personal data is not correct.
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 Surname
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:

POST https://secure.psp.io/api/mobilizations

{
    "firstName": "Polygraph",
    "lastName": "Sharikov",
    "patronymic": "Polygraphovich",
    "dateOfBirth": "07.09.1997",
    "passport": "1111222222",
	"dateOfDocument": "07.09.1977"
}

Check by TIN:

POST https://secure.psp.io/api/mobilizations

{
     "firstName": "Polygraph",
     "lastName": "Sharikov",
     "patronymic": "Polygraphovich",
     "dateOfBirth": "09/07/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
GET https://secure.psp.io/api/mobilizations/{ExtId}

Response if the request was created successfully

{
     "extId": "34b63379-66ce-4496-9091-0ffef",
     "orderId": "958477919",
     "actualDate": "2023-07-07T00:00:00+00:00",
     "isMobilized": false,
     "status": "Processed",
     "description": "Operation completed"
}

← User Interface →