Hosted KYC

Hosted KYC provides you with a way to verify your customers to perform certain actions (money movement) with Wise’s API by embedding Wise's KYC flows into your app. In the embedded flow the end user will go through Wise's KYC process to provide information required for the specific action. The UI of the embedded flow can be customised to look and feel like your UI.

This guide will direct you through the Hosted KYC (Know Your Customer) Flow. Generally, the process for starting a Hosted KYC flow includes following steps:

1. Create a new user, retrieve access token for the user, and create a profile:

   • Retrieve client credentials token by calling the Retrieve Client Credentials endpoint.

   • Create a user for your customer using Create User endpoint.

   • Retrieve access tokens for the user using Retrieve User Tokens endpoint.

   • Create a personal profile for the user Create Personal Profile endpoint.

2. Subscribe to KYC Review state change webhook.

3. Create a transfer by following the Send Money guide.

4. Once a transfer is created, the KYC Review resource is created automatically which is then sent over webhook message with the status either WAITING_CUSTOMER_INPUT or PASSED/PASSED_WITH_REQUIREMENTS. See KYC Review Status for all possible values for KYC Review status can have.

5. If an action is required by the customer for the transfer, KYC Review status will be in WAITING_CUSTOMER_INPUT state. To generate redirect link for Hosted KYC flow to direct the customer to, use Update KYC Review endpoint. This endpoint accepts redirectUrl field that is used to redirect the customer once the Hosted KYC flow is completed. For the full reference, see the KYC Review API reference.

6. Direct your customer to Wise Hosted KYC page using the link received in step 5. Depending on the platform, different integration modes can be used:

   • Web: opening link in a new tab in the browser, redirecting to the link or opening the link in an iframe.
   • Android: embed the page in your app via Custom Tabs.
   • iOS: embed the page in your app via Safari View Controller.

   This page takes the customer through a UI with multiple forms and possibly liveness checks. The customer can also be asked to upload documents like IDs. The exact requirements vary depending on profile country, source currency, target currency, amount being transferred etc. The UI styling can be configured during implementation to a color theme that suits your branding.

   Hosted KYC link expires 5 minutes after generation. When expired, new link can be generated by calling Update KYC Review endpoint again.

7. Once customer provides necessary information on the Hosted KYC flow then the customer is redirected back to the redirectUrl provided in step 5. 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.

8. Customer provided information is reviewed automatically or manually (depending on the information type) by Wise. Based on the review result:

   1. Customer provided information is accepted. Webhook message with PASSED KYC Review status is sent. Customer can proceed with the underlying action that triggered the KYC process ( currently, quote or transfer).

   2. More information is required from the customer. Webhook message with WAITING_CUSTOMER_INPUT KYC Review status is sent. Continue from step 4 to direct the customer to Hosted KYC flow to provide more information.

9. KYC Reviews can be fetched at anytime by calling Get a KYC Review by ID endpoint. This could be particularly helpful to handle unhappy flows, where the hosted journey returned the status=error or if the redirect never happened because the customer closed the hosted journey midway.

Below is a sequence diagram of Hosted KYC flow for transfer.

Collection of requirements from customers can be done proactively using the Hosted KYC flow before transfer is created. In this flow, Quote resource is used to create the KYC Review.

Although completing Hosted KYC flow started with Quote should cover most of the requirements for a customer, further requirements might surface when transfer gets created.

Steps of Hosted KYC flow with Quote:

1. Create a new user, retrieve access token for the user, and create a profile:

   • Retrieve client credentials token by calling the Retrieve Client Credentials endpoint.

   • Create a user for your customer using Create User endpoint.

   • Retrieve access tokens for the user using Retrieve User Tokens endpoint.

   • Create a personal profile for the user Create Personal Profile endpoint.

2. Subscribe to KYC Review state change webhook.

3. Create an authenticated quote that includes source and target currencies and the amount customer wants to transfer. See Create a quote.

4. Start a KYC review by creating KYC Review manually for the Quote created in step 3. by

   using Create KYC Review endpoint.

   Once KYC Review is created, a webhook message with the KYC Review status NEW will be sent confirming the creation of KYC Review. Briefly after another webhook message will be sent with either WAITING_CUSTOMER_INPUT or PASSED/PASSED_WITH_REQUIREMENTS. See KYC Review Status for all possible values for KYC Review status can have.

5. Update the KYC Review when KYC Review status is WAITING_CUSTOMER_INPUT meaning an action is required by the customer. To generate redirect link for Hosted KYC flow to direct the customer to, use Update KYC Review endpoint. This endpoint accepts redirectUrl field that is used to redirect the customer once the Hosted KYC flow is completed. 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. For the full reference, see the KYC Review API reference.

6. Direct your customer to Wise Hosted KYC page using the link received in step 5. Depending on the platform, different integration modes can be used:

   • Web: opening link in a new tab in the browser, redirecting to the link or opening the link in an iframe.
   • Android: embed the page in your app via Custom Tabs.
   • iOS: embed the page in your app via Safari View Controller.

   This page takes the customer through a UI with multiple forms and possibly liveness checks. The customer can also be asked to upload documents like IDs. The exact requirements vary depending on profile country, source currency, target currency, amount being transferred etc. The UI styling can be configured during implementation to a color theme that suits your branding.

7. Once customer provides necessary information on the Hosted KYC flow then the customer is redirected back to the redirectUrl provided in step 5. 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.

8. Customer provided information is reviewed automatically or manually (depending on the information type) by Wise. Based on the review result:

   1. Customer provided information is accepted. Webhook message with PASSED KYC Review status is sent. Customer can proceed with the underlying action that triggered the KYC process ( currently, quote or transfer).

   2. More information is required from the customer. Webhook message with WAITING_CUSTOMER_INPUT KYC Review status is sent. Continue from step 4 to direct the customer to Hosted KYC flow to provide more information.

9. KYC Reviews can be fetched at anytime by calling Get a KYC Review by ID endpoint. This could be particularly helpful to handle unhappy flows, where the hosted journey returned the status=error or if the redirect never happened because the customer closed the hosted journey midway.

Below is a sequence diagram of Hosted KYC flow for Quote.