Example - Device Fingerprint

This is a walkthrough of how to use Device Fingerprint as an authentication method for SCA including setting it up for your end customers.

Please note that all related endpoints use Jose direct encryption for secure data encryption in transit. It is essential to never persist this sensitive data in your application and only retrieve it directly from the customer

Setting Up

Create Device Fingerprint API allow customers to setup their device fingerprint with Wise directly.

This will allow customers to send their device fingerprint to Wise in a direct encrypted manner to Wise and be used as an authentication method in the future.

Please be aware that Wise allows up to three device fingerprints to be registered at any given time. If you have more than three devices connected to your account, you will need to delete unused device fingerprints using our deletion API.

Verify Flow

Once an end customer's device fingerprint is set up. It can now be used as an authentication factor to clear an SCA challenge.

Image below illustrates the interaction between Partner and Wise.

Device Fingerprint Verification Flow

Steps

  1. Partner makes an HTTP call to get balance account statement which is a SCA protected endpoint.
Get Balance Account Statement - Request
curl -X GET https://api.sandbox.transferwise.tech/v1/profiles/{{profileId}}/balance-statements/{{balanceId}}/statement.json \
      ?currency=EUR \
      &intervalStart=2023-01-01T00:00:00.000Z \
      &intervalEnd=2023-01-15T23:59:59.999Z \
      &type=COMPACT \
      -H 'Authorization: Bearer <your api token>'
  1. Wise rejects the request with status 403 Forbidden. Please see the example response on the right.
Get Balance Account Statement - Response
HTTP/1.1 403 Forbidden
Date: Wed, 06 Dec 2023 08:57:34 GMT
x-2fa-approval: bb676aeb-7c4d-4930-bb55-ab949fd3fd87
x-2fa-approval-result: REJECTED
...other headers
  1. Partner gets status of a one time token to get all required challenges to clear this OTT.
Get Status of One Time Token - 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: bb676aeb-7c4d-4930-bb55-ab949fd3fd87'

  1. Wise returns one time token that describes all required challenges.

    For the complete list of challenges available please refer to ChallengeType.

Get Status of One Time Token - Response
{
  "oneTimeTokenProperties": {
    "oneTimeToken": "bb676aeb-7c4d-4930-bb55-ab949fd3fd87",
    "challenges": [
      {
        "primaryChallenge": {
          "type": "PARTNER_DEVICE_FINGERPRINT",
          "viewData": {
            "attributes": {
              "userId": 6146956
            }
          }
        },
        "alternatives": [],
        "required": true,
        "passed": false
      }
    ],
    "validity": 3600,
    "actionType": "BALANCE__GET_STATEMENT",
    "userId": 6146956
  }
}
  1. Partner verify device fingerprint by passing OTT acquired in step 2.
Verify Device Fingerprint - Request
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...'
  1. Wise returns one time token properties after successful verification.

    • Assuming that the challenges array field is empty, indicating that the OTT is now usable.

    • If you are unsure, you can always get status of a one time token again.

    • It is possible that the challenges array returns type of challenge. In that case, please perform the verification flow as written in our guides.

Verify Device Fingerprint - Response
eyJlbmMiOiJBMjU2R0NNIiwi...
  1. Partner calls Get Balance Statement with the approved OTT.
Get Balance Account Statement - Request
curl -X GET https://api.sandbox.transferwise.tech/v1/profiles/{{profileId}}/balance-statements/{{balanceId}}/statement.json \
         ?currency=EUR \
         &intervalStart=2023-01-01T00:00:00.000Z \
         &intervalEnd=2023-01-15T23:59:59.999Z \
         &type=COMPACT \
     -H 'Authorization: Bearer <your api token>' \
     -H 'x-2fa-approval: bb676aeb-7c4d-4930-bb55-ab949fd3fd87'
  1. Wise returns Balance Account Statement.
Get Balance Account Statement - Response
{
   "accountHolder": {
      "type": "PERSONAL",
      "address": {
         "addressFirstLine": "Veerenni 24",
         "city": "Tallinn",
         "postCode": "12112",
         "stateCode": "",
         "countryName": "Estonia"
      },
      "firstName": "Oliver",
      "lastName": "Wilson"
   },
   "otherFields": "..."
}