# API onboarding merchant (/vi/platform-api/merchant_onboarding)
Mọi yêu cầu trên trang này đều sử dụng Server Secret Token của bạn. Xem [Xác thực](/platform-api#authentication).
Merchant có thể yêu cầu [Chấp nhận thanh toán tại cửa hàng](/in-store), [Thanh toán trực tuyến](/online), hoặc cả hai trong một hồ sơ onboarding. Trang này áp dụng cho mọi tích hợp: Accept SDK, ứng dụng Tapaya Terminal và
Checkout. Dùng trang này để tạo và quản lý merchant qua API thay vì Tapaya Platform UI. Hãy yêu cầu những khả năng thanh toán mà merchant cần. Chỉ riêng việc được phê duyệt cho thanh toán tại cửa hàng không bật được thanh toán trực tuyến.
Việc tạo merchant bằng `POST /integrator/merchant`, hoặc bằng `POST /merchant/auth/register` trong một
[tích hợp Accept SDK](/in-store/integration/backend_integration#merchant-authentication-accept-sdk-integrations),
sẽ tạo tài khoản cho merchant, nhưng merchant không thể xử lý thanh toán thật tại cửa hàng hay trực tuyến cho đến khi hoàn tất onboarding.
Với thanh toán trực tuyến, hãy yêu cầu khả năng Checkout và chờ đơn vị xử lý thanh toán trực tuyến phê duyệt cũng như cổng thanh toán được thiết lập. Merchant tự động xuất hiện trong [cài đặt Checkout](/online/integration/checkout_settings), nơi bạn có thể kiểm tra mức độ sẵn sàng và cấu hình key cùng ví điện tử. Tapaya hỗ trợ nhiều hình thức onboarding; tất cả đều có thể được quản lý từ Tapaya Platform UI và tự động hóa khi phù hợp.
| Quy trình | Khi nào sử dụng | Điểm truy cập API |
| ----------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tapaya Platform UI** | Đội ngũ vận hành của bạn hoàn tất onboarding thay cho merchant. | Tạo hoặc chọn merchant trong Tapaya Platform UI và mở quy trình onboarding do Tapaya lưu trữ tại đó. |
| **Giao diện riêng** | Bạn thu thập và kiểm tra thông tin onboarding trong sản phẩm của mình. | Kiểm tra từng phần bằng `POST /integrator/merchant/onboarding/validate/*`, sau đó gửi bằng `POST /integrator/merchant/onboarding`. Chi tiết bên dưới. |
| **Lời mời qua email** | Một merchant đã biết nhận lời mời dùng một lần để tự onboarding. | Gửi lời mời bằng `POST /integrator/merchant/send-registration-invite`; thêm `merchantToken` để gắn lời mời với một bản ghi merchant cơ bản hiện có, sau đó liệt kê hoặc thu hồi lời mời qua `/integrator/merchant/invites`. |
| **Liên kết chiến dịch** | Nhiều merchant hoặc merchant chưa biết trước dùng một liên kết tự đăng ký có thể dùng lại. | Tạo liên kết bằng `POST /integrator/merchant/reusable-registration-invites`; liệt kê hoặc thu hồi liên kết qua cùng resource đó. |
Để so sánh chi tiết các quy trình này, xem [hướng dẫn Onboarding merchant](/merchants/onboarding).
## Yêu cầu khả năng thanh toán trực tuyến [#request-online-payment-capabilities]
`POST /integrator/merchant/onboarding` yêu cầu `capability`. Dùng cùng giá trị capability khi kiểm tra hồ sơ doanh nghiệp:
| Giá trị | Capability | Thông tin kênh |
| ------- | ---------- | ---------------------------------------------------------------------- |
| `1` | Both | Cung cấp `terminal` và `online`. Mỗi kênh cần được phê duyệt riêng. |
| `2` | Terminals | Cung cấp `terminal` cho thanh toán tại cửa hàng. |
| `3` | Checkout | Cung cấp `online` cho thanh toán trực tuyến. Không cần máy thanh toán. |
Với Checkout, hãy thêm các trường cấp cao nhất sau cùng với dữ liệu danh tính, địa chỉ, `business` dùng chung và dữ liệu KYB của merchant. Các trường kênh tương tự cũng áp dụng cho `POST /integrator/merchant/onboarding/validate/business`:
```json
{
"capability": 3,
"online": {
"mcc": "5411",
"statementDescriptor": "ACME CORP",
"productDescription": "Groceries sold online",
"averageItemValue": 2500,
"expectedMonthlyTurnover": 500000,
"url": "https://www.acme.example.com",
"purchaseChargeTiming": 1,
"averageDeliveryDays": 2,
"topCountries": [{ "countryId": 1, "percentage": 100 }]
}
}
```
Số tiền tính theo đơn vị nhỏ nhất của loại tiền tệ. Website bán hàng trực tuyến phải dùng HTTP hoặc HTTPS và hostname phải chứa `www`. `statementDescriptor` dài từ 5 đến 22 ký tự. `purchaseChargeTiming` là `1` khi đơn hàng được đặt, `2` khi đã giao cho đơn vị vận chuyển, hoặc `3` khi khách đã nhận hàng. `averageDeliveryDays` từ 0 đến 999. Cung cấp từ một đến bốn `topCountries` khác nhau, với tổng tỷ lệ phần trăm bằng 100.
Giữ thông tin hỗ trợ và tài chính dùng chung trong `business`. Ở chế độ phân theo kênh, đặt MCC, statement descriptor, mô tả sản phẩm và ước tính giao dịch vào đối tượng `terminal` hoặc `online` tương ứng. Kiểm tra payload trước khi gửi onboarding và xử lý các lỗi trường theo từng kênh được trả về.
## Mời merchant hoàn tất onboarding do Tapaya lưu trữ [#invite-a-merchant-to-complete-hosted-onboarding]
Dùng quy trình này khi bạn muốn Tapaya lưu trữ biểu mẫu KYB, nhưng bạn vẫn muốn kiểm soát việc tạo merchant từ
backend của mình.
Nếu hệ thống của bạn quản lý định danh merchant được SDK hoặc back-office dùng về sau, trước tiên hãy tạo bản ghi
merchant cơ bản bằng `POST /merchant/auth/register` hoặc `POST /integrator/merchant`, sau đó gọi
`POST /integrator/merchant/send-registration-invite` với cùng `merchantToken`. Cách này giữ cho quy trình onboarding
do Tapaya lưu trữ gắn với merchant đó thay vì tạo thêm một merchant thứ hai.
Trình tự được khuyến nghị là:
1. Tạo bản ghi merchant cơ bản:
* `POST /merchant/auth/register`, hoặc
* `POST /integrator/merchant`
2. Gửi lời mời onboarding do Tapaya lưu trữ bằng `POST /integrator/merchant/send-registration-invite`
3. Chia sẻ `registrationUrl` được trả về với merchant nếu cần, và để họ hoàn tất biểu mẫu do Tapaya lưu trữ
4. Kiểm tra định kỳ mức độ sẵn sàng của merchant qua `GET /integrator/merchant/{merchantId}/status`
**Endpoint:** `POST /integrator/merchant/send-registration-invite`
cURL
```bash
curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/send-registration-invite' \
-H 'Content-Type: application/json' \
-H 'Authorization: REPLACE_ME' \
-d '{
"email": "admin@acme.com",
"merchantToken": "unique_merchant_id_from_your_db"
}'
```
**Tham số:**
| Trường | Kiểu | Bắt buộc | Mô tả |
| --------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email` | `string` | ✓ | Địa chỉ email sẽ nhận liên kết onboarding do Tapaya lưu trữ. |
| `merchantToken` | `string` | | Token của merchant hiện có để gắn lời mời vào. Dùng trường này khi bạn đã tạo bản ghi merchant cơ bản và muốn quy trình onboarding do Tapaya lưu trữ điền thông tin cho chính merchant đó. Nếu bỏ qua, việc hoàn tất lời mời sẽ tạo một merchant mới. |
**Phản hồi:**
| Mã | Mô tả |
| ----- | -------------------------------------------------- |
| `200` | Đã tạo lời mời. Phản hồi bao gồm `registrationUrl` |
| `400` | Lỗi kiểm tra tính hợp lệ của yêu cầu |
| `401` | Không được phép |
| `404` | Không tìm thấy tổ chức hoặc merchant |
| `409` | Xung đột |
**Nội dung phản hồi:**
```json
{
"registrationUrl": "https://platform.tapaya.com/invite-merchant?token=...&merchantToken=unique_merchant_id_from_your_db"
}
```
Tapaya cũng cố gắng gửi liên kết này qua email. Việc gửi email không được đảm bảo, vì vậy hãy luôn coi `registrationUrl`
được trả về là nguồn dữ liệu chuẩn cho giao diện và công cụ hỗ trợ của bạn.
`POST /integrator/merchant/{merchantId}/invite` là một quy trình khác. Quy trình này mời một người dùng nền tảng truy cập vào
tài khoản merchant đã tồn tại. Nó **không** bắt đầu onboarding KYB và không tạo hay cập nhật hồ sơ
merchant.
## Gửi onboarding qua API [#submit-onboarding-through-the-api]
Nếu bạn muốn thu thập thông tin onboarding trong sản phẩm của mình thay vì chuyển merchant sang Tapaya Platform, hãy gửi thông tin trực tiếp. Kiểm tra từng phần khi merchant điền bằng các endpoint `validate/*` bên dưới, sau đó gửi tất cả trong một lệnh gọi; lệnh gọi này tạo merchant cùng hồ sơ onboarding của merchant, đồng thời đăng ký merchant với đơn vị xử lý thanh toán ưu tiên của tổ chức bạn.
Trước khi gửi thông tin onboarding qua API, bạn phải có được sự đồng ý của merchant đối với
[Điều khoản và Điều kiện dành cho bên tích hợp của Tapaya](https://tapaya.com/terms) và
[Chính sách quyền riêng tư của Tapaya](https://tapaya.com/privacy). Thêm một ô đánh dấu vào biểu mẫu onboarding có liên kết đến
cả hai tài liệu, hoặc liên kết đến các tài liệu của Tapaya từ phần nội dung điều khoản mà merchant đồng ý. Bạn cũng phải
liệt kê Tapaya là bên xử lý dữ liệu trong chính sách quyền riêng tư của riêng bạn.
`POST /integrator/merchant/onboarding` tạo merchant **và** gửi onboarding trong một lệnh gọi duy nhất. Nếu
dữ liệu onboarding không hợp lệ, endpoint trả về `422` kèm lỗi theo từng trường và **không có merchant nào được tạo**; không có
merchant onboarding dở dang nào cần dọn dẹp hay tiếp tục.
### Kiểm tra danh tính [#validate-identity]
**Endpoint:** `POST /integrator/merchant/onboarding/validate/identity`
cURL
```bash
curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding/validate/identity' \
-H 'Content-Type: application/json' \
-H 'Authorization: REPLACE_ME' \
-d '{
"legalName": "Acme Corp s.r.o.",
"businessTypeId": 2,
"email": "admin@acme.com",
"registrationNumber": "12345678",
"vatNumber": "CZ12345678",
"incorporationDate": "2018-04-01"
}'
```
**Tham số:**
| Trường | Kiểu | Bắt buộc | Mô tả |
| -------------------- | -------- | -------- | ------------------------------------------------------------------ |
| `legalName` | `string` | ✓ | Tên pháp lý của doanh nghiệp hoặc chủ tài khoản cá nhân. |
| `businessTypeId` | `int` | ✓ | Loại hình pháp nhân kinh doanh (`BusinessTypeEnum`). |
| `email` | `string` | ✓ | Địa chỉ email liên hệ. |
| `registrationNumber` | `string` | ✓ | Mã số đăng ký kinh doanh chính thức. Được kiểm tra trùng lặp trong |
| tổ chức của bạn. | | | |
| `vatNumber` | `string` | | Mã số đăng ký VAT, nếu có. |
| `incorporationDate` | `date` | | Ngày doanh nghiệp được thành lập hợp pháp (`YYYY-MM-DD`). |
**Nội dung phản hồi:**
```json
{
"valid": true,
"errors": []
}
```
Một `registrationNumber` đã được merchant khác trong tổ chức của bạn sử dụng sẽ được trả về dưới dạng lỗi `valid: false`
với `code: "DUPLICATE_REGISTRATION_NUMBER"` thay vì `409`; endpoint này luôn trả về `200`.
### Kiểm tra địa chỉ [#validate-address]
**Endpoint:** `POST /integrator/merchant/onboarding/validate/address`
cURL
```bash
curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding/validate/address' \
-H 'Content-Type: application/json' \
-H 'Authorization: REPLACE_ME' \
-d '{
"line1": "Wenceslas Square 1",
"city": "Prague",
"postalCode": "11000",
"countryId": 1
}'
```
**Tham số:**
| Trường | Kiểu | Bắt buộc | Mô tả |
| ------------ | -------- | -------- | --------------------------------- |
| `line1` | `string` | ✓ | Dòng đầu tiên của địa chỉ. |
| `line2` | `string` | | Dòng thứ hai của địa chỉ, nếu có. |
| `city` | `string` | ✓ | Tên thành phố. |
| `postalCode` | `string` | ✓ | Mã bưu chính hoặc mã ZIP. |
| `state` | `string` | | Bang hoặc khu vực, nếu có. |
| `countryId` | `int` | ✓ | Quốc gia (`CountryEnum`). |
**Nội dung phản hồi:** cùng cấu trúc `{valid, errors}` như [Kiểm tra danh tính](#validate-identity).
### Kiểm tra hồ sơ doanh nghiệp [#validate-business-profile]
**Endpoint:** `POST /integrator/merchant/onboarding/validate/business`
cURL
```bash
curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding/validate/business' \
-H 'Content-Type: application/json' \
-H 'Authorization: REPLACE_ME' \
-d '{
"capability": 2,
"mcc": "5411",
"url": "https://acme.example.com",
"supportPhone": "+420123456789",
"statementDescriptor": "ACME CORP"
}'
```
**Tham số:**
| Trường | Kiểu | Bắt buộc | Mô tả |
| ------------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `capability` | `int` | ✓ | Dùng giá trị capability mà bạn sẽ gửi khi onboarding. Với Checkout hoặc Both, cung cấp [thông tin kênh](#request-online-payment-capabilities). |
| `mcc` | `string` | ✓ | Mã ngành hàng của merchant (Merchant Category Code) gồm bốn chữ số. Ở chế độ phân theo kênh, dùng `terminal.mcc` hoặc `online.mcc`. |
| `url` | `string` | | URL website của doanh nghiệp. Bắt buộc phải có `url` hoặc `productDescription`. |
| `productDescription` | `string` | | Mô tả sản phẩm hoặc dịch vụ. Bắt buộc phải có `url` hoặc |
| `productDescription`. | | | |
| `supportPhone` | `string` | ✓ | Số điện thoại hỗ trợ khách hàng, theo định dạng E.164. |
| `statementDescriptor` | `string` | ✓ | Nội dung hiển thị trên sao kê ngân hàng của khách hàng (1–22 ký tự). |
| `averageItemValue` | `long` | | Giá trị giao dịch trung bình, tính theo đơn vị nhỏ nhất của loại tiền tệ. |
| `expectedMonthlyTurnover` | `long` | | Doanh thu hằng tháng dự kiến, tính theo đơn vị nhỏ nhất của loại tiền tệ. |
| `numberOfEmployees` | `int` | | Số lượng nhân viên của doanh nghiệp. |
| `annualTurnover` | `long` | | Doanh thu hằng năm, tính theo đơn vị nhỏ nhất của loại tiền tệ. |
| `balanceSheetTotal` | `long` | | Tổng giá trị bảng cân đối kế toán, tính theo đơn vị nhỏ nhất của loại tiền tệ. |
**Nội dung phản hồi:** cùng cấu trúc `{valid, errors}` như [Kiểm tra danh tính](#validate-identity).
### Kiểm tra KYB [#validate-kyb]
**Endpoint:** `POST /integrator/merchant/onboarding/validate/kyb`
Cung cấp đúng một trong hai: `individual` (hộ kinh doanh cá thể / người tự kinh doanh) hoặc `company`. Với `company`, liệt kê mọi
chủ sở hữu, giám đốc và người có thẩm quyền ký trong `people`.
cURL
```bash
curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding/validate/kyb' \
-H 'Content-Type: application/json' \
-H 'Authorization: REPLACE_ME' \
-d '{
"businessTypeId": 2,
"bankAccount": {
"iban": "CZ6508000000192000145399",
"bic": "GIBACZPX",
"currencyId": 1,
"beneficiaryName": "Acme Corp s.r.o."
},
"company": {
"name": "Acme Corp s.r.o.",
"registrationNumber": "12345678",
"people": [
{
"email": "jane@acme.com",
"firstName": "Jane",
"lastName": "Doe",
"role": {
"isOwner": true,
"isAuthorizedSignatory": true
}
}
]
}
}'
```
**Tham số:**
| Trường | Kiểu | Bắt buộc | Mô tả |
| ------------------------------------------------------------------------------------ | -------- | -------- | --------------------------------------------------------------------------------------------------- |
| `businessTypeId` | `int` | | Loại hình pháp nhân kinh doanh (`BusinessTypeEnum`); xác định trường `individual` hay |
| `company` là bắt buộc. | | | |
| `bankAccount` | `object` | | Tài khoản ngân hàng nhận chi trả (số tài khoản/IBAN + BIC, loại tiền tệ, người thụ hưởng và địa chỉ |
| ngân hàng). | | | |
| `individual` | `object` | | Thông tin chủ sở hữu cá nhân, dành cho hộ kinh doanh cá thể. Không dùng đồng thời với `company`. |
| `company` | `object` | | Thông tin công ty, bao gồm mảng `people` gồm các chủ sở hữu, giám đốc và người có thẩm quyền |
| ký, cùng với `verificationDocument` tùy chọn. Không dùng đồng thời với `individual`. | | | |
Mỗi người trong `people` (và `individual`) có các cờ `role.isOwner` / `isDirector` / `isRepresentative` /
`isAuthorizedSignatory`, cùng các trường danh tính tùy chọn (`dateOfBirth`, `nationalityCountryId`,
`officialIdType`/`officialIdNumber`, `address`, `ownershipPercentage`, `verificationDocuments`). Mỗi mục người
phải là chỉ mời hoặc đầy đủ thông tin; những người chỉ được điền một phần sẽ bị từ chối. Có hai cách để gửi
thông tin một người:
* **Chỉ mời:** chỉ gửi `email` và một `role`. Người đó nhận được email hướng dẫn tự hoàn tất
thông tin cá nhân và xác minh danh tính trực tiếp, bao gồm tự tải lên giấy tờ tùy thân của mình;
bạn không cần thu thập thêm gì cho họ và không phải tải lên tài liệu nào từ phía bạn.
* **Đầy đủ thông tin:** tự gửi toàn bộ thông tin cá nhân của người đó (họ tên, ngày sinh, giấy tờ tùy thân chính thức, địa chỉ,
v.v.). Trong trường hợp này, bạn cũng phải [tải lên giấy tờ tùy thân](#upload-a-persons-id-document) cho
người đó; việc này là bắt buộc, không phải tùy chọn, đối với mọi người được gửi đầy đủ thông tin.
Tài liệu được tải lên sau khi merchant đã tồn tại, vì [endpoint tải lên
tài liệu](#upload-a-persons-id-document) cần `merchantId` được trả về từ [Tạo merchant kèm
onboarding](#create-merchant-with-onboarding). Tài liệu tải lên của mỗi người được khớp với họ qua
`relatedOfficialIdNumber`. Các trường tùy chọn `verificationDocuments.identityDocument`,
`verificationDocuments.additionalDocument` và `company.verificationDocument` đều nhận một đối tượng
`{frontFileId, backFileId}` và chỉ có thể tham chiếu đến các tệp đã được tải lên, vì vậy hãy bỏ qua chúng khi
tạo merchant mới.
Bất kể có bao nhiêu người ở dạng chỉ mời hay đầy đủ thông tin, bạn luôn phải [tải lên giấy tờ đăng ký/thành lập
của công ty](#upload-the-company-document) trước khi merchant có thể được gửi đi xem xét
KYC.
**Nội dung phản hồi:** cùng cấu trúc `{valid, errors}` như [Kiểm tra danh tính](#validate-identity).
### Tạo merchant kèm onboarding [#create-merchant-with-onboarding]
Gửi toàn bộ dữ liệu từ bốn bước trước trong một lệnh gọi, tạo merchant và đăng ký merchant với đơn vị xử lý thanh toán
ưu tiên của tổ chức bạn.
**Endpoint:** `POST /integrator/merchant/onboarding`
cURL
```bash
curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/onboarding' \
-H 'Content-Type: application/json' \
-H 'Authorization: REPLACE_ME' \
-d '{
"name": "Acme Corp",
"capability": 2,
"merchantToken": "unique_merchant_id_from_your_db",
"identity": {
"legalName": "Acme Corp s.r.o.",
"businessTypeId": 2,
"email": "admin@acme.com",
"registrationNumber": "12345678",
"vatNumber": "CZ12345678"
},
"address": {
"line1": "Wenceslas Square 1",
"city": "Prague",
"postalCode": "11000",
"countryId": 1
},
"business": {
"mcc": "5411",
"url": "https://acme.example.com",
"supportPhone": "+420123456789",
"statementDescriptor": "ACME CORP"
},
"kyb": {
"bankAccount": {
"iban": "CZ6508000000192000145399",
"bic": "GIBACZPX",
"currencyId": 1,
"beneficiaryName": "Acme Corp s.r.o."
},
"company": {
"people": [
{
"email": "jane@acme.com",
"firstName": "Jane",
"lastName": "Doe",
"role": {
"isOwner": true,
"isAuthorizedSignatory": true
}
}
]
}
}
}'
```
**Tham số:**
| Trường | Kiểu | Bắt buộc | Mô tả |
| --------------- | -------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `capability` | `int` | ✓ | `1` cho Both, `2` cho Terminals, hoặc `3` cho Checkout. Xem [khả năng thanh toán trực tuyến](#request-online-payment-capabilities). |
| `terminal` | `object` | Tùy capability | Thông tin kênh terminal cho Terminals hoặc Both. |
| `online` | `object` | Tùy capability | Thông tin kênh trực tuyến cho Checkout hoặc Both. |
| `name` | `string` | ✓ | Tên của merchant. |
| `merchantToken` | `string` | | Một định danh duy nhất, ổn định từ hệ thống của bạn. Nếu không cung cấp, một token ngẫu nhiên sẽ |
| được tạo. | | | |
| `identity` | `object` | ✓ | Cùng cấu trúc như [Kiểm tra danh tính](#validate-identity). |
| `address` | `object` | ✓ | Cùng cấu trúc như [Kiểm tra địa chỉ](#validate-address). |
| `business` | `object` | ✓ | Cùng cấu trúc như [Kiểm tra hồ sơ doanh nghiệp](#validate-business-profile). |
| `kyb` | `object` | ✓ | Cùng cấu trúc như [Kiểm tra KYB](#validate-kyb). |
**Phản hồi:**
| Mã | Mô tả |
| ----- | -------------------------------------------------------------------------- |
| `201` | Đã tạo merchant và gửi onboarding |
| `422` | Dữ liệu onboarding không hợp lệ, xem `errors`; merchant **không** được tạo |
**Nội dung phản hồi (`201`):**
```json
{
"merchantId": "018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e",
"merchantToken": "unique_merchant_id_from_your_db",
"name": "Acme Corp",
"email": "admin@acme.com",
"processors": [
{
"processorId": 5,
"registered": true,
"onboardingUrl": null
}
]
}
```
`onboardingUrl` được điền khi đơn vị xử lý thanh toán yêu cầu merchant hoàn tất thêm một quy trình onboarding
do đơn vị xử lý thanh toán lưu trữ (ví dụ: xác minh danh tính) trước khi có thể xử lý thanh toán thật.
**Nội dung phản hồi (`422`):**
```json
{
"errors": [
{
"step": "identity",
"field": "registrationNumber",
"message": "A merchant with this registration number is already onboarded under this integrator (merchantId: 018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e).",
"code": "DUPLICATE_REGISTRATION_NUMBER"
}
]
}
```
### Tải lên giấy tờ tùy thân của một người [#upload-a-persons-id-document]
Bắt buộc với mọi người được gửi đầy đủ thông tin trong `kyb.company.people` / `kyb.individual` (xem [Kiểm tra
KYB](#validate-kyb)); những người chỉ được mời sẽ tự tải lên qua liên kết được gửi qua email.
**Endpoint:** `POST /integrator/merchant/{merchantId}/document`
Nội dung yêu cầu là `multipart/form-data`, không phải JSON.
cURL
```bash
curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/document' \
-H 'Authorization: REPLACE_ME' \
-F 'paymentProcessorId=5' \
-F 'documentType=2' \
-F 'relatedOfficialIdNumber=123456789' \
-F 'frontFile=@./jane-doe-id-front.jpg' \
-F 'backFile=@./jane-doe-id-back.jpg'
```
**Tham số:**
| Trường | Kiểu | Bắt buộc | Mô tả |
| -------------------------------------------------------------------------------------------------------------------- | --------- | -------- | -------------------------------------------------------------------------------------------------- |
| `paymentProcessorId` | `int` | ✓ | Luôn là `5`. |
| `documentType` | `int` | ✓ | Loại tài liệu (`DocumentTypeEnum`: `1` Other, `2` Id, `3` Address, `4` Company, |
| `5` BankStatement, `6` Passport, `7` RecentFinancials). | | | |
| `frontFile` | `file` | ✓ | Ảnh mặt trước của tài liệu. |
| `backFile` | `file` | | Ảnh mặt sau của tài liệu, nếu có. |
| `relatedOfficialIdNumber` | `string` | | `officialIdNumber` của người đó từ [Kiểm tra KYB](#validate-kyb). |
| Chỉ bắt buộc khi `documentType` gắn với cá nhân (ví dụ: Id, Passport, Address); bị bỏ qua trong các trường hợp khác. | | | |
| `submitMerchant` | `boolean` | | Để trống/`false` ở đây: giấy tờ tùy thân của một người không phải là lần tải lên cuối cùng của lô. |
| Chỉ đặt `true` khi [tải lên tài liệu công ty](#upload-the-company-document) sau khi tài liệu của mọi người đã được | | | |
| tải lên. | | | |
**Nội dung phản hồi (`200`):**
```json
{
"frontFileId": "file_1NqtHo2eZvKYlo2CZPg8Xt5h",
"backFileId": "file_1NqtHp2eZvKYlo2CRTg9Xm3k",
"uploadedAt": "2026-07-17T12:00:00Z"
}
```
### Tải lên tài liệu công ty [#upload-the-company-document]
Bắt buộc đúng một lần cho mỗi merchant. Nếu thông tin cá nhân chưa được điền, người có thẩm quyền ký sẽ có thể
tải tài liệu này lên bằng liên kết trong email onboarding và không cần gọi endpoint này.
**Endpoint:** `POST /integrator/merchant/{merchantId}/document`
Nội dung yêu cầu là `multipart/form-data`, không phải JSON.
cURL
```bash
curl -X 'POST' 'https://api.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/document' \
-H 'Authorization: REPLACE_ME' \
-F 'paymentProcessorId=5' \
-F 'documentType=4' \
-F 'frontFile=@./acme-corp-register-extract.pdf' \
-F 'submitMerchant=true'
```
**Tham số:**
| Trường | Kiểu | Bắt buộc | Mô tả |
| ------------------------------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `paymentProcessorId` | `int` | ✓ | Luôn là `5`. |
| `documentType` | `int` | ✓ | Luôn là `4` (`Company`) cho bước này. |
| `frontFile` | `file` | ✓ | Giấy tờ đăng ký/thành lập của công ty. |
| `submitMerchant` | `boolean` | | Đặt thành `true` để kích hoạt việc xem xét KYC của đơn vị xử lý thanh toán khi mọi tài liệu bắt buộc |
| đã được tải lên. Mặc định là `false`. | | | |
**Nội dung phản hồi (`200`):**
```json
{
"frontFileId": "file_1NqtHo2eZvKYlo2CZPg8Xt5h",
"backFileId": null,
"uploadedAt": "2026-07-17T12:00:00Z"
}
```