Example - FaceMap

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

By following these steps, you can enable secure and convenient authentication for your users while meeting the regulatory requirements for online transactions.

Limitations

  1. Wise only supports the 3D FaceMap Interoperability Between Organizations, which requires integration with FaceTec. This means that your organization must also be a consumer of FaceTec services in order to enable this flow.
  2. This authentication method will only be enabled when requested. Please reach out to your implementation manager for inquiry.

Setting Up

Wise leverages the import functionality of FaceTec when receiving 3D FaceMaps from customers, enabling seamless integration and secure authentication processes.

Image below illustrates the interaction between Frontend, Backend and Wise.

Enrolment Flow

Steps

  1. Frontend makes an HTTP call to enrol FaceMap to your Backend application.

    This is where the customer submits a FaceScan to your application for FaceTec enrolment.

    Take note that you should have a FaceMap after successful enrolment. This will be used in Step (4) for export.
  1. Backend makes an HTTP call to get Wise's FaceTec Public Key to acquire public key required to do a FaceTec export.
Get FaceTec Public Key - Request
curl -X GET https://api.sandbox.transferwise.tech/v1/facetec/public-key \
     -H 'Authorization: Bearer <your api token>'
  1. Wise returns the public key to Backend in plain text. You are encouraged to cache this public key to minimize latency, as it is not subject to frequent rotation.
Get FaceTec Public Key - Response
-----BEGIN PUBLIC KEY-----
Public Key Content
-----END PUBLIC KEY-----

  1. The Backend application will utilize the previously stored FaceMap from Step (1) and the acquired Wise's FaceTec public key from Step (3) as input parameters for the export function provided by FaceTec.

    Upon a successful export, we will possess an encrypted FaceMap that is ready to be transmitted to Wise.

  1. Backend makes an HTTP call to Enrol FaceMap.
Enrol FaceMap - Request
curl -X POST https://api.sandbox.transferwise.tech/v1/users/facemap/enrol \
     -H 'Authorization: Bearer <your api token>' 
     -d '{
        "faceMap": "<encrypted_face_map_in_base64_string>"
     }'

  1. Wise responds with a 204 - No Content status code upon successful enrollment.

    Please note that a 409 - Conflict response indicates that the enrollment already exists and cannot be repeated.

  1. Backend should responds with a successful HTTP status code to customer upon successful enrollment.

Verify Flow

This guide uses retrieving balance account statement as an example.

Image below illustrates the interaction between Frontend, Backend, and Wise.

Verification Flow

Steps

  1. Frontend 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. Frontend 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": "FACE_MAP",
               "viewData": {
                  "attributes": {
                     "userId": 6146956
                  }
               }
            },
            "alternatives": [],
            "required": true,
            "passed": false
         }
      ],
      "validity": 3600,
      "actionType": "BALANCE__GET_STATEMENT",
      "userId": 6146956
   }
}

  1. Frontend makes an HTTP call to Backend to perform a match 3d 3d check.

    Take note that you should have a FaceMap after successful match3d3d. This will be used in Step (8) for export.
  1. Backend makes an HTTP call to get Wise's FaceTec Public Key to acquire public key required to do a FaceTec export.
Get FaceTec Public Key - Request
curl -X GET https://api.sandbox.transferwise.tech/v1/facetec/public-key \
     -H 'Authorization: Bearer <your api token>'
  1. Wise returns the public key to Backend in plain text. You are encouraged to cache this public key to minimize latency, as it is not subject to frequent rotation.
Get FaceTec Public Key - Response
-----BEGIN PUBLIC KEY-----
Public Key Content
-----END PUBLIC KEY-----

  1. The Backend application will utilize the previously stored FaceMap from Step (5) and the acquired Wise's FaceTec public key from Step (7) as input parameters for the export function provided by FaceTec.

    Upon a successful export, we will possess an encrypted FaceMap that is ready to be transmitted to Wise.

  1. Backend makes an HTTP call to Verify FaceMap.
Verify FaceMap - 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>"
    }'
  1. Wise returns one time token properties after a successful FaceMap 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 FaceMap - Response
{
   "oneTimeTokenProperties": {
      "oneTimeToken": "bb676aeb-7c4d-4930-bb55-ab949fd3fd87",
      "challenges": [],
      "validity": 3600,
      "actionType": null,
      "userId": null
   }
}
  1. Backend should respond with a successful HTTP status code to customer upon successful verification.
  1. Frontend 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": "..."
}