Tài liệu Webhook
1. Tổng quan
Hệ thống kiểm tra lịch sử giao dịch của các tài khoản đã cấu hình webhook liên tục (khoảng 5 giây / lần).
Khi có giao dịch mới khớp với Sự kiện (Tất cả / Nhận tiền / Chuyển tiền), hệ thống gửi một request
POST tới Endpoint của bạn. Định dạng tương thích với Pay2S Webhook.
Giao dịch có sẵn trước khi tạo webhook sẽ không được gửi.
2. Request
POST {Endpoint}
Content-Type: application/json
Authorization: Bearer {Token webhook}
{
"transactions": [
{
"id": 10001,
"gateway": "ACB",
"transactionDate": "2026-10-18 09:00:00",
"transactionNumber": "5208",
"accountNumber": "15531151",
"content": "NAP123 chuyen tien",
"transferType": "IN",
"transferAmount": 2000,
"checksum": "9f2b0c3e4d5a6b7c8d9e0f1a2b3c4d5e"
}
]
}
| Trường | Kiểu | Mô tả |
|---|---|---|
| id | number | ID duy nhất của lần thông báo giao dịch |
| gateway | string | Mã ngân hàng: ACB, VCB, MBB, TCB, BIDV, TPB, VTB, THESIEURE |
| transactionDate | string | Thời gian giao dịch, định dạng Y-m-d H:i:s |
| transactionNumber | string | Mã giao dịch phía ngân hàng |
| accountNumber | string | Số tài khoản nhận / chuyển |
| content | string | Nội dung chuyển khoản |
| transferType | string | IN = tiền vào, OUT = tiền ra |
| transferAmount | number | Số tiền (VND) |
| checksum | string | Mã định danh giao dịch, dùng để chống xử lý trùng |
3. Phản hồi
Endpoint phải trả về HTTP 2xx với body {"success": true} trong vòng 10 giây.
Nếu không, hệ thống gửi lại sau 1 phút, 2 phút, 5 phút, 15 phút, 30 phút.
Vì có thể nhận lại cùng một giao dịch, hãy xử lý idempotent theo id hoặc checksum.
4. Code mẫu (PHP)
<?php
// webhook.php - nhận giao dịch
$token = 'TOKEN_WEBHOOK_CUA_BAN';
$auth = $_SERVER['HTTP_AUTHORIZATION'] ?? $_SERVER['REDIRECT_HTTP_AUTHORIZATION'] ?? '';
if (!hash_equals('Bearer ' . $token, $auth)) {
http_response_code(403);
exit(json_encode(['success' => false]));
}
$data = json_decode(file_get_contents('php://input'), true);
if (!isset($data['transactions']) || !is_array($data['transactions'])) {
http_response_code(400);
exit(json_encode(['success' => false]));
}
foreach ($data['transactions'] as $tx) {
// Lưu giao dịch, chống trùng theo $tx['id'] hoặc $tx['checksum']
// if ($tx['transferType'] === 'IN') { ... cộng tiền theo $tx['content'] ... }
}
header('Content-Type: application/json');
echo json_encode(['success' => true]);
Nếu máy chủ Apache không nhận được header Authorization, thêm vào .htaccess:
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]