Comment on page
SMS
Validate a user's number and send a one time password via SMS to their phone to verify they have possession.
The PhoneMatch OTP delivery services are asynchronous which means you will make an initial call to send the OTP and receive a response and a second call to validate the user's OTP entry against what was sent.
- 1.Initial Request - Send the phone number with other options via the Initial Request Instructions below and when successful you will receive a response with a template that includes a token value.
- 2.OTP Validation Request - Send the template returned in the initial request including the token and the user's OTP entry back to the system for final match result.
As part of this process you are also validating the number the user provided since the service will not send to invalid phone lines.
post
https://production.idresponse.com
/process/comprehensive/gateway
PhoneMatch5.0.SMS (initial request)
{
"user": "[email protected]",
"pass": "PASSWORD",
"service": "PhoneMatch5.0.SMS",
"reference": "12345",
"options": {
"outofband": {
"message": "Hello {fn}, your one-time password is {pin}",
"do_not_send_to_types": ["voip", "mobile", "landline"],
"country": {
"blacklist": ["ISO2 Country Code"], //countries you do not want to send codes
"whitelist": ["ISO2 Country Code"] //countries you only want to send codes
}
}
},
"target": {
"fn": "John",
"ln": "Smith",
"phone": "2015106000"
}
}
The following are all values that will be returned in the result object of the response.
Action | Detail | Description |
FAIL | SUPPRESSED SENDING CODE | The phone line type was detected as one of the line types passed in the options object in the do_not_send_to_types array |
FAIL | FAILED TO SEND TO NUMBER | An issue occurred during password delivery and it never reached the user |
FAIL | DATA CHECK FAILED | The phone number is invalid and the code could not be sent |
PENDING | TRANSACTION REQUIRES FURTHER ATTENTION | The line type is not in the do_not_send_to_types array, the number is valid and the SMS was sent to the user. The transaction is now waiting for submission of the OTP for final matching |
post
https://production.idresponse.com
/process/continue
PhoneMatch5.0.SMS (OTP validation request)
{
"token": "o76m3nvz94jvaatfsmespzgx3qkzjjl1",
"codematch": {
"key": "12345"
}
}
Action | Detail | Description |
FAIL | FAILED OUT-OF-BAND CHECK | The number is valid, the line type was not found in the do_not_send_to_types array, the OTP was successfully sent, the user entered the OTP and the OTP entered DID NOT match the OTP sent. |
PASS | ALL CHECKS PASSED | The number is valid, the line type was not found in the do_not_send_to_types array, the OTP was successfully sent, the user entered the OTP and the OTP entered matched the OTP sent. |
PhoneMatch+SMS will process with the default base ruleset:
The base ruleset will return a PASS when:
- The phone number is valid
- The phone line type is not found in the
do_not_send_to_types
array - The OTP was sent successfully
- The user OTP entry matched the OTP sent
The base ruleset will return a PENDING when:
- The phone number is valid
- The phone line type is not found in the
do_not_send_to_types
array - The OTP was sent successfully
- The transaction is waiting for submission of the user's OTP entry
The base ruleset will return a FAIL when:
- The phone number is not valid
- The phone line type is found in the
do_not_send_to_types
array - The OTP was not sent successfully
- The user OTP entry did not match the OTP sent
Last modified 10mo ago