Cấu trúc Payload & Tích hợp Webhook
Tích hợp webhook HiTechCloud Pay: đặc tả các trường trong payload giao dịch, quy chuẩn phản hồi bắt buộc và kỹ thuật chống trùng lặp (idempotent).
Mỗi khi phát sinh giao dịch thỏa mãn điều kiện, HiTechCloud Pay gửi request HTTP POST dạng JSON đến URL đã cấu hình.
Cấu trúc Payload mẫu (JSON)
{
"id": 92704,
"gateway": "Vietcombank",
"transactionDate": "2026-10-31 09:22:10",
"accountNumber": "9988776655",
"subAccount": "VA001",
"code": "DH98765",
"content": "DH98765 chuyen tien mua hosting hitechcloud",
"transferType": "in",
"description": "NGUYEN VAN A chuyen tien",
"transferAmount": 500000,
"accumulated": 15500000,
"referenceCode": "FT261031998888"
}{
"id": 92705,
"gateway": "MBBank",
"transactionDate": "2026-10-31 09:25:40",
"accountNumber": "090912345678",
"subAccount": null,
"code": "INV-7788",
"content": "INV-7788 THANH TOAN CLOUD VPS",
"transferType": "in",
"description": "MBB-090912345678-TK-NAP-TIEN",
"transferAmount": 1200000,
"accumulated": 48200000,
"referenceCode": "MB26103100124"
}Ý nghĩa chi tiết các trường dữ liệu
| Trường | Kiểu | Có thể null? | Mô tả chi tiết |
|---|---|---|---|
id | integer | Không | ID duy nhất của giao dịch trên hệ thống HiTechCloud Pay. Giá trị này cố định qua mọi lần retry/replay, dùng làm khóa chống trùng lặp. |
gateway | string | Không | Tên ngân hàng phát sinh giao dịch (ví dụ: Vietcombank, MBBank, ACB, BIDV, Techcombank, VPBank...). |
transactionDate | string | Không | Thời gian giao dịch theo định dạng YYYY-MM-DD HH:mm:ss (múi giờ Việt Nam GMT+7). |
accountNumber | string | Không | Số tài khoản ngân hàng thụ hưởng nhận tiền của bạn. |
subAccount | string | Có thể rỗng | Số tài khoản ảo (VA) hoặc mã định danh phụ nếu giao dịch thông qua Virtual Account. |
code | string | Có thể null | Mã thanh toán bóc tách được từ nội dung theo mẫu cấu hình (ví dụ: DH98765). null nếu không khớp cấu hình. |
content | string | Không | Nội dung chuyển khoản nguyên bản nhận từ ngân hàng, giữ nguyên không biến đổi. |
transferType | string | Không | Chiều dòng tiền: in (tiền vào) hoặc out (tiền ra). |
description | string | Có thể rỗng | Mô tả chi tiết giao dịch từ hệ thống ngân hàng. |
transferAmount | integer | Không | Số tiền giao dịch thực tế tính bằng VNĐ (luôn là số nguyên dương). |
accumulated | integer | Có thể 0 | Số dư tích lũy sau giao dịch (nếu ngân hàng hỗ trợ trả số dư). |
referenceCode | string | Có thể rỗng | Mã số bút toán / mã tham chiếu từ ngân hàng chuyển mạch (FT code). |
3 Điều kiện bắt buộc để xác nhận thành công
- HTTP Status Code: Server của bạn phải trả về HTTP
200hoặc201. - Body JSON: Nội dung trả lời phải là chuỗi JSON:
{"success": true}. - Thời gian timeout: Máy chủ phải phản hồi trong vòng tối đa 30 giây (khuyến nghị dưới 2 giây).
Xử lý chống trùng lặp (Idempotency)
Do cơ chế retry tự động khi mạng chập chờn hoặc khi quản trị viên bấm 'Gửi lại' trên bảng điều khiển, một giao dịch có thể được gửi nhiều hơn một lần. Để tránh cộng tiền 2 lần cho khách, bạn phải sử dụng trường id của payload làm ràng buộc UNIQUE trong cơ sở dữ liệu.
CREATE TABLE `hitechcloud_webhook_transactions` (
`id` BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
`htc_transaction_id` BIGINT UNSIGNED NOT NULL,
`gateway` VARCHAR(64) NOT NULL,
`transaction_date` DATETIME NOT NULL,
`account_number` VARCHAR(64) NOT NULL,
`sub_account` VARCHAR(64) NULL,
`code` VARCHAR(128) NULL,
`content` TEXT NOT NULL,
`transfer_type` ENUM('in', 'out') NOT NULL DEFAULT 'in',
`transfer_amount` BIGINT UNSIGNED NOT NULL,
`accumulated` BIGINT UNSIGNED DEFAULT 0,
`reference_code` VARCHAR(128) NULL,
`raw_payload` JSON NULL,
`created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
UNIQUE KEY `uniq_htc_trans_id` (`htc_transaction_id`),
INDEX `idx_code` (`code`),
INDEX `idx_account` (`account_number`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;<?php
$payload = json_decode(file_get_contents('php://input'), true);
$trans_id = $payload['id'];
// Chèn vào bảng với khóa UNIQUE(htc_transaction_id)
$stmt = $pdo->prepare("INSERT IGNORE INTO hitechcloud_webhook_transactions
(htc_transaction_id, gateway, transaction_date, account_number, sub_account, code, content, transfer_type, transfer_amount, accumulated, reference_code, raw_payload)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
$stmt->execute([
$trans_id,
$payload['gateway'],
$payload['transactionDate'],
$payload['accountNumber'],
$payload['subAccount'] ?? null,
$payload['code'] ?? null,
$payload['content'],
$payload['transferType'],
$payload['transferAmount'],
$payload['accumulated'] ?? 0,
$payload['referenceCode'] ?? null,
json_encode($payload)
]);
if ($stmt->rowCount() === 0) {
// Đã tồn tại giao dịch này trước đó -> phản hồi thành công ngay để dừng retry
echo json_encode(['success' => true, 'message' => 'Already processed']);
exit;
}
// Xử lý cộng tiền hoặc kích hoạt dịch vụ cho giao dịch mới...
echo json_encode(['success' => true]);Mỗi khi phát sinh giao dịch thỏa mãn điều kiện, HiTechCloud Pay gửi request HTTP POST dạng JSON đến URL đã cấu hình.
Cấu trúc Payload mẫu (JSON)
Ý nghĩa chi tiết các trường dữ liệu
| Trường | Kiểu | Có thể null? | Mô tả chi tiết |
|---|---|---|---|
id | integer | Không | ID duy nhất của giao dịch trên hệ thống HiTechCloud Pay. Giá trị này cố định qua mọi lần retry/replay, dùng làm khóa chống trùng lặp. |
gateway | string | Không | Tên ngân hàng phát sinh giao dịch (ví dụ: Vietcombank, MBBank, ACB, BIDV, Techcombank, VPBank...). |
transactionDate | string | Không | Thời gian giao dịch theo định dạng YYYY-MM-DD HH:mm:ss (múi giờ Việt Nam GMT+7). |
accountNumber | string | Không | Số tài khoản ngân hàng thụ hưởng nhận tiền của bạn. |
subAccount | string | Có thể rỗng | Số tài khoản ảo (VA) hoặc mã định danh phụ nếu giao dịch thông qua Virtual Account. |
code | string | Có thể null | Mã thanh toán bóc tách được từ nội dung theo mẫu cấu hình (ví dụ: DH98765). null nếu không khớp cấu hình. |
content | string | Không | Nội dung chuyển khoản nguyên bản nhận từ ngân hàng, giữ nguyên không biến đổi. |
transferType | string | Không | Chiều dòng tiền: in (tiền vào) hoặc out (tiền ra). |
description | string | Có thể rỗng | Mô tả chi tiết giao dịch từ hệ thống ngân hàng. |
transferAmount | integer | Không | Số tiền giao dịch thực tế tính bằng VNĐ (luôn là số nguyên dương). |
accumulated | integer | Có thể 0 | Số dư tích lũy sau giao dịch (nếu ngân hàng hỗ trợ trả số dư). |
referenceCode | string | Có thể rỗng | Mã số bút toán / mã tham chiếu từ ngân hàng chuyển mạch (FT code). |
3 Điều kiện bắt buộc để xác nhận thành công
- HTTP Status Code: Server của bạn phải trả về HTTP
200hoặc201. - Body JSON: Nội dung trả lời phải là chuỗi JSON:
{"success": true}. - Thời gian timeout: Máy chủ phải phản hồi trong vòng tối đa 30 giây (khuyến nghị dưới 2 giây).
Xử lý chống trùng lặp (Idempotency)
Do cơ chế retry tự động khi mạng chập chờn hoặc khi quản trị viên bấm 'Gửi lại' trên bảng điều khiển, một giao dịch có thể được gửi nhiều hơn một lần. Để tránh cộng tiền 2 lần cho khách, bạn phải sử dụng trường id của payload làm ràng buộc UNIQUE trong cơ sở dữ liệu.
{
"id": 92704,
"gateway": "Vietcombank",
"transactionDate": "2026-10-31 09:22:10",
"accountNumber": "9988776655",
"subAccount": "VA001",
"code": "DH98765",
"content": "DH98765 chuyen tien mua hosting hitechcloud",
"transferType": "in",
"description": "NGUYEN VAN A chuyen tien",
"transferAmount": 500000,
"accumulated": 15500000,
"referenceCode": "FT261031998888"
}{
"id": 92705,
"gateway": "MBBank",
"transactionDate": "2026-10-31 09:25:40",
"accountNumber": "090912345678",
"subAccount": null,
"code": "INV-7788",
"content": "INV-7788 THANH TOAN CLOUD VPS",
"transferType": "in",
"description": "MBB-090912345678-TK-NAP-TIEN",
"transferAmount": 1200000,
"accumulated": 48200000,
"referenceCode": "MB26103100124"
}CREATE TABLE `hitechcloud_webhook_transactions` (
`id` BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
`htc_transaction_id` BIGINT UNSIGNED NOT NULL,
`gateway` VARCHAR(64) NOT NULL,
`transaction_date` DATETIME NOT NULL,
`account_number` VARCHAR(64) NOT NULL,
`sub_account` VARCHAR(64) NULL,
`code` VARCHAR(128) NULL,
`content` TEXT NOT NULL,
`transfer_type` ENUM('in', 'out') NOT NULL DEFAULT 'in',
`transfer_amount` BIGINT UNSIGNED NOT NULL,
`accumulated` BIGINT UNSIGNED DEFAULT 0,
`reference_code` VARCHAR(128) NULL,
`raw_payload` JSON NULL,
`created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
UNIQUE KEY `uniq_htc_trans_id` (`htc_transaction_id`),
INDEX `idx_code` (`code`),
INDEX `idx_account` (`account_number`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;<?php
$payload = json_decode(file_get_contents('php://input'), true);
$trans_id = $payload['id'];
// Chèn vào bảng với khóa UNIQUE(htc_transaction_id)
$stmt = $pdo->prepare("INSERT IGNORE INTO hitechcloud_webhook_transactions
(htc_transaction_id, gateway, transaction_date, account_number, sub_account, code, content, transfer_type, transfer_amount, accumulated, reference_code, raw_payload)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
$stmt->execute([
$trans_id,
$payload['gateway'],
$payload['transactionDate'],
$payload['accountNumber'],
$payload['subAccount'] ?? null,
$payload['code'] ?? null,
$payload['content'],
$payload['transferType'],
$payload['transferAmount'],
$payload['accumulated'] ?? 0,
$payload['referenceCode'] ?? null,
json_encode($payload)
]);
if ($stmt->rowCount() === 0) {
// Đã tồn tại giao dịch này trước đó -> phản hồi thành công ngay để dừng retry
echo json_encode(['success' => true, 'message' => 'Already processed']);
exit;
}
// Xử lý cộng tiền hoặc kích hoạt dịch vụ cho giao dịch mới...
echo json_encode(['success' => true]);