Table of Contents |
---|
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
This method is used only by TRUSTED_PIS, PIS and CABINET client types.
Only one active verification code can exist for phone number.
This method can be used only with JWT with fixed set of
aud
, specific for each client type.
Specification
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
andtype
fields exist in request and is not emptyin case of error - return 422 ('can't be blank')
Check value in
factor
field corresponds to phone number regexpin case of error - return 422 ('invalid phone')
Check value in
type
field equals to SMSin case of error - return 422 ('is invalid')
Check
content_hash
field exists in request and is not empty foraud
=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
If
aud
=pis-registration
,trusted-client
, get value of PIS_VALIDATE_ALL_PHONES config parameter. Ifaud
=cabinet-registration
, proceed to p.2.if it set to true - proceed to p.2.
if it set to false - check existance of phone number in verification database, verified_phones table:
if phone number exists - skip phone number verification, render a response according to specification with result = 'Verified'.
if phone number does not exist - proceed to p.2.
Generate verification code using basic random (default) function or time-based algorithm:
Verification code format - digits only (regexp:
^[1-9][0-9]*$
)Verification code length - OTP_CODE_LENGTH configuration parameter (default = 4)
Verification code expiration period - CODE_EXPIRATION_PERIOD_MINUTES configuration parameter (default = 15 min)
Search active verification codes for phone number in verifications database, verifications table, if found - cancel them, set:
status = ‘canceled’
is_active = false
Send SMS with OTP to phone number from request using SMS provider.
Save generated verification code to verifications database, verifications table, set:
id = autogenerate uuid
phone_number =
factor
check_digit = checksum digit for verification code
status = ‘new’
code = verification code
code_expired_at = verification code expiration date
is_active = true
attempt_count = 0
inserted_at = now()
content_hash =
content_hash
Generate response according to specification with result = ‘OTP sent’ and urgent.next_step = ‘REQUEST_OTP'.