Smart 2FA
What is Smart 2FA?
Exclusively from Veratad, Smart 2FAâ„ finally introduces two-factor authentication to customer onboarding. By combining the best of identity verification and two-factor, Smart 2FA delivers the highest level of surety that your customers are who they say they are.
This service is asynchronous
This service may include two requests:
Initial Request: with this request you will start the session by sending the target. Once started the first thing that will happen is the user will receive the OTP either through call or SMS. You will get a session token in return to send back in the secondary request with the user's OTP entry.
Secondary Request: with this request you will send the entered OTP to be scored. If successful the verification process will also occur and the final result is returned.
SMS or Call
You are able to send the OTP via SMS or Call by adjusting the service name on initial request. The service name will either be:
PhoneMatch5.0.Smart2FA.SMS
PhoneMatch5.0.Smart2FA.Call
Initial Request Parameters and example response
POST https://production.idresponse.com/process/comprehensive/gateway
Request Body
user*
string
Your account's API username
pass*
string
Your account's API password
service*
string
The service name (PhoneMatch5.0.Smart2FA.SMS or PhoneMatch5.0.Smart2FA.Call)
reference
string
A unique identifier for your customer
target*
object
The individual being sent for verification
fn*
string
The target's first name
ln*
object
The target's last name
addr
string
The target's street address (line 1 and line 2)
city
string
the target's city
state
string
The target's state
zip
string
The target's zip
dob
string
The target's Date of Birth (YYYYMMDD format)
ssn
string
The target's SSN (either 4 or 9)
phone*
string
The target's phone number
string
The target's email address
age
string
The age to check (must be sent like "age+" i.e. "18+", "21+" etc.)
options
object
The OTP options
{
"output": {
"outofband": {},
"rescue": {}
},
"meta": {
"confirmation": 127334139,
"reference": "195599",
"service": "PhoneMatch5.0.Smart2FA.SMS",
"timestamp": "2022-03-08 09:39:38",
"company": "Company, LLC",
"user": "[email protected]"
},
"result": {
"action": "PENDING",
"detail": "MORE INFORMATION IS REQUIRED",
"issues": []
},
"continuations": {
"outofband": {
"url": "/process/continue",
"hint": "Enter the six-digit code",
"prompt": "One Time Passcode",
"template": {
"token": "umge9844g0j5d6sebq08qif9isr0xzzl",
"codematch": {
"key": null
}
},
"instructions": "A code has been delivered to the provided number. Please resubmit the code to complete the transaction."
}
}
}Initial Request Body Example
{
"user": "[email protected]",
"pass": "PASSWORD",
"service": "PhoneMatch5.0.Smart2FA.SMS",
"reference": "12345 {A UNIQUE ID}",
"options": {
"outofband": {
"message": "Hello {fn}, your one-time password is {pin}", // this is the SMS message that will be delivered to the user
"do_not_send_to_types": ["landline"] // you can block "landlines" for the SMS service here
}
},
"target":{
"fn":"Barbara",
"ln": "Miller",
"phone": "2015106000"
}
}Initial Request Action and Detail Responses
FAIL
VOIP NOT ALLOWED
The phone line type was detected as VOIP
FAIL
SUPPRESSED SENDING CODE
The phone line type discovered was found in the do_not_send_to_types array in the options block on request
FAIL
FAILED TO SEND TO NUMBER
An issue occurred during OTP delivery and the code was never received by the user
FAIL
DATA CHECK FAILED
The phone number is invalid
PENDING
MORE INFORMATION IS REQUIRED
The line type is not VOIP, the number is valid and the OTP was delivered to the user. The transaction is now waiting for the secondary request to complete.
Secondary request parameters and responses
POST https://production.idresponse.com/process/continue
Return the OTP entered and the token that you received on the Initial response to complete the transaction
Request Body
token*
string
The session token returned on the initial response
codematch:key*
string
The OTP value entered by the user
{{
"final": {
"template": {
"token": "631bg2jx4s7fjwceitituf9nw52yn6i7"
},
"url": "/process/status"
},
"meta": {
"company": "Veratad Technologies, LLC",
"confirmation": 127335232,
"reference": "195599",
"service": "PhoneMatch5.0.Smart2FA.SMS",
"timestamp": "2022-03-08 10:17:55",
"user": "[email protected]"
},
"output": {
"codematch": {
"key_matched": true
}
},
"result": {
"action": "PASS",
"detail": "ALL CHECKS PASSED",
"issues": [
"OUT-OF-BAND SUCCESSFUL"
]
}
}Secondary Request Sample Body
{
"token": "631bg2jx4s7fjwceitituf9nw52yn6i7",
"codematch": {
"key": 12345
}
}Secondary Request Action and Detail Responses
The following are all values that will be returned in the result object of the response.
FAIL
NO MATCH
No matching identity found in the data sources
FAIL
TARGET IS DECEASED
Target found as a deceased identity
FAIL
FAILED OUT-OF-BAND CHECK
The OTP entered did not match what was sent to the user
REVIEW
TRANSACTION REQUIRES FURTHER ATTENTION
Target found and not deceased, but at least one identity attribute provided does not match. This will also populate the issuesobject with a list of the identity attributes that did not match. See full list below
PASS
ALL CHECKS PASSED
Target was found is not deceased and all submitted target attributes match
Issues Responses
When a transaction returns as REVIEW then there will be a list of issues. This list can include any of the below values.
ADDRESS CHECK FAILED
The address provided does not match any on file
DOB CHECK FAILED
The Date of Birth provided does not match any on file
SSN CHECK FAILED
The SSN provided does not math any on file
PHONE CHECK FAILED
The phone number provided does not match any on file
EMAIL CHECK FAILED
The email address provided does not match any on file
AGE CHECK FAILED
The age found does not meet the age submitted
Rules
PhoneMatch+Smart2FA will process with the default ruleset. Which is as follows:
The ruleset will return a PASS when:
All OTP checks have passed
A match is found
The target is not deceased
The target has provided all valid identity attributes including phone number
The ruleset will return a REVIEW when:
A match is found
The target is not deceased
The OTP was delivered
The OTP matched
The target's identity attributes do not all match
This result will also return an array of issues to notify you of exactly which target attributes provided did not match.
The ruleset will return a FAIL when:
A match is not found
The target is deceased
The phone line type is not acceptable
The OTP is not able to be delivered
The OTP entered does not match the OTP sent
Service Testing
Since this service requires a successful OTP process you must use real data and have access to the phone number provided. You will be allotted 250 free transactions for development purposes.
Last updated