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.

Fields
oneTimeTokentext

Unique identifier of a one time token.

challengesChallengeObject[]

Array of ChallengeObject.

validitynumber

Seconds until the one time token become expired.

actionTypetext

The action bound to the one time token.

For example: BALANCE__GET_STATEMENT when we want to retrieve a balance account statement.

userIdnumber

Creator of this one time token.

One Time Token Object
{
"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
}
Fields
primaryChallengeChallenge

Type of challenge user can do.

alternativesChallenge[]

Alternative challenges that user can do instead of the primary ones.

requiredboolean

Required (or not) to pass the OTT.

passedboolean

Status of this challenge.

Challenge Object
{
"primaryChallenge": {
"type": "PIN",
"viewData": {
"attributes": {
"userId": 6146956
}
}
},
"alternatives": [],
"required": true,
"passed": false
}
Fields
typeChallengeType
viewDataobject

An object that provides data required to present a challenge window. It can be messages, ids, or other attributes.

Challenge
{
"type": "PIN",
"viewData": {
"attributes": {
"userId": 6146956
}
}
}

Enumerated string that indicates what sort of challenge user can do to pass the associated OTT.

TypePre-requisiteEndpoint to perform challenge
PINCreate PinVerify Pin

GET /v1/identity/one-time-token/status

Retrieve necessary information to clear a OTT.

Request

Header
One-Time-Tokentext

Text value of a OTT.

Response

oneTimeTokenPropertiesOneTimeToken

Properties of OneTimeToken

Example Request
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>'
Example Response
{
"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:

  1. User is required to create pin before the verification can be successful.
  2. Rate limit may be applied if attempts are too frequent.
The Verify PIN API is currently in closed Beta and subject to change. Please speak with your implementation manager if you would like to use this API

Request

Header
One-Time-Tokentext

Text value of a OTT.

Body
pintext

PIN that is setup using create pin endpoint.

Response

oneTimeTokenPropertiesOneTimeToken

Properties of OneTimeToken.
When successful, PIN challenge will be removed from the challenges array.

Example Request
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>'
-d '{
"pin": "1111"
}'
Example Response
{
"oneTimeTokenProperties": {
"oneTimeToken": "9f5f5812-2609-4e48-8418-b64437c0c7cd",
"challenges": [],
"validity": 3600
}
}