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.

Endpoints

The One Time Token resource

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
}

The Challenge Object resource

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
}

The Challenge resource

Fields

typeChallengeType

Type of the challenge

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
    }
  }
}

The Challenge Type resource

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 status of a one time token

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
  }
}

Verify PIN

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.

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, 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.

Example Request

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"
    }'

Example Response

{
  "oneTimeTokenProperties": {
    "oneTimeToken": "9f5f5812-2609-4e48-8418-b64437c0c7cd",
    "challenges": [],
    "validity": 3600
  }
}

Verify FaceMap

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.

The Verify FaceMap 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

faceMaptext

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

oneTimeTokenPropertiesOneTimeToken

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.

Example Request

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>"
    }'

Example Response

{
  "oneTimeTokenProperties": {
    "oneTimeToken": "9f5f5812-2609-4e48-8418-b64437c0c7cd",
    "challenges": [],
    "validity": 3600
  }
}