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).

Xem Markdown

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)

Payload dữ liệu giao dịch ngân hàng (Ví dụ Vietcombank)
{
  "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"
}
Payload dữ liệu giao dịch ngân hàng (Ví dụ MBBank)
{
  "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ườngKiểuCó thể null?Mô tả chi tiết
idintegerKhôngID 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.
gatewaystringKhôngTên ngân hàng phát sinh giao dịch (ví dụ: Vietcombank, MBBank, ACB, BIDV, Techcombank, VPBank...).
transactionDatestringKhôngThời gian giao dịch theo định dạng YYYY-MM-DD HH:mm:ss (múi giờ Việt Nam GMT+7).
accountNumberstringKhôngSố tài khoản ngân hàng thụ hưởng nhận tiền của bạn.
subAccountstringCó thể rỗngSố tài khoản ảo (VA) hoặc mã định danh phụ nếu giao dịch thông qua Virtual Account.
codestringCó thể nullMã 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.
contentstringKhôngNộ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.
transferTypestringKhôngChiều dòng tiền: in (tiền vào) hoặc out (tiền ra).
descriptionstringCó thể rỗngMô tả chi tiết giao dịch từ hệ thống ngân hàng.
transferAmountintegerKhôngSố tiền giao dịch thực tế tính bằng VNĐ (luôn là số nguyên dương).
accumulatedintegerCó thể 0Số dư tích lũy sau giao dịch (nếu ngân hàng hỗ trợ trả số dư).
referenceCodestringCó thể rỗngMã 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

  1. HTTP Status Code: Server của bạn phải trả về HTTP 200 hoặc 201.
  2. Body JSON: Nội dung trả lời phải là chuỗi JSON: {"success": true}.
  3. 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.

Cấu trúc bảng MySQL / MariaDB lưu trữ giao dịch Webhook
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;
Kỹ thuật INSERT IGNORE chống trùng lặp bằng PHP & MySQL
<?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]);