For each transaction, the validation code (an OTP) is generated via the SCIM API Authenticator endpoint with the DELIVER-CHALLENGE function.
Specific parameters to generate the validation code:
- tds – contains the message to send to the end user, where "{$secret}" is replaced by the generated OTP.
- correlationid – (optional) allows passing an external correlation ID to a challenge, if present, when validating the transaction with OTP.
Copy
Sample request
POST https://scim.example.com/SCIM/domain/v2/Authenticator/11112.AT_TXOOB HTTP/1.1Content-Type: application/scim+json
Authorization: Bearer RTp7HwAAAW0VlDTQhCrk4etgkODKVAsWIkpJUNL2
{
"schemas": ["urn:hid:scim:api:idp:2.0:Action"],
"urn:hid:scim:api:idp:2.0:Action": {
"action": "DELIVER-CHALLENGE",
"attributes": [
{
"name": "tds",
"value": "To complete your 50 euros purchase on webstore.com, please input the following code : {$secret}"
},
{
"name": "correlationid",
"value": "1111"
},
{
"name": "DEVICETYPE",
"value": "DT_TXOOB"
}
]
}
}Copy
Sample response
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
X-Content-Type-Options: nosniff
Content-Type: application/scim+json;charset=utf-8
{
"schemas": ["urn:hid:scim:api:idp:2.0:Action"],
"attributes": [
{
"name": "CHALLENGE",
"type": "string",
"value": "e0lWPXNiJyGm0qgXWLyCGXI3eTEsQUVTMn0ufTfDY+04yYSQiCJPEf8/1cIKEnsgJX1YDTacsuXYS1cxhljVDZO62LmjRFb5s2UCK22fcAgAwI3icuR5OgUsWfxLgMIq8rg4TIUAwWj1Lp/u7UodNwLpzMpm5MVQinPFxXsr4dab0J2+5SPtuMK3BU+xHqjWCLdtd5vZjSC+Ee16nxhEUwzd0B1HsoMWZz4A+NvjobnJVjyojXOSr8v/SA==;RU5DX0tFWT1ISUQtSUEtNFQuQ1JFRFMuMQ==",
"readOnly": false
},
{
"name": "CHALLENGE.ID",
"type": "string",
"value": "21088",
"readOnly": false
},
{
"name": "REQUEST.STATUS",
"type": "string",
"value": "1",
"readOnly": false
},
{
"name": "REQUEST.REASON",
"type": "string",
"value": "-1",
"readOnly": false
},
{
"name": "REQUEST.ERROR_MESSAGE",
"type": "string",
"readOnly": false
}
]
}The authenticator:
- Generates a new OTP dedicated to this transaction (a plain random number generated by a secure random generator).
- Generates and save the challenge (encrypted) which contains the OTP, tds (message sent to the end user) and, eventually, the correlationid if it is present in the parameters.
- Invokes the delivery gateway to send the message (SMS in this sample) to the end user.
When DELIVER-CHALLENGE is executed with success, and the end user's mobile phone number is correctly configured, they will receive a SMS as follows (where the OTP for the transaction is 49991081):
Note:
- The ActivID AS server supports several transactions in parallel. If a user has several transactions processed by the same ActivID AS instance in parallel:
- "txID" (challengeid) is essential to identifying the transaction
- OTP is the secret used to validate the transaction
- correlationid is strongly recommended since it is useful to add an additional verification to the external transaction to be validated
- The same external transaction (with the same correlationid) can be sent several times (due to non-receive, message latency, or user error). Each time, a new challenge and OTP will be generated, and the validation can be done with any pair of txID and OTP. It's the client application's responsibility to manage the unicity of the same transaction.
- Once the challenge/transaction has been validated with success, the challenge will be deleted. If the same valid txID and OTP pair is sent for the second time, an error will be returned.
