# Platform API (/vi/platform-api)





Tapaya Platform API cho phép bạn quản lý merchant, thanh toán và cài đặt tổ chức từ máy chủ của mình. Bạn cần
những endpoint nào phụ thuộc vào cách ứng dụng của bạn nhận thanh toán; không phải bên tích hợp nào cũng cần mọi phần.

<SwaggerBanner href="https://api.tapaya.com/openapi/index.html" />

<Callout title="Enum là giá trị số" type="info">
  Các trường như `businessTypeId`, `countryId`, `currencyId`, `documentType` và `refundReasonId` đều là enum
  dạng số. Các giá trị có thể có của từng trường được liệt kê trong
  [tài liệu Swagger](https://api.tapaya.com/openapi/index.html), không phải trong hướng dẫn này.
</Callout>

## Những phần áp dụng cho bạn [#which-sections-apply-to-you]

| Tích hợp của bạn                                                                                                                  | [Xác thực merchant](/in-store/integration/backend_integration#merchant-authentication-accept-sdk-integrations) | [Onboarding merchant](/platform-api/merchant_onboarding) | [Báo cáo và thanh toán](/platform-api/reporting) |
| --------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------: | :----------------------------------------------: |
| **Accept SDK** (nhúng trong ứng dụng của bạn)                                                                                     |                                                   🟢 Bắt buộc                                                  |                        🟡 Tùy chọn                       |                    🟡 Tùy chọn                   |
| **Chỉ ứng dụng Tapaya Terminal** ([intent/deeplink](/in-store/integration/card_terminal#integrate-without-the-sdk), không có SDK) |                                                   ⚪ Không cần                                                  |                        🟡 Tùy chọn                       |                    🟡 Tùy chọn                   |
| **Chỉ báo cáo / back-office**                                                                                                     |                                                   ⚪ Không cần                                                  |                        ⚪ Không cần                       |                    🟢 Bắt buộc                   |

* **Xác thực merchant**: SDK xác thực với tư cách merchant bằng một token đăng nhập do backend của bạn yêu cầu. Không
  cần thiết cho các tích hợp Tapaya Terminal: merchant đăng nhập trực tiếp vào ứng dụng Tapaya Terminal, nên không có
  phiên SDK nào để backend của bạn phải xác thực.
* **Onboarding merchant**: tùy chọn cho mọi tích hợp thanh toán, tại cửa hàng hay trực tuyến. Merchant chỉ onboarding một lần và
  lần onboarding đó áp dụng cho cả hai kênh. Thực hiện onboarding qua Tapaya Platform UI, lời mời onboarding do Tapaya lưu trữ hoặc API, tùy theo
  ai là bên thu thập dữ liệu của merchant.
* **Báo cáo và thanh toán**: tùy chọn cho cả hai loại tích hợp thanh toán nếu bạn tự xây dựng bảng điều khiển;
  bắt buộc (và tự nó là đủ) nếu bạn chỉ lấy dữ liệu báo cáo mà không có tích hợp thanh toán riêng.

Tất cả các hàng vẫn yêu cầu [xác thực](#authentication) bằng Server Secret Token.

<Callout title="Dùng Secret key cho Checkout" type="info">
  [Online Checkout](/online/integration/api_integration#authentication) chấp nhận cùng một **Secret key** từ
  [trang API Keys](https://platform.tapaya.com/api-keys/), ở đây được gọi là Server Secret Token.
  Checkout yêu cầu `Authorization: Bearer <secret-key>` và ánh xạ tổ chức tới một merchant.
  Xem [Xác thực Checkout](/online/integration/api_integration#authentication) để biết các yêu cầu về việc khớp merchant.
</Callout>

## Môi trường [#environments]

Tapaya Platform API hỗ trợ các môi trường sau:

* **Production:** Chạy tại `https://api.tapaya.com`. Môi trường này dùng tài khoản thật và liên quan đến tiền thật. &#x2A;*Không sử dụng môi trường production để thử nghiệm.**
* **Sandbox:** Chạy tại `https://api.sandbox.tapaya.com`. Môi trường này cho phép bạn thử nghiệm tích hợp mà không có bất kỳ dịch chuyển tiền thật nào. Tìm hiểu thêm về kiểm thử trong [hướng dẫn Kiểm thử / Sandbox](/in-store/getting-started/testing) của chúng tôi.

## Xác thực [#authentication]

Các yêu cầu đến Platform API sử dụng Server Secret Token của bạn, được ghi là **Secret key** trên trang API Keys. Truyền nguyên giá trị này trong header `Authorization` của các yêu cầu HTTP.

```http
Authorization: REPLACE_ME
```

Để xác thực nền tảng của bạn với API, bạn phải tạo một **Secret key**, ở đây gọi là Server Secret Token, trên [trang API Keys](https://platform.tapaya.com/api-keys/) và thay *REPLACE\_ME* ở trên bằng giá trị đó.

<Callout title="Cảnh báo bảo mật" type="warn">
  Server Secret Token của bạn có quyền hạn cao. **Không bao giờ** để lộ token này trong mã phía client (ứng dụng di động, trình duyệt
  web). Token chỉ được phép sử dụng từ các máy chủ backend bảo mật của bạn.
</Callout>

Nếu một token bị lộ, hãy thu hồi token đó trên [trang API Keys](https://platform.tapaya.com/api-keys/); việc thu hồi
có hiệu lực ngay lập tức và không thể hoàn tác. Tạo token thay thế trước hoặc sau khi thu hồi, tùy nhu cầu;
không có thao tác “xoay vòng” tại chỗ, vì vậy hãy cập nhật cấu hình backend bằng token mới sau khi tạo.

<Callout title="Không giới hạn phạm vi key" type="info">
  Mọi Server Secret Token đều có cùng quyền hạn trên toàn tổ chức; hiện chưa thể giới hạn token cho
  các endpoint hoặc merchant cụ thể. Hãy coi mọi token tương đương với quyền truy cập API đầy đủ cho tổ chức của bạn.
</Callout>

Máy chủ chỉ có thể truy cập qua giao thức HTTPS, với TLS 1.2 trở lên được áp dụng bắt buộc ở cấp hạ tầng. Có áp dụng giới hạn tần suất (100 yêu cầu mỗi phút trên mỗi địa chỉ IP); các yêu cầu làm quá tải máy chủ sẽ trả về lỗi `429 Too Many Requests`.