Sandbox — Môi trường thử nghiệm Webhook

Môi trường thử nghiệm (sandbox) webhook HiTechCloud Pay: chạy thử trọn luồng bằng giao dịch giả lập trước khi đưa endpoint lên môi trường thật với tiền thật.

Xem Markdown

Sandbox là môi trường chạy độc lập cho phép bạn giả lập giao dịch tiền về mà không cần chuyển khoản thật. Mọi webhook bắn từ Sandbox đều có dữ liệu mô phỏng và không ảnh hưởng tới số dư hay đối soát trên tài khoản ngân hàng thật.

Luôn hoàn tất tích hợp và kiểm thử trên Sandbox trước khi bật webhook Production. Giao dịch Sandbox được gắn cờ test: true trong payload để bạn dễ phân biệt.

Phân biệt Sandbox và Production

Tiêu chíSandboxProduction
Bảng điều khiểnhttps://sandbox.my.hitechcloud.vnhttps://my.hitechcloud.vn
Nguồn giao dịchGiao dịch giả lập do bạn tự tạoBiến động số dư ngân hàng thật
Số tiềnGiá trị mô phỏng, không có tiền thậtSố tiền thực tế bằng VNĐ
Khóa bí mật (SECRET_KEY)Secret riêng chỉ dùng cho SandboxSecret riêng cho Production
test trong payloadtruefalse
Giới hạnTạo giao dịch giả lập không giới hạnTheo lưu lượng giao dịch thật

Bước 1: Kích hoạt môi trường Sandbox

  1. Đăng nhập https://sandbox.my.hitechcloud.vn bằng chính tài khoản HiTechCloud của bạn.
  2. Vào mục Webhooks → Thêm Webhook và điền URL endpoint (có thể là địa chỉ local tunnel như ngrok).
  3. Sao chép Sandbox Secret Key riêng trong trang cấu hình webhook — đây là khóa dùng để ký HMAC cho mọi webhook Sandbox.
  4. Lưu khóa này vào biến môi trường HITECHCLOUD_WEBHOOK_SECRET_SANDBOX ở máy chủ của bạn.

Bước 2: Tạo giao dịch giả lập

Bạn có thể tạo giao dịch giả lập ngay trên bảng điều khiển Sandbox (nút Giả lập giao dịch) hoặc gọi API để tự động hóa kịch bản kiểm thử.

POSThttps://sandbox.my.hitechcloud.vn/api/v1/webhooks/simulate

API này đẩy một giao dịch giả lập vào hàng đợi; HiTechCloud Pay sẽ bắn webhook tới endpoint của bạn giống hệt Production.

Headers
Body
Payload webhook giả lập mà endpoint của bạn nhận được
{
  "id": 10000123,
  "gateway": "Vietcombank",
  "transactionDate": "2026-10-31 10:05:00",
  "accountNumber": "9988776655",
  "subAccount": null,
  "code": "DH98765",
  "content": "DH98765 thanh toan test",
  "transferType": "in",
  "description": "SANDBOX GIAO DICH GIA LAP",
  "transferAmount": 500000,
  "accumulated": 0,
  "referenceCode": "SBX261031000123",
  "test": true
}
Chữ ký HMAC của webhook Sandbox được tạo bằng Sandbox Secret Key (khác với Production). Nếu endpoint của bạn dùng chung một biến môi trường, hãy chọn secret theo cờ test hoặc theo cấu hình môi trường đang chạy.

Bước 3: Chuyển lên Production

  1. Xác nhận endpoint trả về {"success": true} với mọi kịch bản giả lập (tiền vào, tiền ra, trùng lặp, chữ ký sai).
  2. Đăng ký lại webhook trên https://my.hitechcloud.vn với URL Production (bắt buộc HTTPS).
  3. Thay secret trong máy chủ sang Production Secret Key và bật xác thực HMAC-SHA256.
  4. Thực hiện một giao dịch thật giá trị nhỏ (ví dụ 10.000 VNĐ) để kiểm chứng lần cuối.