Callback
Tổng quan
Callback hoặc Webhook là một cơ chế tự động thông báo cho các nhà bán hàng về các sự kiện liên quan đến giao dịch Zalopay. Người dùng và nhà phát triển bên thứ ba có thể quản lý các Callback này. Chúng là các phản hồi HTTP được xác định bởi người dùng cho phép hai ứng dụng trực tuyến độc lập giao tiếp với nhau.
Luồng thực hiện
Khi một giao dịch thanh toán / liên kết thành công:
- Máy chủ Zalopay sẽ thông báo đến Máy chủ Merchant thông qua Callback URL đã đăng ký trước đó.
- Máy chủ Merchant sử dụng mac key (do Zalopay cung cấp) để xác nhận dữ liệu callback.
Yêu cầu (Request)
Zalopay gửi kết quả thanh toán thành công hoặc kết quả liên kết/hủy liên kết về cho Merchant
- Phương thức:
POST - Content-Type:
application/json
Kết quả dữ liệu theo cấu trúc sau (áp dụng cho thanh toán/liên kết):
| Tham số | Kiểu dữ liệu | Mô tả |
|---|---|---|
| data | Json String | Dữ liệu gọi lại (callback data) có thể thay đổi định dạng tùy thuộc vào sản phẩm cụ thể. |
| mac | String | Xác nhận thông tin đơn hàng bằng cách sử dụng mac key (đã được cung cấp) để xác minh đơn hàng. |
| type | Int | Loại gọi lại (callback type): - type=1: Order - type=2: Agreement |
Dữ liệu gọi lại (callback data) cụ thể được như bên dưới:
Dữ liệu gọi lại (callback data) cho đơn hàng:
| Tham số | Kiểu dữ liệu | Mô tả |
|---|---|---|
| app_id | Int | Thông tin app_id của đơn hàng. |
| app_trans_id | String | Thông tin app_trans_id của đơn hàng. |
| app_time | Int64 | Thông tin app_time của đơn hàng. |
| app_user | String | Thông tin app_user của đơn hàng. |
| amount | Int64 | Thông tin số tiền user thực hiện thanh toán(VND). |
| embed_data | Json String | Thông tin embed_data của đơn hàng. |
| item | Json Array | Thông tin item của đơn hàng. |
| zp_trans_id | Int64 | Thông tin mã giao dịch của Zalopay. |
| server_time | Int64 | Thời gian giao dịch của Zalopay (unix timestamp in miliseconds). |
| channel | Int | Kênh thanh toán. |
| merchant_user_id | String | Thông tin định danh của Zalopay user tương ứng với app_id. |
| user_fee_amount | Int64 | Thông tin phí của đơn hàng (VND). |
| discount_amount | Int64 | Thông tin khuyến mãi của đơn hàng (VND). |
Ví dụ:
{
"data": "{\"app_id\":2638,\"app_trans_id\":\"230407_13583500399\",\"app_time\":1680850715576,\"app_user\":\"Zalopay\",\"amount\":50000,\"embed_data\":\"{}\",\"item\":\"[]\",\"zp_trans_id\":230407000006575,\"server_time\":1680850894407,\"channel\":38,\"merchant_user_id\":\"Bs8KJXf2GKyfVv_fnxG7IwG5VbQ8H_qGsOUW2UJAJSM\",\"zp_user_id\":\"Bs8KJXf2GKyfVv_fnxG7IwG5VbQ8H_qGsOUW2UJAJSM\",\"user_fee_amount\":0,\"discount_amount\":0}",
"mac": "761c9be42fd419b7078e4cf42e5034238ced266b2e094bfd4ce242f99e61b172",
"type": 1
}
Dữ liệu gọi lại (callback data) cho liên kết:
| Tham số | Kiểu dữ liệu | Mô tả |
|---|---|---|
| app_id | Int | Thông tin app_id của liên kết. |
| app_trans_id | String | Thông tin app_trans_id của liên kết. |
| binding_id | String | Thông tin binding_id của liên kết. |
| pay_token | String | Thông tin token của người dùng. |
| server_time | Int | Thời gian xử lý của Zalopay. |
| merchant_user_id | String | Thông tin định danh của user (giá trị identifier trong request gọi API liên kết). |
| status | Int | 1: người dùng liên kết, 3: người dùng hủy liên kết. |
| msg_type | Int | 1: người dùng đồng ý liên kết, 2: người dùng cập nhật liên kết. |
| zp_user_id | String | Thông tin định danh của Zalopay user tương ứng với app_id. |
| masked_user_phone | String | Thông tin số điện thoại đăng ký Zalopay đã được che dấu (Ex: masked_user_phone: "****6938"). |
Ví dụ:
{
"data": "{\"app_id\":2638,\"app_trans_id\":\"230407_13221300383\",\"binding_id\":\"230407qQe7vGnqp0agyforLAy0D2b1x3\",\"pay_token\":\"NJLHNTRLZDETZGQYZI0ZNTBKLTGWZJKTMTKXYJHLMWI5NTFI\",\"merchant_user_id\":\"84903863801\",\"zp_user_id\":\"Bs8KJXf2GKyfVv_fnxG7IwG5VbQ8H_qGsOUW2UJAJSM\",\"masked_user_phone\":\"****3801\",\"server_time\":1680848564,\"status\":1,\"msg_type\":1,\"expiry_timestamp_in_ms\":1996467763977}",
"mac": "bed74dc38e023d7402297107e1e518b16731d1689ebf77120872e12d9e36882a",
"type": 2
}
Phản hồi (response)
| Tham số | Kiểu dữ liệu | Mô tả |
|---|---|---|
| return_code | Int | 1: Thành công 2: Thất bại |
| return_message | String | Mô tả về mã trả về |
Xác thực (validation)
URL callback của bạn có thể bị tấn công bởi hacker. Để đảm bảo tính hợp lệ của một callback, việc xác thực bằng HMAC là bắt buộc.
reqmac = HMAC(hmac_algorithm, mac key, callback_data.data);
if (reqmac == callback_data.mac) {
// valid callback
} else {
// invalid callback
}
trong đó:
hmac_algorithm: là phương pháp bảo mật được đăng ký bởi Merchant với Zalopay, giá trị mặc định làHmacSHA256mac key: được Zalopay cung cấp trong quá trình đăng ký.callback_data: là dữ liệu mà Zalopay yêu cầu từ API gọi lại của Merchant khi Zalopay đã thành công thu tiền từ khách hàng.
Kênh thanh toán
| Giá trị | Kênh Thanh Toán |
|---|---|
| 36 | Visa/Master/JCB |
| 37 | Bank Account |
| 38 | Zalopay Wallet |
| 39 | ATM |
| 41 | Visa/Master Debit |
| 44 | MMF (Số dư sinh lời) |
| 45 | BNPL (Tài khoản trả sau) |
| 46 | VietQR |
| 58 | VietQR Global |