Webhook
Nhận thông báo có chữ ký khi thanh toán, hoàn tiền, merchant và onboarding thay đổi.
Webhook thông báo cho server của bạn về các thay đổi trong tổ chức Tapaya. Sử dụng cùng một tích hợp cho thanh toán tại cửa hàng và thanh toán trực tuyến, bất kể đơn vị xử lý thanh toán.
Cách hoạt động
TapayaCấu hình một địa chỉ đích HTTPS cho mỗi tổ chức và chọn các sự kiện bạn cần. Tapaya gửi yêu cầu HTTP POST kèm bản lưu (snapshot) JSON và chữ ký. Xác thực chữ ký, lưu sự kiện và trả về phản hồi thành công trước khi xử lý logic nghiệp vụ.
Bạn có thể đăng ký từng loại hoặc tất cả các loại được hỗ trợ. Đăng ký tất cả các loại cũng nhận những loại mới được hỗ trợ trong tương lai, vì vậy hãy bỏ qua các loại mà ứng dụng của bạn không nhận diện được.
Tích hợp nhanh
Lưu địa chỉ đích
Trong Platform, mở API Keys, rồi Webhooks. Nhập URL HTTPS của bạn, chọn các sự kiện bạn cần và lưu. Sao chép signing secret (khóa ký) ngay lúc này; khóa chỉ hiển thị một lần. Xem Cấu hình.
Xác thực từng yêu cầu
Tính HMAC-SHA256 trên dấu thời gian, một dấu chấm và nội dung gốc bằng signing secret của bạn, rồi so sánh kết quả với X-Tapaya-Signature. Xem Kiểm tra chữ ký.
Lưu sự kiện, rồi trả về 2xx
Lưu sự kiện với id duy nhất, trả lời 2xx trong vòng 10 giây và xử lý sự kiện sau đó. Xem Lưu và xác nhận.
Gửi webhook kiểm tra
Trên cùng trang đó, dùng thao tác kiểm tra để gửi một webhook.test có chữ ký. Xem Gửi webhook kiểm tra.
Cấu trúc chung của sự kiện
Mỗi sự kiện sử dụng cấu trúc chung này. Bản lưu của tài nguyên trong data phụ thuộc vào loại sự kiện.
{
"id": "019a0000-0000-7000-8000-000000000001",
"type": "payment.succeeded",
"apiVersion": "1",
"organizationId": "019a0000-0000-7000-8000-000000000002",
"merchantId": "019a0000-0000-7000-8000-000000000005",
"createdAt": "2026-10-30T12:00:00.000000Z",
"data": {
"payment": {
"id": "019a0000-0000-7000-8000-000000000003",
"token": "example_payment_token",
"merchantId": "019a0000-0000-7000-8000-000000000005",
"status": "success",
"statusId": 2,
"requestedAmount": 10000,
"requestedCurrencyId": 203,
"settlementAmount": 10000,
"settlementCurrencyId": 203
}
}
}| Trường | Ý nghĩa |
|---|---|
id | ID duy nhất của sự kiện. Dùng ID này để loại bỏ các lần gửi trùng lặp. Các lần thử lại giữ nguyên ID. |
type | Tên sự kiện trong danh mục sự kiện. |
apiVersion | Mã định danh cấu trúc payload, hiện là chuỗi "1". |
organizationId | Tổ chức sở hữu sự kiện. Kiểm tra xem tổ chức có khớp với tích hợp của bạn không. |
merchantId | Merchant sở hữu tài nguyên. Có thể là null đối với các khoản thanh toán cũ chưa xác định được chủ sở hữu hoặc một lần kiểm tra chẩn đoán. |
createdAt | Thời gian UTC khi sự kiện được ghi nhận, thay vì thời gian gửi. |
data | Bản lưu bất biến của tài nguyên tại thời điểm ghi nhận sự kiện. |
Số tiền là số nguyên theo đơn vị nhỏ nhất của loại tiền tệ tương ứng với trường. Ví dụ, 10000 với ID tiền tệ dạng số ISO 4217 203 có nghĩa là 100,00 CZK. Số tiền yêu cầu và số tiền quyết toán có thể sử dụng các loại tiền tệ khác nhau.
Mỗi loại sự kiện đặt bản lưu riêng của mình bên trong data. Xem Loại sự kiện để biết mọi dạng payload và giá trị trạng thái.
Quy tắc gửi
Tapaya gửi sự kiện ngay khi thay đổi của sự kiện được lưu, và tiếp tục gửi cho đến khi server của bạn trả lời 2xx.
| Quy tắc | Cách hoạt động |
|---|---|
| Xác nhận | Mọi phản hồi 2xx trong vòng 10 giây. Hệ thống không đi theo chuyển hướng. |
| Thử lại | Tối đa 12 lần thử trong khoảng 20 giờ, với khoảng chờ 1, 2, 4, 8, 16, 32, 64, 128, 256, 360 và 360 phút. |
| Thứ tự | Không được đảm bảo. Sự kiện được gửi ít nhất một lần, vì vậy hãy dự liệu các sự kiện trùng lặp và bản lưu cũ hơn. |
| Đồng thời | 2 yêu cầu cùng lúc cho mỗi tổ chức, dùng chung với các lần kiểm tra thủ công. Các sự kiện khác chờ trong hàng đợi. |
Một lần gửi thất bại không bao giờ làm thay đổi chính khoản thanh toán, và các lần gửi trước đây không thể gửi lại. Để cập nhật sau sự cố gián đoạn, hãy đọc trạng thái hiện tại qua API thanh toán và merchant.