KYC Review

KYC Review API provides endpoints to view, update and submit information related to KYC flow. Partners redirect their customers in order to go through KYC requirements collection in a dynamic manner with minimal configurable styling if Hosted KYC is the preferred solution to provide KYC requirements.

Alternatively KYC Requirement Submit endpoint can be used for the KYC requirements that are allowed to be submitted. For the requirements that can't be submitted through this endpoint, partner should redirect their customer to Hosted KYC flow.

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

triggerReferenceslist of TriggerReference object

List containing TriggerReference objects

TriggerReferenceobject

An object refers to the action/process this KYC Review pertains to.

triggerReference.typestring

Type of the underlying action/process this KYC Review is for. Usually a reference to which product this KYC Review pertains to (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"). The supported types are "QUOTE", "TRANSFER", "PROACTIVE_SEND_MONEY", "CARD" and "BANK_ACCOUNT_DETAILS"

triggerReference.triggerDataobject

Key-value Object containing metadata of the underlying product object that triggered the KYC Review. For "QUOTE" and "TRANSFER" types, triggerData contains an"id" field that refers to their respective IDs. For "BANK_ACCOUNT_DETAILS", triggerData has a field called "currencies" which contains a list of currencies (i.e USD, SGD, EUR) that the bank details have been created for. Table below shows the fields and their data type for each triggerReference type:

triggerReference.type	field	type
QUOTE	id	uuid
TRANSFER	id	long
BANK_ACCOUNT_DETAILS	currencies	list of string

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.

requirementslist of KYCRequirement object

Nested list of KYC Requirement objects. It will be in [List<KycRequirement>, List<KycRequirement>] format with each List<KYCRequirement> represents a combination of possible KycRequirements to be provided. To fulfil the whole KYC Review, at least one item from each List<KYCRequirement> should be provided.

For an example if the requirements are [ [a, b], [c, d] ] then it should be read as (a or b) and (c or d) to be provided. This field is only included in the response above v2 of KYC Review endpoints.

KYC Requirementobject

The list of requirements of the KYC Review.

requirements[n].keystring

The name of the KYC requirement. A single KYC Requirement should appear in requirements list at most once.

requirements[n].statestring

The state of the KYCRequirement. There are 2 state of a requirement "NOT_PROVIDED" or "IN_REVIEW". If the state is "NOT_PROVIDED" the information is pending some information to be provided. Either the Hosted KYC flow or KYC Requirement Submit endpoint should be used to fulfill the requirement. If the state is "IN_REVIEW" the required information are retrieved and the KYC requirement is being reviewed, no action is needed.

requirements[n].apiCollectionSupportedboolean

A boolean field that indicates if the requirement can be provided via KYC Requirement Submit endpoint. If this field is false the requirement should be provided via Hosted KYC flow.

TriggerReference Object example

{
  "type": "QUOTE",
  "triggerData": {
    "id": "ba83s43a-f623-46f0-956d-196c13e2ab01"
  }
}

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"
  },
  "triggerReferences": [
    {
      "type": "QUOTE",
      "triggerData": {
        "id": "ba83s43a-f623-46f0-956d-196c13e2ab01"
      }
    },
    {
      "type": "TRANSFER",
      "triggerData": {
        "id": "471147"
      }
    }],   
  "redirectUrl": "https://example.com",
  "requirements": [
    [
      [
        {
          "key": "BUSINESS_USE_CASE",
          "state": "NOT_PROVIDED",
          "apiCollectionSupported": true
        }
      ],
      [
        {
          "key": "BUSINESS_MONTHLY_VOLUME",
          "state": "NOT_PROVIDED",
          "apiCollectionSupported": false
        }
      ],
      [
        {
          "key": "BUSINESS_REGISTRATION_DOCS",
          "state": "IN_REVIEW",
          "apiCollectionSupported": false
        }
      ]
    ]
  ]
}

Create KYC Review

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

Creates a KYC Review for a specific customer action

Request Fields

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").

Supported types:

QUOTE
PROACTIVE_SEND_MONEY

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",
  "triggerReferences": [{
    "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.

The following parameters are optional:

pageNumber - Page number. Default value is 1 if not specified
pageSize - Desired number of items per page. Max 100, and default value is 100 if not specified

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?pageNumber=10&pageSize=2' \
-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",
    "triggerReferences": [
    {
      "type": "QUOTE",
      "triggerData": {
        "id": "ba83s43a-f623-46f0-956d-196c13e2ab01"
      }
    },
    {
      "type": "TRANSFER",
      "triggerData": {
        "id": "471147"
      }
    }],
    "redirectUrl": null
  }
]

Get KYC Review by ID

GET /v2/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/v2/profiles/{profileId}/kyc-reviews/{kycReviewId}' \
-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",
    "triggerReferences": [
    {
      "type": "QUOTE",
      "triggerData": {
        "id": "ba83s43a-f623-46f0-956d-196c13e2ab01"
      }
    },
    {
      "type": "TRANSFER",
      "triggerData": {
        "id": "471147"
      }
    }],
    "redirectUrl": null,
    "requirements": [
      [
        [
          {
            "key": "BUSINESS_USE_CASE",
            "state": "NOT_PROVIDED",
            "apiCollectionSupported": true
          }
        ],
        [
          {
            "key": "BUSINESS_MONTHLY_VOLUME",
            "state": "NOT_PROVIDED",
            "apiCollectionSupported": false
          }
        ],
        [
          {
            "key": "BUSINESS_REGISTRATION_DOCS",
            "state": "IN_REVIEW",
            "apiCollectionSupported": false
          }
        ]
      ]
    ]
  }
]

Update KYC review to get a hosted KYC link

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

Updates the KYC review with a redirect url.

Returns KYC review object with a link field containing a url where the end customer needs to be directed in order to complete 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"
  },
  "triggerReferences": [{
    "type": "QUOTE",
    "triggerData": {
      "id": "ba83s43a-f623-46f0-956d-196c13e2ab01"
    }
  }],
  "redirectUrl": "https://example.com"
}

Submit a KYC Requirement for a KYC Review

POST /v2/profiles/{profileId}/kyc-reviews/{kycReviewId}/requirements/{requirementKey}

Submit a KYC requirement under a KYC review.

Please note that a KYC requirement can be only submitted if the KYC Review status is WAITING_CUSTOMER_INPUT.
KYC requirement should only be submitted if the status is "NOT_PROVIDED" and apiCollectionSupported field is true.

Response

Possible HTTP status codes

202 - ACCEPTED

No response

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 or provided requirement key not found

Example Request

curl -X POST 'https://api.sandbox.transferwise.tech/v2/profiles/{profileId}/{kycReviewId}/requirements/{requirementKey}' \
-H 'Authorization: Bearer <your api token>' \
-H 'Content-Type: multipart/form-data'  \
-F 'files=@"<your file>"' \
-F 'submissionData="<payload for the key>";type=application/json'