> For the complete documentation index, see [llms.txt](https://docs.musepay.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.musepay.io/integration/kyc-api.md).

# KYC API

Integrate standalone merchant KYC — three endpoints, four levels, and what to do for each result.

Standalone KYC verifies your own end users through a MusePay-hosted verification link. Three endpoints cover the whole flow: register the user, get a link, read the result.

## Before you start

1. Contact MusePay to enable the product on your account and confirm the enabled levels, fee currency, and pricing.
2. This product serves API-type agent accounts that do not operate card issuing. If your account has card issuing, use the verification flow of the [Card API](https://docs.musepay.io/integration/card-api.md) instead. Contact MusePay if you are unsure which applies to you.
3. Set up [authentication](https://docs.musepay.io/integration/authentication.md) and [IP whitelisting](https://docs.musepay.io/integration/ip-whitelisting.md), and keep sufficient balance — the verification fee is reserved when the link is created.
4. Confirm your merchant Webhook URL receives `KYC_RESULT`. It is one shared merchant-level URL, not a per-request `notify_url`, so check the impact on your other notifications. These callbacks carry **no RSA signature** — see [KYC webhook](https://docs.musepay.io/integration/webhook/kyc.md).

## Flow

| Step | Call                                                                                                                                                      | Result                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| 1    | [Create Applicant](https://docs.musepay.io/reference/api-reference/kyc-api/create-applicant.md)                                                           | Registers the user under a stable `user_xid` and returns `user_id`. No fee.                                            |
| 2    | [Get Verification Link](https://docs.musepay.io/reference/api-reference/kyc-api/link.md)                                                                  | Starts one chargeable application and returns a hosted `link` and the `fee_order_no`. Pass the link only to that user. |
| 3    | [KYC webhook](https://docs.musepay.io/integration/webhook/kyc.md) or [Query KYC Status](https://docs.musepay.io/reference/api-reference/kyc-api/query.md) | The final result. The webhook pushes it, the query reads it on demand.                                                 |

Opening a link is not the same as being verified. Decide what a user may do at each level yourself.

## Levels

`level_name` is required on every link request. There is no default, and missing or unknown values are rejected. Only enabled levels are available.

| `level_name` | Covers                                          |
| ------------ | ----------------------------------------------- |
| `L1`         | Identity verification, level 1                  |
| `L2`         | Identity verification, level 2                  |
| `L1_AML`     | Level 1 plus AML screening for this application |
| `L2_AML`     | Level 2 plus AML screening for this application |

AML screening covers this application only; it is not ongoing monitoring. Required documents, scope, and price follow your onboarding agreement.

## Results

`kyc_status`, returned by [Query KYC Status](https://docs.musepay.io/reference/api-reference/kyc-api/query.md):

| Status        | Means                                                                          | Your next step                                                                      |
| ------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| `NOT_STARTED` | No application yet.                                                            | Call the link endpoint.                                                             |
| `PROCESSING`  | Waiting for the user to submit, under review, or waiting for more information. | Fee is reserved. Wait, or renew the link if it expired.                             |
| `APPROVED`    | Latest application approved.                                                   | Fee settled. Apply the level to what the user may do.                               |
| `REJECTED`    | Latest application finally rejected.                                           | Fee settled. Read `moderation_comment` and `reject_labels` before the user retries. |
| `EXPIRED`     | The fee order closed after roughly 24 hours; the review may still be running.  | Nothing charged. Query again or contact MusePay.                                    |

A separate field, `kyc_level`, is the highest level the user has already obtained through this product (`0`/`1`/`2`). It rises only on approval and is independent of card-issuing levels.

## Rules that change your code

* **One application per user at a time**, across all levels. Requesting a different level while one is running returns `209002`.
* **Expired or lost link: renew, don't re-apply.** Call the link endpoint again with the same `user_xid` and the same `level_name`. You get a fresh link and the original `fee_order_no`, with no new fee order and no new charge. Changing the level is not renewal.
* **Approval and final rejection are both charged.** Requests for more information are not final: no fee settles and no `KYC_RESULT` is sent.
* **Retry with the same `request_id` within one hour.** Keep business fields identical and regenerate `timestamp`, `nonce`, and `sign` for each attempt. Inside that window a failed or still-running attempt is not re-executed — it comes back as a duplicate-request error, so confirm the original outcome before using a new `request_id`.
* **The callback is unsigned.** Never unlock business operations on an unsigned notification alone: keep your request-to-user association and confirm with a query.
* **Names and types differ between directions.** API responses are `snake_case` with `user_id` and `kyc_level` as strings; the callback is `camelCase` with them as numbers. Normalise before comparing, and match on `requestId` + `userId`.

## Errors

| Code     | Meaning                                                                                            | What to do                                                                            |
| -------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `209002` | Another KYC application is already in progress for this user.                                      | Wait for it to close, or renew the existing link.                                     |
| `209003` | On `POST /v1/kyc/link`: this user is already handled by card-issuing KYC.                          | Use the Card API flow for this user.                                                  |
| `209004` | On `POST /v1/kyc/link`: the user already holds this level or higher.                               | No link and no fee order are created. Skip the application or request a higher level. |
| `209005` | On `POST /v1/kyc/applicant/create`: that email is already used by another user under your account. | Register with a different email.                                                      |

## Relationship to card KYC <a href="#relationship-to-card-kyc" id="relationship-to-card-kyc"></a>

Standalone KYC and card-issuing verification serve different accounts and are mutually exclusive: this product is for API-type agent accounts without card issuing. A user already handled by card-issuing KYC is rejected on the link endpoint with `209003`, without a fee order. User creation and status queries stay available either way, so an eligibility problem surfaces only on the link endpoint. The same `user_xid` under two different merchants identifies two different users.
