> For the complete documentation index, see [llms.txt](https://aliniex.gitbook.io/alix-pay/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://aliniex.gitbook.io/alix-pay/api-reference/card-api/kyc-verification-flow.md).

# KYC Verification Flow

Before a user can issue cards, they must complete identity verification (KYC) through three sequential steps: submitting personal details, uploading identity documents, and submitting the profile for review.

#### Step 1 — Update Personal Details

<mark style="color:orange;">`PUT`</mark> <mark style="color:$info;"><https://api.alixpay.com/></mark>card/v3/profile

Submit the cardholder's basic personal information: first and last name, date of birth, gender, nationality (ISO 3166-1 alpha-2), and full contact details including phone number, address, city, state, and ZIP code.

**Constraints:**

* Full name must not exceed 23 characters.
* Address must not exceed 48 characters.
* This endpoint is blocked if the profile is already under review (`PROFILE_IS_BEING_PROCESSED`) or has been previously verified (`PROFILE_IS_VERIFIED`).

#### Step 2 — Update Identity Document

<mark style="color:orange;">`PUT`</mark> <mark style="color:$info;"><https://api.alixpay.com/></mark>card/v3/profile/document

Provide the user's identity document details and photos. The request must include the document type (`idType`), document number (`nationalId`), issue date, expiry date, and three base64-encoded images: front side, back side, and a selfie holding the document (`holdPhoto`).

**Constraints:**

* All images must be valid base64 strings; invalid encoding returns `INVALID_BASE64`.
* Only the end user may update their own profile — admin tokens are not permitted (`ACCESS_DENIED`).

#### Step 3 — Submit for Review

<mark style="color:$success;">`POST`</mark> <mark style="color:$info;"><https://api.alixpay.com/></mark>card/v3/profile/submit

Once Steps 1 and 2 are complete, submit the profile for KYC review. The system typically processes submissions within **30 minutes**. Upon approval, the user is authorized to create cards.

***

#### Checking KYC Status

<mark style="color:blue;">`GET`</mark> <mark style="color:$info;"><https://api.alixpay.com/></mark>card/v3/profile

Retrieve the full profile, including the `kyc.status` field. The status lifecycle is:

```
NONE → SUBMITTED → UNDER_REVIEW → VERIFIED
                                ↘ REJECTED
```

| Status         | Description                                              |
| -------------- | -------------------------------------------------------- |
| `NONE`         | No submission has been made.                             |
| `SUBMITTED`    | Profile submitted, pending intake.                       |
| `UNDER_REVIEW` | Actively being reviewed.                                 |
| `VERIFIED`     | Verification approved. User may now create cards.        |
| `REJECTED`     | Verification denied. See `kyc.rejectReason` for details. |

***

#### Handling Rejections

When `kyc.status` is `REJECTED`, the `kyc.rejectReason` field returns a structured code in the format:

```
ERROR_CODE | Vietnamese description | English description
```

Rejection codes are grouped by category:

| Category     | Codes                                                                                                                         | Description                                                                                            |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Image**    | `IMG_FRONT_INVALID`, `IMG_BACK_INVALID`, `IMG_SELFIE_INVALID`, `IMG_GLARE_BLUR`, `IMG_CROPPED`, `IMG_LIVENESS_FAILED`         | Photo quality or validity issues.                                                                      |
| **Document** | `DOC_EXPIRED`, `DOC_UNSUPPORTED_TYPE`, `DOC_TAMPERED`, `DOC_SECURITY_FEATURES_MISSING`, `DOC_MISSING_REQUIRED`                | Document integrity or compliance issues.                                                               |
| **Match**    | `MATCH_DOC_INFO_MISMATCH`, `MATCH_FACE_MISMATCH`, `MATCH_MULTIPLE_ACCOUNTS`, `MATCH_BLACKLISTED_ID`, `MATCH_AGE_OUT_OF_RANGE` | Discrepancies between submitted data, document content, and identity checks. Age must be within 18–65. |
| **System**   | `SYS_UPLOAD_CORRUPTED`, `SYS_FORMAT_UNSUPPORTED`, `SYS_EXTRACTION_FAILED`, `SYS_TIMEOUT`                                      | Technical failures during processing.                                                                  |
| **Fraud**    | `FRAUD_DOCUMENT`, `FRAUD_IMPERSONATION`                                                                                       | Fraudulent document or identity detected.                                                              |
| **Generic**  | `GENERIC`                                                                                                                     | Unclassified rejection reason.                                                                         |

On receiving a `REJECTED` status, the client should allow the user to correct their information by re-executing Steps 1 and/or 2, then resubmitting via Step 3.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://aliniex.gitbook.io/alix-pay/api-reference/card-api/kyc-verification-flow.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.