# One Time Token

These endpoints are deprecated. Please refer to [strong-customer-authentication](/api-reference/strong-customer-authentication) section to integrate with SCA.

Represents a list of challenges that a user needs to clear in order to access protected resources.

Commonly used for [Strong Customer Authentication & 2FA](/guides/developer/auth-and-security/sca-and-2fa).

Learn from our [guide](/guides/developer/auth-and-security/one-time-token) to understand One Time Token Framework.

To ease reading in this document, we will use OTT as an abbreviation for one time token.

The Verify PIN/FaceMap/Device Fingerprint APIs are currently in closed Beta and subject to change. Please speak with your implementation manager if you would like to use these APIs

Operations 

## The One Time Token resource 

We suggest the following method to check if the OTT is ready to access an SCA protected endpoint.

Iterate through `challenges` array and look for any [challenge](/api-reference/one-time-token#challenge-object) that has the following properties:

1. `required` is true
2. `passed` is false


Fields
oneTimeToken
Unique identifier of a one time token.

challenges
Array of [ChallengeObject](/api-reference/one-time-token#challenge-object).

validity
Seconds until the one time token become expired.

actionType
The action bound to the one time token.

For example: *BALANCE__GET_STATEMENT* when we want to [retrieve a balance account statement](/api-reference/balance-statement#get).

userId
Creator of this one time token.

One Time Token Object

```json
{
  "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
primaryChallenge
[Type of challenge](/api-reference/one-time-token#challenge) user can do.

alternatives
Alternative [challenges](/api-reference/one-time-token#challenge) that user can do instead of the primary ones.

required
Required (or not) to pass the OTT.

passed
Status of this challenge.

Challenge Object

```json
{
  "primaryChallenge": {
    "type": "PIN",
    "viewData": {
      "attributes": {
        "userId": 6146956
      }
    }
  },
  "alternatives": [],
  "required": true,
  "passed": false
}
```

## The Challenge resource 

Fields
type
[Type of the challenge](/api-reference/one-time-token#challenge-type)

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

Challenge

```json
{
  "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 trigger challenge | Endpoint to perform challenge |
|  --- | --- | --- | --- |
| PIN | [Create Pin](/api-reference/user-security#create-pin) | - | [Verify Pin](/api-reference/one-time-token#verify-pin) |
| FACE_MAP | [Enrol FaceMap](/api-reference/user-security#enrol-facemap) | - | [Verify FaceMap](/api-reference/one-time-token#verify-facemap) |
| SMS | [Create Phone Number](/api-reference/user-security#create-phone-number) | [Trigger SMS Challenge](/api-reference/one-time-token#trigger-sms) | [Verify SMS](/api-reference/one-time-token#verify-sms) |
| WHATSAPP | [Create Phone Number](/api-reference/user-security#create-phone-number) | [Trigger WhatsApp Challenge](/api-reference/one-time-token#trigger-whatsapp) | [Verify WhatsApp](/api-reference/one-time-token#verify-whatsapp) |
| VOICE | [Create Phone Number](/api-reference/user-security#create-phone-number) | [Trigger Voice Challenge](/api-reference/one-time-token#trigger-voice) | [Verify Voice](/api-reference/one-time-token#verify-voice) |
| PARTNER_DEVICE_FINGERPRINT | [Create Device Fingerprint](/api-reference/user-security#create-device-fingerprint) | - | [Verify Device Fingerprint](/api-reference/one-time-token#verify-device-fingerprint) |


## Get status of a one time token 

**`GET /v1/one-time-token/status`**

Notes:

1. **`GET /v1/identity/one-time-token/status`** will be deprecated soon.
2. Please use the new endpoint **/v1/one-time-token/status** instead.


Retrieve necessary information to clear a OTT.

### Request

Header
One-Time-Token
Text value of a OTT.

### Response

oneTimeTokenProperties
Properties of [OneTimeToken](/api-reference/one-time-token#object)

Example Request

```shell
curl -X GET \
  https://api.sandbox.transferwise.tech/v1/one-time-token/status \
  -H 'Authorization: Bearer <your api token>'
  -H 'One-Time-Token: <one time token>'
```

Example Response

```json
{
  "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`**

[](/guides/developer/auth-and-security/jose-jwe)

To clear a **PIN** challenge listed in a OTT.

Notes:

1. User is required to [create pin](/api-reference/user-security#create-pin) before the verification can be successful.
2. Rate limit may be applied if there are 5 continuous unsuccessful attempts and OTT creation will be blocked for 15 minutes.


### Request

Header
One-Time-Token
Text value of a OTT.

Body
pin
PIN that is setup using [create pin endpoint](/api-reference/user-security#create-pin).

### Response

oneTimeTokenProperties
Take note that the raw response body will be a string.
Please refer to our [JOSE guide](/guides/developer/auth-and-security/jose-jws) on how should you decrypt this.

Properties of [OneTimeToken](/api-reference/one-time-token#object).

Example Request

```shell
curl -X POST \
  https://api.sandbox.transferwise.tech/v1/one-time-token/pin/verify \
  -H 'Authorization: Bearer <your api token>' \
  -H 'Accept: application/jose+json' \
  -H 'Accept-Encoding: identity' \
  -H 'Content-Type: application/jose+json' \
  -H 'Content-Encoding: identity' \
  -H 'X-TW-JOSE-Method: jwe' \
  -H 'One-Time-Token: <one time token>' \
  -d 'eyJlbmMiOiJBMjU2R0NNIiwi...'
```

Example Response

```text
eyJlbmMiOiJBMjU2R0NNIiwi...
```

## Verify Device Fingerprint 

**`POST /v1/one-time-token/partner-device-fingerprint/verify`**

[](/guides/developer/auth-and-security/jose-jwe)

To clear a **Device Fingerprint** challenge listed in an OTT.

Notes:

1. User is required to [create a device fingerprint](/api-reference/user-security#create-device-fingerprint) before the verification can be successful.
2. Rate limit may be applied if there are 5 continuous unsuccessful attempts and OTT creation will be blocked for 15 minutes.


### Request

Header
One-Time-Token
Text value of a OTT.

Body
deviceFingerprint
Device Fingerprint previously set.

### Response

oneTimeTokenProperties
Take note that the raw response body will be a string.
Please refer to our [JOSE guide](/guides/developer/auth-and-security/jose-jws) on how should you decrypt this.

Properties of [OneTimeToken](/api-reference/one-time-token#object).
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

```shell
curl -X POST \
  'https://api.sandbox.transferwise.tech/v1/one-time-token/partner-device-fingerprint/verify' \
  -H 'Authorization: Bearer <your api token>' \
  -H 'Accept: application/jose+json' \
  -H 'Accept-Encoding: identity' \
  -H 'Content-Type: application/jose+json' \
  -H 'Content-Encoding: identity' \
  -H 'X-TW-JOSE-Method: jwe' \
  -H 'One-Time-Token: <one time token>' \
  -d 'eyJlbmMiOiJBMjU2R0NNIiwi...'
```

Example Response

```text
eyJlbmMiOiJBMjU2R0NNIiwi...
```

## Verify FaceMap 

**`POST /v1/one-time-token/facemap/verify`**

To clear a **FACE_MAP** challenge listed in a OTT.

Notes:

1. User is required to [enrol facemap](/api-reference/user-security#enrol-facemap) before the verification can be successful.
2. Rate limit may be applied if there are 5 continuous unsuccessful attempts and OTT creation will be blocked for 15 minutes.


### Request

Header
One-Time-Token
Text value of a OTT.

Body
faceMap
Base64-encoded binary data as a string.

For more details how to get this binary, please read FaceTec's [export API](https://dev.facetec.com/api-guide#export-3d-facemap).

To retrieve Wise's FaceTec public key, please refer to our FaceTec's [Get Public Key API](/api-reference/facetec#public-key).

### Response

oneTimeTokenProperties
Properties of [OneTimeToken](/api-reference/one-time-token#object).

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

```shell
curl -X POST \
  https://api.sandbox.transferwise.tech/v1/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

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

## Trigger SMS Challenge 

**`POST /v1/one-time-token/sms/trigger`**

To trigger a SMS challenge by sending SMS to user verified [phone number](/api-reference/user-security#phone-number) containing a 6 digit one time password (**OTP**).

This **OTP** code can be used to clear a [SMS](/api-reference/one-time-token#challenge-type) challenge by using the [verify sms endpoint](/api-reference/one-time-token#verify-sms).

### Request

Header
One-Time-Token
Text value of a OTT.

### Response

obfuscatedPhoneNo
Obfuscated phone number that can be used as a hint for the end customer regarding which phone
number the SMS was sent to.

Example Request

```shell
curl -X POST \
  https://api.sandbox.transferwise.tech/v1/one-time-token/sms/trigger \
  -H 'Authorization: Bearer <your api token>' \
  -H 'One-Time-Token: <one time token>'
```

Example Response

```json
{
  "obfuscatedPhoneNo": "*********8888"
}
```

## Verify SMS Challenge 

**`POST /v1/one-time-token/sms/verify`**

To clear a **SMS** challenge listed in a OTT.

Notes:

1. User is required have a verified phone number. See [create phone number](/api-reference/user-security#create-phone-number) for more information.
2. [Trigger SMS Challenge](/api-reference/one-time-token#trigger-sms) is required to be called first.
3. Since we won't be sending real SMS on sandbox, the **OTP Code** will always be **111111**.


The Verify SMS Challenge 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-Token
Text value of a OTT.

Body
otpCode
6 digit OTP code in text format.

### Response

oneTimeTokenProperties
Properties of [OneTimeToken](/api-reference/one-time-token#object).

Example Request

```shell
curl -X POST \
  https://api.sandbox.transferwise.tech/v1/one-time-token/sms/verify \
  -H 'Authorization: Bearer <your api token>' \
  -H 'One-Time-Token: <one time token>' \
  -d '{
    "otpCode": "111111"
  }'
```

Example Response

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

## Trigger WhatsApp Challenge 

**`POST /v1/one-time-token/whatsapp/trigger`**

To trigger a WhatsApp challenge by sending WhatsApp message to user verified [phone number](/api-reference/user-security#phone-number) containing a 6 digit one time password (**OTP**).

This **OTP** code can be used to clear a [WHATSAPP](/api-reference/one-time-token#challenge-type) challenge by using the [verify whatsapp endpoint](/api-reference/one-time-token#verify-whatsapp).

The Trigger WhatsApp Challenge 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-Token
Text value of a OTT.

### Response

obfuscatedPhoneNo
Obfuscated phone number that can be used as a hint for the end customer regarding which phone
number the WhatsApp message was sent to.

Example Request

```shell
curl -X POST \
  https://api.sandbox.transferwise.tech/v1/one-time-token/whatsapp/trigger \
  -H 'Authorization: Bearer <your api token>' \
  -H 'One-Time-Token: <one time token>'
```

Example Response

```json
{
  "obfuscatedPhoneNo": "*********8888"
}
```

## Verify WhatsApp Challenge 

**`POST /v1/one-time-token/whatsapp/verify`**

To clear a **WHATSAPP** challenge listed in a OTT.

Notes:

1. User is required have a verified phone number. See [create phone number](/api-reference/user-security#create-phone-number) for more information.
2. [Trigger WhatsApp Challenge](/api-reference/one-time-token#trigger-whatsapp) is required to be called first.
3. Since we won't be sending real WhatsApp message on sandbox, the **OTP Code** will always be **111111**.


The Verify WhatsApp Challenge 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-Token
Text value of a OTT.

Body
otpCode
6 digit OTP code in text format.

### Response

oneTimeTokenProperties
Properties of [OneTimeToken](/api-reference/one-time-token#object).

Example Request

```shell
curl -X POST \
  https://api.sandbox.transferwise.tech/v1/one-time-token/whatsapp/verify \
  -H 'Authorization: Bearer <your api token>' \
  -H 'One-Time-Token: <one time token>' \
  -d '{
    "otpCode": "111111"
  }'
```

Example Response

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

## Trigger Voice Challenge 

**`POST /v1/one-time-token/voice/trigger`**

To trigger a WhatsApp challenge by sending voice message to user verified [phone number](/api-reference/user-security#phone-number) containing a 6 digit one time password (**OTP**).

This **OTP** code can be used to clear a [VOICE](/api-reference/one-time-token#challenge-type) challenge by using the [verify voice endpoint](/api-reference/one-time-token#verify-voice).

The Trigger Voice Challenge 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-Token
Text value of a OTT.

### Response

obfuscatedPhoneNo
Obfuscated phone number that can be used as a hint for the end customer regarding which phone
number the WhatsApp message was sent to.

Example Request

```shell
curl -X POST \
  https://api.sandbox.transferwise.tech/v1/one-time-token/voice/trigger \
  -H 'Authorization: Bearer <your api token>' \
  -H 'One-Time-Token: <one time token>'
```

Example Response

```json
{
  "obfuscatedPhoneNo": "*********8888"
}
```

## Verify Voice Challenge 

**`POST /v1/one-time-token/voice/verify`**

To clear a **VOICE** challenge listed in a OTT.

Notes:

1. User is required have a verified phone number. See [create phone number](/api-reference/user-security#create-phone-number) for more information.
2. [Trigger Voice Challenge](/api-reference/one-time-token#trigger-voice) is required to be called first.
3. Since we won't be sending real voice message on sandbox, the **OTP Code** will always be **111111**.


The Verify Voice Challenge 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-Token
Text value of a OTT.

Body
otpCode
6 digit OTP code in text format.

### Response

oneTimeTokenProperties
Properties of [OneTimeToken](/api-reference/one-time-token#object).

Example Request

```shell
curl -X POST \
  https://api.sandbox.transferwise.tech/v1/one-time-token/voice/verify \
  -H 'Authorization: Bearer <your api token>' \
  -H 'One-Time-Token: <one time token>' \
  -d '{
    "otpCode": "111111"
  }'
```

Example Response

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