# Quản lý merchant (/vi/platform-api/merchant_management)
Quản lý các merchant trong tổ chức của bạn từ backend. Mọi lệnh gọi đều dùng Server Secret Token, vì vậy hãy giữ token này trên máy chủ của bạn.
| Thông tin | Giá trị |
| ------------------- | ------------------------------------------------------------------------------------------------- |
| Base URL | `https://api.sandbox.tapaya.com` cho sandbox, `https://api.tapaya.com` cho production |
| Xác thực | Server Secret Token trong `Authorization`. Xem [Xác thực](/platform-api#authentication). |
| Số tiền | Đơn vị nhỏ nhất: `2500` với `EUR` là 25,00 EUR. Phí tương đối tính theo điểm cơ bản: `100` là 1%. |
| Hướng dẫn liên quan | [Onboarding merchant](/platform-api/merchant_onboarding) |
## Tất cả thao tác [#all-operations]
| Thao tác | Dùng để |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| [Đọc onboarding đã lưu](#read-a-saved-onboarding) | Tiếp tục biểu mẫu onboarding của merchant từ chỗ họ đã dừng. |
| [Lưu lựa chọn kênh](#save-channel-selections) | Lưu các kênh thanh toán merchant đã chọn mà không nộp hồ sơ. |
| [Liệt kê thành viên](#list-members) | Xem ai đã có quyền truy cập vào một merchant. |
| [Liệt kê máy thanh toán](#list-terminals) | Hiển thị các máy thanh toán của merchant và thiết bị của chúng. |
| [Liệt kê lời mời qua email](#list-email-invites) | Theo dõi các lời mời dùng một lần đã gửi cho người nhận đã biết. |
| [Liệt kê liên kết tái sử dụng](#list-reusable-links) | Theo dõi các liên kết chiến dịch và xem liên kết nào đang tạm dừng. |
| [Tạo liên kết tái sử dụng](#create-a-reusable-link) | Bắt đầu một chiến dịch mà nhiều merchant có thể đăng ký qua đó. |
| [Thay đổi thời hạn lời mời](#change-an-invites-expiry) | Gia hạn hoặc rút ngắn lời mời, kể cả lời mời đã hết hạn. |
| [Tạm dừng hoặc tiếp tục liên kết tái sử dụng](#pause-or-resume-a-reusable-link) | Tạm ngừng nhận đăng ký mới mà không thu hồi liên kết. |
| [Liệt kê bộ định giá](#list-pricing-sets) | Tìm các bộ định giá mà tổ chức của bạn có thể dùng để tạo hồ sơ. |
| [Liệt kê hồ sơ hoa hồng](#list-commission-profiles) | Chọn hồ sơ để gán cho lời mời. |
| [Tạo hồ sơ hoa hồng](#create-a-commission-profile) | Cung cấp cho merchant một bảng giá được tạo từ bộ định giá. |
| [Cập nhật hồ sơ hoa hồng](#update-a-commission-profile) | Đổi tên hồ sơ hoặc thay đổi mức phí của hồ sơ. |
| [Xóa hồ sơ hoa hồng](#delete-a-commission-profile) | Xóa hồ sơ bạn không còn cung cấp. |
| [Đặt hồ sơ mặc định](#set-the-default-profile) | Chọn hồ sơ được dùng cho lời mời không chỉ định hồ sơ nào. |
| [Đọc mức phí của merchant](#read-merchant-pricing) | Hiển thị mức phí merchant đã đăng ký. |
## Bản nháp onboarding [#onboarding-drafts]
**Dùng để** tiếp tục biểu mẫu onboarding của merchant với mọi dữ liệu họ đã lưu cho đến lúc này.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/onboarding' \
-H 'Authorization: REPLACE_ME'
```
**Cần biết:**
* Đây là lệnh gọi duy nhất trả về toàn bộ dữ liệu onboarding đã lưu; các lệnh gọi hồ sơ và đơn vị xử lý thanh toán chỉ trả về một phần.
* `pricingConstraints` liệt kê những gì merchant được phép chọn, không phải bảng phí.
**Trả về:**
| Trường | Mô tả |
| ---------------------- | --------------------------------------------------------------------------------------------------------- |
| `identity` | Thông tin danh tính của merchant. |
| `address` | Địa chỉ của merchant. |
| `business` | Thông tin kinh doanh dùng chung cho cả hai kênh. |
| `kyb` | Các tài khoản ngân hàng, tài khoản chính, các bên liên quan của công ty hoặc cá nhân, và tài liệu của họ. |
| `capability` | Capability đã chọn. |
| `terminal` | Thông tin đã lưu cho kênh tại cửa hàng. |
| `online` | Thông tin đã lưu cho kênh trực tuyến. |
| `processors` | Trạng thái với từng đơn vị xử lý thanh toán. |
| `commissionProfileIds` | Các hồ sơ hoa hồng đã gán cho merchant. |
| `pricingConstraints` | Các loại tiền tệ quyết toán và MCC được phép. |
**Dùng để** lưu các kênh thanh toán merchant đã chọn trong biểu mẫu của bạn trước khi họ hoàn tất onboarding.
```bash
curl -X POST 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/channel' \
-H 'Authorization: REPLACE_ME' \
-H 'Content-Type: application/json' \
-d '{
"capability": 2,
"terminal": {
"mcc": "5411",
"statementDescriptor": "ACME STORE",
"productDescription": "Groceries",
"averageItemValue": 2500,
"expectedMonthlyTurnover": 500000,
"numberOfTerminals": 1
}
}'
```
**Cần biết:**
* Chỉ hoạt động với merchant đã lưu bản nháp onboarding và hồ sơ.
* Cập nhật bản nháp và trả về `200`. Thao tác này không nộp hồ sơ onboarding hay đăng ký tài khoản với đơn vị xử lý thanh toán.
* Chỉ gửi các phần kênh mà merchant đã chọn.
**Tham số:**
| Trường | Mô tả |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `capability` | Các kênh đã chọn. Cùng giá trị như trong [Onboarding merchant](/platform-api/merchant_onboarding#request-online-payment-capabilities). |
| `terminal` | Thông tin kênh tại cửa hàng, với cùng các trường như trong Onboarding merchant. |
| `online` | Thông tin kênh trực tuyến, với cùng các trường như trong Onboarding merchant. |
## Thành viên và máy thanh toán [#members-and-terminals]
**Dùng để** xem ai đã có quyền truy cập vào một merchant.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/members' \
-H 'Authorization: REPLACE_ME'
```
**Cần biết:**
* Trả về một mảng gồm các thành viên hiện tại.
* Lời mời đang chờ không được bao gồm; chúng được liệt kê riêng.
**Trả về:** cho mỗi thành viên:
| Trường | Mô tả |
| ----------- | --------------------------------------- |
| `userId` | ID người dùng của thành viên. |
| `firstName` | Tên. |
| `lastName` | Họ. |
| `email` | Địa chỉ email. |
| `joinedAt` | Thời điểm thành viên tham gia merchant. |
**Dùng để** hiển thị các máy thanh toán của merchant và thiết bị được gán cho chúng.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/terminal?page=1&pageSize=25' \
-H 'Authorization: REPLACE_ME'
```
**Cần biết:**
* Trả về máy thanh toán, không phải địa điểm đang hoạt động; địa điểm có danh sách riêng.
* Phản hồi chứa `items` và `totalCount`. Mỗi mục có ID máy thanh toán và ID địa điểm, nhãn và thông tin thiết bị.
* `terminalType` và `deviceIdentifier` mô tả thiết bị đang được gán hiện tại, không phải thiết bị đã nhận một khoản thanh toán trước đó.
**Tham số:**
| Trường | Mô tả |
| --------------- | ----------------------- |
| `page` | Số trang. |
| `pageSize` | Số dòng mỗi trang. |
| `sortBy` | Trường dùng để sắp xếp. |
| `sortDirection` | Chiều sắp xếp. |
## Lời mời đăng ký [#registration-invites]
Dùng [lời mời qua email](/platform-api/merchant_onboarding#invite-a-merchant-to-complete-hosted-onboarding) cho người nhận đã biết, hoặc liên kết tái sử dụng cho một chiến dịch. Cả hai đều có thể giới hạn kênh và gán hồ sơ hoa hồng.
**Dùng để** theo dõi các lời mời dùng một lần bạn đã gửi.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/invites' \
-H 'Authorization: REPLACE_ME'
```
**Cần biết:**
* Mỗi lời mời hiển thị email người nhận, URL, `capability` và `commissionProfileIds`.
* Lời mời còn chứa `commissionProfileId`, dạng một hồ sơ của `commissionProfileIds`.
**Dùng để** theo dõi các liên kết chiến dịch và xem liên kết nào đang tạm dừng.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites' \
-H 'Authorization: REPLACE_ME'
```
**Cần biết:**
* Mỗi liên kết hiển thị `capability`, các hồ sơ đã gán và `pausedAt`.
* `pausedAt` là `null` khi liên kết không bị tạm dừng.
* Liên kết đang tạm dừng mà chưa hết hạn hoặc chưa bị thu hồi vẫn khớp với `isActive=true`. Hãy kiểm tra `pausedAt` để phân biệt.
**Dùng để** bắt đầu một chiến dịch mà nhiều merchant có thể đăng ký qua đó.
```bash
curl -X POST 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites' \
-H 'Authorization: REPLACE_ME' \
-H 'Content-Type: application/json' \
-d '{
"name": "Partner onboarding",
"expiresAt": "2030-12-31T00:00:00Z",
"capability": 2
}'
```
**Cần biết:**
* `capability` giới hạn các kênh mà merchant có thể chọn. Trường này không cấp phê duyệt của đơn vị xử lý thanh toán.
* Bỏ qua các trường hồ sơ để gán hồ sơ mặc định của tổ chức.
* `commissionProfileId` vẫn được chấp nhận cho một hồ sơ. Hãy dùng `commissionProfileIds` thay thế, và không bao giờ gửi cả hai.
**Tham số:**
| Trường | Mô tả |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Tên của chiến dịch. |
| `expiresAt` | Dấu thời gian ISO 8601 UTC, cách hiện tại ít nhất một ngày trong tương lai. Không có thời hạn tối đa. |
| `capability` | Tùy chọn. Cùng giá trị như với [lời mời qua email](/platform-api/merchant_onboarding#invite-a-merchant-to-complete-hosted-onboarding). |
| `commissionProfileIds` | Tùy chọn. Cùng quy tắc như với lời mời qua email. |
**Dùng để** gia hạn hoặc rút ngắn lời mời, kể cả lời mời đã hết hạn.
```bash
curl -X PUT 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f/expires-at' \
-H 'Authorization: REPLACE_ME' \
-H 'Content-Type: application/json' \
-d '{"expiresAt": "2031-01-31T00:00:00Z"}'
```
**Cần biết:**
* Với lời mời qua email, gọi `PUT /integrator/merchant/invites/{inviteId}/expires-at` với cùng nội dung.
* Trả về `204`.
* Không thể gia hạn lời mời đã thu hồi và lời mời qua email đã được sử dụng.
**Tham số:**
| Trường | Mô tả |
| ----------- | ----------------------------------------------------------------------------------------------------- |
| `expiresAt` | Dấu thời gian ISO 8601 UTC, cách hiện tại ít nhất một ngày trong tương lai. Không có thời hạn tối đa. |
**Dùng để** tạm ngừng nhận đăng ký mới mà không thu hồi liên kết.
```bash
curl -X PUT 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f/pause' \
-H 'Authorization: REPLACE_ME'
```
**Cần biết:**
* Gọi `.../resume` trên cùng liên kết để nhận đăng ký trở lại. Tiếp tục không gia hạn thời hạn của liên kết.
* Cả hai đều trả về `204` và có tính idempotent.
* Mở liên kết đang tạm dừng trả về `410`.
## Hồ sơ hoa hồng [#commission-profiles]
Hồ sơ hoa hồng là bảng giá bạn cung cấp cho merchant. Hãy tạo hồ sơ từ một bộ định giá mà tổ chức của bạn được phép sử dụng.
**Dùng để** tìm các bộ định giá bạn có thể dùng để tạo hồ sơ hoa hồng.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/organization/pricing-sets?pricingType=instore' \
-H 'Authorization: REPLACE_ME'
```
**Cần biết:**
* Mỗi bộ bao gồm mức phí theo hợp đồng cho merchant và cho bên tích hợp.
* Dùng `pricingSetId` được trả về khi bạn tạo hồ sơ.
**Tham số:**
| Trường | Mô tả |
| ------------- | ---------------------------------- |
| `pricingType` | Tùy chọn. `online` hoặc `instore`. |
**Dùng để** chọn hồ sơ để gán cho lời mời.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles?pricingType=online' \
-H 'Authorization: REPLACE_ME'
```
**Cần biết:**
* Chỉ trả về các hồ sơ được bật và hoàn chỉnh của tổ chức bạn.
* Mỗi hồ sơ bao phủ một loại định giá.
* Hãy lưu `revision` của từng hồ sơ nếu bạn định cập nhật hồ sơ đó.
**Tham số:**
| Trường | Mô tả |
| ------------- | ---------------------------------- |
| `pricingType` | Tùy chọn. `online` hoặc `instore`. |
**Dùng để** cung cấp cho merchant một bảng giá được tạo từ bộ định giá.
```bash
curl -X POST 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles' \
-H 'Authorization: REPLACE_ME' \
-H 'Content-Type: application/json' \
-d '{
"name": "Standard profile",
"pricingModel": 1,
"cardTypes": [
{"region": 1, "holderType": 1, "scheme": 1, "enabled": true, "referralFeeRelative": 0, "referralFeeAbsolute": 0}
],
"pricings": [
{"currency": "eur", "pricingSetId": "018f8f2a-5d3a-7e4c-9b3f-4a8c3d9e6f5a"}
]
}'
```
**Cần biết:**
* Một hồ sơ bao phủ một loại định giá, lấy từ các bộ định giá của hồ sơ.
* Chi phí bên tích hợp và tỷ lệ chia doanh thu đến từ bộ định giá; bạn chỉ đặt mức phí cho merchant.
* `region` là `1` trong nước hoặc `2` quốc tế, `holderType` là `1` cá nhân tiêu dùng hoặc `2` công ty, và `scheme` là `1` Visa hoặc `2` Mastercard.
**Tham số:**
| Trường | Mô tả |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Tên hồ sơ. |
| `pricingModel` | `1` cho MDR hoặc `2` cho IC++. |
| `cardTypes` | Mỗi tổ hợp khu vực, loại chủ thẻ và tổ chức thẻ mà hồ sơ chấp nhận, kèm phí giới thiệu tương ứng. |
| `pricings` | Tiền tệ và `pricingSetId` cho mỗi loại tiền tệ bạn cung cấp. |
| `merchantPricingOverrides` | Tùy chọn. Các mục với `holderCategory`, `regionSegment`, `relative` và `absolute`. Các tổ hợp bạn bỏ qua giữ mức phí của bộ định giá. |
**Dùng để** đổi tên hồ sơ hoặc thay đổi mức phí của hồ sơ.
```bash
curl -X PUT 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles/018f8f2a-7a1c-7b2d-8e3f-6c1d2e3f4a5b' \
-H 'Authorization: REPLACE_ME' \
-H 'Content-Type: application/json' \
-d '{
"name": "Standard profile 2027",
"pricingModel": 1,
"cardTypes": [
{"region": 1, "holderType": 1, "scheme": 1, "enabled": true, "referralFeeRelative": 0, "referralFeeAbsolute": 0}
],
"expectedRevision": 3
}'
```
**Cần biết:**
* Gửi `revision` bạn đọc gần nhất dưới dạng `expectedRevision`. Phiên bản sửa đổi đã cũ trả về `409`.
* Bỏ qua `pricings` để giữ mức phí đã lưu.
* Hồ sơ đã được gán cho merchant, hoặc không cho phép chỉnh sửa, chỉ chấp nhận tên mới.
**Tham số:**
| Trường | Mô tả |
| ------------------ | ------------------------------------------- |
| `name` | Bắt buộc. Tên hồ sơ. |
| `pricingModel` | Bắt buộc. `1` cho MDR hoặc `2` cho IC++. |
| `cardTypes` | Bắt buộc. Giống như khi tạo. |
| `pricings` | Tùy chọn. Giống như khi tạo. |
| `expectedRevision` | `revision` của hồ sơ tại thời điểm bạn đọc. |
**Dùng để** xóa hồ sơ bạn không còn cung cấp.
```bash
curl -X DELETE 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles/018f8f2a-7a1c-7b2d-8e3f-6c1d2e3f4a5b' \
-H 'Authorization: REPLACE_ME'
```
**Cần biết:**
* Không thể xóa hồ sơ mặc định. Hãy đặt một hồ sơ khác làm mặc định trước.
* Không thể xóa hồ sơ đã được gán cho merchant. Cả hai trường hợp đều trả về `400`.
**Dùng để** chọn hồ sơ được dùng cho lời mời không chỉ định hồ sơ nào.
```bash
curl -X PUT 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles/018f8f2a-7a1c-7b2d-8e3f-6c1d2e3f4a5b/default' \
-H 'Authorization: REPLACE_ME'
```
**Cần biết:**
* Tổ chức của bạn có một hồ sơ mặc định.
* Không thể xóa hồ sơ mặc định.
## Mức phí của merchant [#merchant-pricing]
**Dùng để** hiển thị mức phí merchant đã đăng ký, cho thanh toán tại cửa hàng và thanh toán trực tuyến.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/pricing' \
-H 'Authorization: REPLACE_ME'
```
**Cần biết:**
* Kênh chưa có mức phí đã lưu có giá trị `null`. Merchant không có bảng giá đã lưu nào trả về `404`.
* Trả về mức phí theo hợp đồng, không phải bảng phí cơ sở của nhà cung cấp dịch vụ thanh toán. Đọc mức phí từ `cells`; các thành phần `commission` không phải hoa hồng đã thực nhận.
* Mô hình hoặc chi phí bên tích hợp chưa biết có giá trị `null`, không phải bằng không.
* Tỷ lệ chia doanh thu chia biên lợi nhuận có thể phân phối, không phải toàn bộ số tiền thanh toán.
**Trả về:**
| Trường | Mô tả |
| ------------------------------------- | ------------------------------------------------------------------------ |
| `instore` | Mức phí tại cửa hàng, hoặc `null`. |
| `online` | Mức phí trực tuyến, hoặc `null`. |
| `currency` | Tiền tệ của mức phí. |
| `pricingModel` | Mô hình định giá của merchant. |
| `integratorPricingModel` | Mô hình định giá của bên tích hợp, độc lập với mô hình của merchant. |
| `priceListId` | Bảng giá đã lưu của merchant, nếu có. |
| `pricingSetVersionId` | Phiên bản bộ định giá nguồn, nếu có. |
| `pricingSetName` | Tên bộ định giá nguồn, nếu có. |
| `cells` | Mức phí theo nhóm chủ thẻ và khu vực. |
| `cells[].discountBps` | Mức phí tương đối cuối cùng của merchant theo điểm cơ bản. |
| `cells[].transactionFeeMinor` | Phí cố định cuối cùng của merchant theo đơn vị nhỏ nhất. |
| `cells[].integratorCostRelativeBps` | Chi phí tương đối theo hợp đồng của bên tích hợp theo điểm cơ bản. |
| `cells[].integratorCostAbsoluteMinor` | Chi phí cố định theo hợp đồng của bên tích hợp theo đơn vị nhỏ nhất. |
| `cells[].revenueShareTapayaBps` | Phần của Tapaya trong biên lợi nhuận có thể phân phối, theo điểm cơ bản. |
| `cells[].revenueShareIntegratorBps` | Phần của bạn trong biên lợi nhuận có thể phân phối, theo điểm cơ bản. |
## Lỗi [#errors]
Mọi thao tác đều trả về các mã trạng thái sau khi yêu cầu thất bại.
| Mã | Mô tả |
| ----- | -------------------------------------------------------------------------------------------------------------- |
| `400` | Dữ liệu kênh, lựa chọn hồ sơ, bộ lọc hoặc thời hạn không hợp lệ, hoặc xóa hồ sơ mặc định hay hồ sơ đã gán. |
| `401` | Server Secret Token bị thiếu hoặc không hợp lệ. |
| `404` | Tài nguyên không khả dụng cho tổ chức của bạn, hoặc dữ liệu onboarding hay mức phí đã lưu không tồn tại. |
| `409` | Phiên bản sửa đổi hồ sơ đã cũ, trạng thái onboarding xung đột, hoặc lời mời đã được sử dụng hay đã bị thu hồi. |