KYC Review

The Hosted KYC API provides a basic state of KYC requirements for given actions, and an action-specific link to Hosted KYC solution where partners can redirect their customers in order to go through KYC requirements collection in a dynamic manner with minimal configurable styling.

Please refer to our Hosted KYC guide for more information on the general use of the endpoints included below.

Endpoints

The KYC Review resource

Fields

iduuid

Unique identifier for a KYC Review resource, generated by Wise.

statustext

Aggregated state of the underlying requirement set. Any of the states below could move into any other state. Can be one of "NEW", "PASSED", "PASSED_WITH_REQUIREMENTS", "WAITING_CUSTOMER_INPUT" or "PROCESSING".

linkobject

Contains the URL and expiry of said URL the end customer needs to be directed to in order to go through Hosted KYC flow. link is returned only when status is WAITING_CUSTOMER_INPUT and Update redirect url is called.

link.valuetext

The URL that the end customer needs to be directed to in order to go through the Hosted KYC flow.

link.expiresAtdatetime

Timestamp to when the One Time Token in the link will expire after which a new link needs to be generated.

createdAtdatetime

Timestamp marking the creation of the KYC Review.

updatedAtdatetime

Timestamp marking the last update of the KYC Review.

requiredBydatetime

Timestamp by which the underlying requirement set needs to be verified to not block the customer. Only relevant if the status is "PASSED_WITH_REQUIREMENTS".

triggerReferenceobject

Object containing a reference to the action/process this KYC Review is about.

triggerReference.typestring

Type of the underlying action/process this KYC Review is for. Usually a reference to which product this KYC Review is for (like "QUOTE" or "TRANSFER") or a reference to a KYC process on the profile that isn’t related to a specific product (like "REFRESH_CYCLE" or "REPAPERING"). Currently only type QUOTE is supported.

triggerReference.triggerDataobject

Object containing data of the underlying product object that triggered the KYC Review.

triggerReference.triggerData.iduuid

Field containing the ID of the underlying product object. e.g. if type is "TRANSFER" then this would be transfer ID. This ID might be null if underlying action is a single resource without an ID.

redirectUrltext

URL where the user will be redirected at the end of the flow. Can contain query params and path fragments. It has to be a valid URL as per RFC2396. Provided by the caller in the Update redirect url call.

Standard KYC Review Object

{
  "id": "46e1a5c4-4a9b-4563-39d3-18174d3ac0f8",
  "createdAt": "2024-09-03T16:22:02.257725",
  "updatedAt": "2024-09-03T16:29:41.147522",
  "requiredBy": "2024-09-03T16:22:02.257725",
  "status": "WAITING_CUSTOMER_INPUT",
  "link": {
    "value": "https://sandbox.transferwise.tech/embedded-flows/verification?token=d7332edb-25bf-41af-a4e9-09f5efe39ded&checkId=3120073",
    "expiresAt": "2024-09-03T16:29:41.203225146"
  },
  "triggerReference": {
    "type": "QUOTE",
    "triggerData": {
      "id": "ba83s43a-f623-46f0-956d-196c13e2ab01"
    }
  },
  "redirectUrl": "https://example.com"
}

Create KYC Review

POST /v1/profiles/{profileId}/kyc-reviews

Creates a KYC Review for a specific customer action

Request Fields

typestring

triggerDataobject

Object containing data of the underlying product object that triggered the KYC Review.

iduuid

Field containing the ID of the underlying product object. e.g. if type is "QUOTE" then this would be quote ID. This ID might be null when referencing an ID isn’t meaningful. As an example, there’s only ever one active refresh cycle per profile so referencing by ID isn’t useful.

Response

Possible HTTP status codes

202 - Accepted

KYC Review successfully created.

400 - Bad Request

Invalid request. (e.g. unsupported type, null type)

401 - Unauthorized

User is not authorized to access the resource

404 - Not Found

Underlying action with provided ID is not found. (e.g. Quote not found)

Example Request

curl -L 'https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/kyc-reviews' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <user access token>' \
-d '{
    "type": "QUOTE",
    "triggerData": {
        "id": "{quoteId}"
    }
}'

Example Response

{
  "id": "46e1a5c4-4a9b-4563-39d3-18174d3ac0f8",
  "createdAt": "2024-09-03T16:22:02.257725",
  "updatedAt": "2024-09-03T16:22:02.257725",
  "requiredBy": "2024-09-03T16:22:02.257725",
  "status": "NEW",
  "triggerReference": {
    "type": "QUOTE",
    "triggerData": {
      "id": "ba83s43a-f623-46f0-956d-196c13e2ab01"
    }
  },
  "redirectUrl": null
}

Get all KYC Reviews for a profile

GET /v1/profiles/{profileId}/kyc-reviews

Retrieves list of all active KYC Reviews for a given profile.

Response

Possible HTTP status codes

200 - OK

Return list of KYC Review objects for the profile. Returns empty list if no KYC Review exists for a profile

401 - Unauthorized

User is not authorized to access the resource

Example Request

curl -L 'https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/kyc-reviews' \
-H 'Authorization: Bearer <user access token>'

Example Response

[
  {
    "id": "46e1a5c4-4a9b-4563-39d3-18174d3ac0f8",
    "createdAt": "2024-09-03T16:22:02.257725",
    "updatedAt": "2024-09-03T16:24:21.065068",
    "requiredBy": "2024-09-03T16:22:02.257725",
    "status": "WAITING_CUSTOMER_INPUT",
    "triggerReference": {
      "type": "QUOTE",
      "triggerData": {
        "id": "ba83s43a-f623-46f0-956d-196c13e2ab01"
      }
    },
    "redirectUrl": null
  }
]

Get a KYC Review by ID

GET /v1/profiles/{profileId}/kyc-reviews/{kycReviewId}

Retrieves a single KYC Review by ID for a profile

Response

Possible HTTP status codes

200 - OK

Returns KYC Review object

404 - Not Found

KYC Review not found

401 - Unauthorized

User is not authorized to access the resource

Example Request

curl -L 'https://api.sandbox.transferwise.tech/v1/profiles/{profileId}/kyc-reviews/{kycReviewId}' \
-H 'Authorization: Bearer <user access token>'

Update KYC Review with a redirect url

PATCH /v1/profiles/{profileId}/kyc-reviews/{kycReviewId}

Updates KYC Review with redirect url.

Returns KYC Review object with link field containing url where the end customer needs to be directed to in order to go through the Hosted KYC flow. Once Hosted KYC flow is completed by the end customer, they will be redirected to the redirectUrl provided in this API call. During the redirection, the redirectUrl will be appended with query parameters: status=success or status=error, indicating whether Hosted KYC flow was completed successfully or not.

Request Fields

redirectUrlstring

URL where the user will be redirected at the end of the flow. Can contain query params and path fragments. It has to be a valid URL as per RFC2396.

Response

Possible HTTP status codes

200 - OK

Returns updated KYC Review object

400 - Bad Request

Invalid request. (e.g. not valid URI)

401 - Unauthorized

User is not authorized to access the resource

404 - Not Found

KYC Review not found

Example Request

curl -L -X PATCH 'https://api.sandbox.transferwise.tech/v1/profiles/{personalProfileId}/kyc-reviews/{kycReviewId}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <user access token>' \
-d '{
    "redirectUrl": "https://example.com"
}'

Example Response

{
  "id": "46e1a5c4-4a9b-4563-39d3-18174d3ac0f8",
  "createdAt": "2024-09-03T16:22:02.257725",
  "updatedAt": "2024-09-03T16:29:41.147522",
  "requiredBy": "2024-09-03T16:22:02.257725",
  "status": "WAITING_CUSTOMER_INPUT",
  "link": {
    "value": "https://sandbox.transferwise.tech/embedded-flows/verification?token=d7332edb-25bf-41af-a4e9-09f5efe39ded&checkId=3120073",
    "expiresAt": "2024-09-03T16:29:41.203225146"
  },
  "triggerReference": {
    "type": "QUOTE",
    "triggerData": {
      "id": "ba83s43a-f623-46f0-956d-196c13e2ab01"
    }
  },
  "redirectUrl": "https://example.com"
}