One Time Token
Represents a list of challenges that a user needs to clear in order to access protected resources.
Commonly used for Strong Customer Authentication & 2FA.
Learn from our guide to understand One Time Token Framework.
To ease reading in this document, we will use OTT as an abbreviation for one time token.
Unique identifier of a one time token.
Array of ChallengeObject.
Seconds until the one time token become expired.
The action bound to the one time token.
For example: BALANCE__GET_STATEMENT when we want to retrieve a balance account statement.
Creator of this one time token.
{"oneTimeToken": "5932d5b5-ec13-452f-8688-308feade7834","challenges": [{"primaryChallenge": {"type": "PIN","viewData": {"attributes": {"userId": 6146956}}},"alternatives": [],"required": true,"passed": false}],"validity": 3600,"actionType": "BALANCE__GET_STATEMENT","userId": 6146956}
Type of challenge user can do.
Alternative challenges that user can do instead of the primary ones.
Required (or not) to pass the OTT.
Status of this challenge.
{"primaryChallenge": {"type": "PIN","viewData": {"attributes": {"userId": 6146956}}},"alternatives": [],"required": true,"passed": false}
An object that provides data required to present a challenge window. It can be messages, ids, or other attributes.
{"type": "PIN","viewData": {"attributes": {"userId": 6146956}}}
Enumerated string that indicates what sort of challenge user can do to pass the associated OTT.
Type | Pre-requisite | Endpoint to perform challenge |
---|---|---|
PIN | Create Pin | Verify Pin |
FACE_MAP | Enrol FaceMap | Verify FaceMap |
GET /v1/identity/one-time-token/status
Retrieve necessary information to clear a OTT.
Request
Text value of a OTT.
Response
Properties of OneTimeToken
curl -X GET https://api.sandbox.transferwise.tech/v1/identity/one-time-token/status \-H 'Authorization: Bearer <your api token>'-H 'One-Time-Token: <one time token>'
{"oneTimeTokenProperties": {"oneTimeToken": "9f5f5812-2609-4e48-8418-b64437c0c7cd","challenges": [{"primaryChallenge": {"type": "PIN","viewData": {"attributes": {"userId": 6146956}}},"alternatives": [],"required": true,"passed": false}],"validity": 3600,"actionType": "BALANCE__GET_STATEMENT","userId": 6146956}}
POST /v1/one-time-token/pin/verify
To clear a PIN challenge listed in a OTT.
Notes:
- User is required to create pin before the verification can be successful.
- Rate limit may be applied if there are 5 continuous unsuccessful attempts and OTT creation will be blocked for 15 minutes.
Request
Text value of a OTT.
PIN that is setup using create pin endpoint.
Response
Properties of OneTimeToken.
When successful, response may return the next challenge in challenges
array.
If challenges
array is empty. You may now use the OTT to access an SCA protected endpoint.
curl -X POST https://api.sandbox.transferwise.tech/v1/identity/one-time-token/pin/verify \-H 'Authorization: Bearer <your api token>'-H 'One-Time-Token: <one time token>'-d '{"pin": "1111"}'
{"oneTimeTokenProperties": {"oneTimeToken": "9f5f5812-2609-4e48-8418-b64437c0c7cd","challenges": [],"validity": 3600}}
POST /v1/one-time-token/facemap/verify
To clear a FACE_MAP challenge listed in a OTT.
Notes:
- User is required to enrol facemap before the verification can be successful.
- Rate limit may be applied if there are 5 continuous unsuccessful attempts and OTT creation will be blocked for 15 minutes.
Request
Text value of a OTT.
Base64-encoded binary data as a string.
For more details how to get this binary, please read FaceTec's export API.
To retrieve Wise's FaceTec public key, please refer to our FaceTec's Get Public Key API.
Response
Properties of OneTimeToken.
When successful, response may return the next challenge in challenges
array.
If challenges
array is empty. You may now use the OTT to access an SCA protected endpoint.
curl -X GET https://api.sandbox.transferwise.tech/v1/identity/one-time-token/facemap/verify \-H 'Authorization: Bearer <your api token>'-H 'One-Time-Token: <one time token>'-d '{"faceMap": "<base64_encoded_string>"}'
{"oneTimeTokenProperties": {"oneTimeToken": "9f5f5812-2609-4e48-8418-b64437c0c7cd","challenges": [],"validity": 3600}}