Purpose

This WS is designed to verify submitted phone number as a part of registration process, generate and send OTP in the context of hashed content that contains phone number that needs to be verified.

Key points

1. This method is used only by TRUSTED_PIS, PIS and CABINET client types.

2. Only one active verification code can exist for phone number.

3. This method can be used only with JWT with fixed set of aud, specific for each client type.

Specification

Apiary

Validate JWT

• Check Authorization header contains a valid JWT

  • in case of error - return 401 ('JWT is invalid')

• Check JWT is not expired (exp > now())

  • in case of error - return 401 ('JWT expired')

• Check JWT is with correct aud : cabinet-registration, pis-registration, trusted-client.

  • in case of error - return 401 ('JWT is not permitted for this action')

Validate request

• Check factor and type fields exist in request and is not empty

  • in case of error - return 422 ('can't be blank')

• Check value in factor field corresponds to phone number regexp

  • in case of error - return 422 ('invalid phone')

• Check value in type field equals to SMS

  • in case of error - return 422 ('is invalid')

• Check content_hash field exists in request and is not empty for aud = pis-registration, trusted-client

  • in case of error - return 422 ('content hash is required for pis and trusted_pis clients')

• Check OTP initialize limit is not exceeded for phone number (based on INIT_VERIFICATION_LIMIT configuration parameter)

  • in case of error - return 429 ('Too many attemts')

Service logic

1. If aud = pis-registration, trusted-client, get value of PIS_VALIDATE_ALL_PHONES config parameter. If aud = cabinet-registration, proceed to p.2.

   1. if it set to true - proceed to p.2.

   2. if it set to false - check existance of phone number in verification database, verified_phones table:

      1. if phone number exists - skip phone number verification, render a response according to specification with result = 'Verified'.

      2. if phone number does not exist - proceed to p.2.

2. Generate verification code using basic random (default) function or time-based algorithm:

   1. Verification code format - digits only (regexp: ^[1-9][0-9]*$)

   2. Verification code length - OTP_CODE_LENGTH configuration parameter (default = 4)

   3. Verification code expiration period - CODE_EXPIRATION_PERIOD_MINUTES configuration parameter (default = 15 min)

3. Search active verification codes for phone number in verifications database, verifications table, if found - cancel them, set:

   1. status = ‘canceled’

   2. is_active = false

4. Send SMS with OTP to phone number from request using SMS provider.

5. Save generated verification code to verifications database, verifications table, set:

   1. id = autogenerate uuid

   2. phone_number = factor

   3. check_digit = checksum digit for verification code

   4. status = ‘new’

   5. code = verification code

   6. code_expired_at = verification code expiration date

   7. is_active = true

   8. attempt_count = 0

   9. inserted_at = now()

   10. content_hash = content_hash

6. Generate response according to specification with result = ‘OTP sent’ and urgent.next_step = ‘REQUEST_OTP'.