# Hosted customer onboarding

With Wise-hosted customer onboarding, you direct your customers to a Wise-hosted page branded with your logo and theme colors to collect the required KYC/B data. You don't need to build the verification screens yourself, as Wise handles the collection of all data requirements.

## Hosted flow summary

Once initiated, hosted customer onboarding follows this path:

1. Your system receives a KYC review state change event indicating data is needed for the customer to proceed (requires subscribing to an application webhook).
2. Your system fetches a single-use link which you use to direct the customer to your branded and Wise-hosted onboarding page.
3. Your customer completes the onboarding tasks presented to them.
4. Wise redirects your customer back to your application, indicates if your customer successfully completed the onboarding flow, and sends a KYC review state change event.
5. Wise reviews the customer-provided information and sends a KYC review state change event to indicate the customer has passed or more input is required.


## Hosted onboarding process

Once you have [subscribed to the KYC state change webhook](/guides/product/kyc/wise-kyc/#webhook-for-kyc-state-change-events), you can then initiate onboarding for customer profiles that require it.

For **proactive KYC**, [create a KYC review](/api-reference/kyc-review/kycreviewcreate) before your customer tries to send money. Set the `triggerReferences.​type` field to `PROACTIVE_SEND_MONEY`.
If initiating onboarding when the customer sends money, the first request to create a transfer automatically creates a KYC review resource.

The rest of the process is the same whether doing proactive KYC or initiating on the customer’s first transfer.

### Step 1: Check KYC review status

Check the `data.resource.state` field of the KYC review state change event payload. When the status is `WAITING_CUSTOMER_INPUT`, you can then fetch the hosted onboarding link.

### Step 2: Fetch hosted onboarding link

Request the link for the hosted onboarding flow using the [update KYC review to get a hosted KYC link endpoint](/api-reference/kyc-review/kycreviewredirecturlupdate).

**Endpoint**: `PATCH /v1/profiles/{profileId}/kyc-reviews/{kycReviewId}`

- Use the `data.resource.id` value received in the state change event payload as the `{kycReviewId}` path parameter.
- The `redirectUrl` in the request body is the URL your customer should be redirected to once completing the KYC flow.



```
curl -L -X PATCH \
  'https://api.wise.com/v1/profiles/{profileId}/kyc-reviews/{kycReviewId}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <USER_ACCESS_TOKEN>' \
  -d '{
    "redirectUrl": "https://example.com"
  }'
```

The response provides a short-lived, single-use link to direct the customer to your branded and Wise-hosted onboarding page. The link currently **expires after 5 minutes** and can only be used once. Use the `expiredAt` field from the response as the source of truth for the exact expiry time.

If the link expires or has already been used, you must fetch a new link before redirecting the customer. To get a new link, make another request to the [Update KYC Review](/api-reference/kyc-review#update-redirect-url) endpoint.

### Step 3: Direct customer to the hosted page

Direct your customer to the URL received in the `link.value` field of the response. How you implement this depends on the platform your customer is using:

* **Web**: Open the link in a new browser tab or redirect the customer to the link.
* **Android**: Embed the page within your app using [Custom Tabs](https://developer.chrome.com/docs/android/custom-tabs).
* **iOS**: Embed the page within your app using [Safari View Controller](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller).


The hosted page guides the customer through multiple forms to gather the required details. Customers may be asked to perform “liveness checks” and upload documents, like images of government-issued IDs.

Requirements vary!
The exact requirements for a specific customer will vary based on multiple factors, including the customer type and country of residence. If KYC is initiated on the customer’s first transfer action, other factors like source currency, target currency, and transfer amount can also impact KYC requirements.

Once the customer provides all necessary information, Wise redirects them back to your application using the `redirectUrl` you provided.

### Step 4: Completing hosted onboarding

Upon redirecting the customer back to your application, Wise appends a query parameter to the URL to indicate success:

- `status=success`: The data submission has been completed successfully.
- `status=error`: The data submission failed. While this is a rare occurrence, the URL query parameter lets you track which customers did not complete their onboarding steps. Should this occur, contact Wise for assistance.


If all requirements have been submitted successfully, you also receive a KYC review status change event with the status `PROCESSING`. Wise will then review the submission.

### Step 5: Monitor review state change events

Wise reviews the information provided by the customer and determines if the information is sufficient to pass the KYC review, or if more information is required.

- **Information accepted**: If the customer's information is accepted, you receive a status change event with a `PASSED` KYC review status. The customer can then proceed with the action that initiated the onboarding process (for example, a transfer).
- **More information required**: If more information is needed from the customer, you receive a status change event with a `WAITING_CUSTOMER_INPUT` KYC review status. The requirements outstanding or rejected will have a status of `NOT_PROVIDED`.
  - If rejected, the requirement object will include a `reasons` object with a description. Direct the customer back to the hosted onboarding flow, with a new redirect link, so they can resubmit or provide the additional information (the hosted flow will surface the reason to the customer so they understand what happened and what they need to do to submit successfully).


## KYC review statuses

KYC review statuses and what they mean:

| Status  | Description |
|  --- | --- |
| `NEW` | KYC review has been newly created and requirements are being determined. When you create a KYC review resource, this is the first status the resource will be in and the response will not include a `link` or `requirements` object. KYC Review will be in this state for, at most, a few seconds, and then will move to `WAITING_CUSTOMER_INPUT`. |
| `WAITING_CUSTOMER_INPUT` | The customer needs to provide some KYC information before they can perform any transactions. KYC review also returns to this status if the Wise review determines more data is required or rejects some piece of submitted data. |
| `PROCESSING` | Wise has received the submitted data and is reviewing it. KYC review will be in this state for, at most, a few seconds when processing is done automatically. However, when manual review is required the review will be in this state a bit longer, for example, when a provided document needs to be reviewed manually. |
| `PASSED` | No further customer action is required, and the initiating action can proceed. |
| `PASSED_WITH_REQUIREMENTS` | The initiating action can proceed, but additional non-blocking requirements must be completed by the customer. |
| `EXPIRED` | Signals that a KYC review can no longer be actioned. Occurs if a KYC review is initiated by a quote and that quote has expired. A new quote then needs to be created. |