Platform API
Các môi trường, xác thực và những phần của Tapaya Platform API mà tích hợp của bạn cần.
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.
Swagger documentationTapaya Integrator APIEvery endpoint, request field, and enum value, with a console to try requests.Open the API reference
Enum là giá trị số
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, không phải trong hướng dẫn này.
Những phần áp dụng cho bạn
| Tích hợp của bạn | Xác thực merchant | Onboarding merchant | Báo cáo và thanh toán |
|---|---|---|---|
| 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, 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 bằng Server Secret Token.
Dùng Secret key cho Checkout
Online Checkout chấp nhận cùng một Secret key từ
trang 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 để biết các yêu cầu về việc khớp merchant.
Môi trường
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. 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 của chúng tôi.
Xác thực
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.
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 và thay REPLACE_ME ở trên bằng giá trị đó.
Cảnh báo bảo mật
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.
Nếu một token bị lộ, hãy thu hồi token đó trên trang 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.
Không giới hạn phạm vi key
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.
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.