> 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

End-to-end integration workflow and business rules for standalone merchant KYC.

{% hint style="warning" %}
**Not yet released (documentation preview)**: KYC OpenAPI has not been released to production. This documentation is for integration planning only; API definitions and business rules may change before release. Do not use it for production workloads. Contact MusePay to confirm test availability and access arrangements. Production availability will be announced separately.
{% endhint %}

## Prerequisites

1. Contact MusePay to enable standalone merchant KYC and confirm the target environment, available verification levels, fee currency, and pricing. Test access does not imply production access.
2. Confirm your account is eligible for this product. It is available only to API-type agent accounts that do not operate card issuing. An account with an active card-issuing product is not eligible, and link generation is rejected for its users; verify through the [Card API](/integration/card-api.md) workflow instead. Contact MusePay if you are unsure which account type applies to you. See [Relationship to card KYC](#relationship-to-card-kyc).
3. Set up [authentication](/integration/authentication.md) and [IP whitelisting](/integration/ip-whitelisting.md). Prepare your merchant API credentials and sufficient available balance.
4. Confirm that your merchant Webhook URL is enabled and can receive `KYC_RESULT`. This is a shared merchant-level setting, not a URL supplied with each link request. Check the impact on other business notifications before changing it.
5. Read the [KYC webhook security guidance](/integration/webhook/kyc.md): these callbacks do not carry an RSA signature.

## Integration workflow

1. Assign each user a stable `user_xid` unique within your merchant account and call [Create Applicant](/reference/api-reference/kyc-api/create-applicant.md). Save the returned `user_id`.
2. Generate a new `request_id` for each new verification and call [Get Verification Link](/reference/api-reference/kyc-api/link.md). Save the association between `request_id`, `user_xid`, `user_id`, and `fee_order_no`.
3. Present the returned `link` to the corresponding user, who should open it promptly and submit the required information. Successful user creation or link generation does not mean verification is complete. Generating a link alone also does not immediately create an applicant at the verification provider.
4. Receive the [KYC Merchant Webhook](/integration/webhook/kyc.md) and use [Query KYC Status](/reference/api-reference/kyc-api/query.md) to check the user's current status. You can also query to track progress proactively.
5. Apply your own compliance policy before allowing subsequent business operations. Successful link generation does not mean verification has passed.

## Verification levels

`level_name` is required and must be one of the following four canonical values, not the provider's dashboard level names. Only enabled levels are available. Missing, blank, or unknown values are rejected; there is no default tier. Each tier maps to a separate fee product, and each application creates only one fee order.

| Value    | Meaning                                                                 |
| -------- | ----------------------------------------------------------------------- |
| `L1`     | Level 1 identity verification.                                          |
| `L2`     | Level 2 identity verification.                                          |
| `L1_AML` | Level 1 identity verification with AML screening for this verification. |
| `L2_AML` | Level 2 identity verification with AML screening for this verification. |

AML levels do not include a commitment to ongoing monitoring. Required documents, verification scope, and fees are subject to your onboarding agreement. The response field `kyc_level` is the highest verification level the user has obtained through this product (`0`/`1`/`2`); it only increases after approval and does not prove that a particular AML screening has completed.

## Fees and in-progress requests

* Creating a user and querying status do not incur this product's verification fee. Requesting a link creates a fee order and reserves the applicable amount.
* **Both approval and final rejection settle the verification fee.** Requests for additional information or retryable rejection are not final results; the fee is not settled and no final-result callback is sent at that stage.
* Only one verification order may be in progress for the same merchant and user across all levels. Do not change levels or `request_id` to bypass an existing in-progress order.
* By default, a scheduled task initiates closure of an unfinished fee order and release of reserved funds once the order is 24 hours old; this is not exact to the second. This deadline is neither the link validity period nor a review turnaround commitment. Timeout closure does not send `KYC_RESULT` or cancel the provider's review. Contact MusePay if a review remains pending beyond the deadline or a late result arrives; the user's current level does not prove that the fee order completed.
* After the original order completes or closes, another application is a new chargeable request. Upgrades, downgrades, same-level re-verification, and applications by already-verified users are not automatically free.
* If link generation fails, the system initiates closure of the corresponding fee order and release of reserved funds. This is not instantaneous. An expired or invalid link is normal: renew it by calling the link endpoint again with the same `user_xid` and level. Contact MusePay if the outcome is unclear, funds have not been released, or renewal misbehaves; do not repeatedly create new applications.

## Retries and correlation

A successful link response can be replayed with the same `request_id` within the 1-hour deduplication window. Keep business fields unchanged and regenerate the common `timestamp`, `nonce`, and `sign` fields. Replaying returns the original link and does not extend its validity.

An in-progress or failed request may return a duplicate-request error. A timeout does not prove that the original request was not accepted. Confirm the outcome of the original request and fee order before deciding whether to apply with a new `request_id`. Do not rely on replay after the deduplication window; persist the order association in your own system.

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

Standalone merchant KYC and card-issuing verification are **mutually exclusive per agent account**. An account with an active card-issuing product is not eligible for this product: `POST /v1/kyc/link` is rejected for its users, and no fee order is created. Existing card integrations should continue using the verification workflow of the [Card API](/integration/card-api.md), which remains the authority on card onboarding, levels, and fees. Standalone KYC does not enable card issuing.

The eligibility check runs only on `POST /v1/kyc/link`. [Create Applicant](/reference/api-reference/kyc-api/create-applicant.md) and [Query KYC Status](/reference/api-reference/kyc-api/query.md) stay available regardless, so an ineligible account sees user creation and queries succeed while link generation fails. Diagnose on the link endpoint.

Independently of eligibility, a new standalone application is rejected with `209003` while a card-issuing verification for the same user is still in progress. This guard applies in this direction only; it does not block a card application while a standalone one is running. Wait for the in-progress application to complete or close.

Identical `user_xid` values under different merchants do not identify the same user.