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.
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.
test: true trong payload để bạn dễ phân biệt.Phân biệt Sandbox và Production
| Tiêu chí | Sandbox | Production |
|---|---|---|
| Bảng điều khiển | https://sandbox.my.hitechcloud.vn | https://my.hitechcloud.vn |
| Nguồn giao dịch | Giao dịch giả lập do bạn tự tạo | Biến động số dư ngân hàng thật |
| Số tiền | Giá trị mô phỏng, không có tiền thật | Số tiền thực tế bằng VNĐ |
| Khóa bí mật (SECRET_KEY) | Secret riêng chỉ dùng cho Sandbox | Secret riêng cho Production |
test trong payload | true | false |
| Giới hạn | Tạo giao dịch giả lập không giới hạn | Theo lưu lượng giao dịch thật |
Bước 1: Kích hoạt môi trường Sandbox
- Đăng nhập
https://sandbox.my.hitechcloud.vnbằng chính tài khoản HiTechCloud của bạn. - Vào mục Webhooks → Thêm Webhook và điền URL endpoint (có thể là địa chỉ local tunnel như ngrok).
- 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.
- 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ử.
https://sandbox.my.hitechcloud.vn/api/v1/webhooks/simulateKiểm thử tại chỗ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.
{
"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
}test hoặc theo cấu hình môi trường đang chạy.Bước 3: Chuyển lên Production
- 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). - Đăng ký lại webhook trên
https://my.hitechcloud.vnvới URL Production (bắt buộc HTTPS). - Thay secret trong máy chủ sang Production Secret Key và bật xác thực HMAC-SHA256.
- 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.
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.
test: true trong payload để bạn dễ phân biệt.Phân biệt Sandbox và Production
| Tiêu chí | Sandbox | Production |
|---|---|---|
| Bảng điều khiển | https://sandbox.my.hitechcloud.vn | https://my.hitechcloud.vn |
| Nguồn giao dịch | Giao dịch giả lập do bạn tự tạo | Biến động số dư ngân hàng thật |
| Số tiền | Giá trị mô phỏng, không có tiền thật | Số tiền thực tế bằng VNĐ |
| Khóa bí mật (SECRET_KEY) | Secret riêng chỉ dùng cho Sandbox | Secret riêng cho Production |
test trong payload | true | false |
| Giới hạn | Tạo giao dịch giả lập không giới hạn | Theo lưu lượng giao dịch thật |
Bước 1: Kích hoạt môi trường Sandbox
- Đăng nhập
https://sandbox.my.hitechcloud.vnbằng chính tài khoản HiTechCloud của bạn. - Vào mục Webhooks → Thêm Webhook và điền URL endpoint (có thể là địa chỉ local tunnel như ngrok).
- 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.
- 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ử.
https://sandbox.my.hitechcloud.vn/api/v1/webhooks/simulateKiểm thử tại chỗ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.
test hoặc theo cấu hình môi trường đang chạy.Bước 3: Chuyển lên Production
- 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). - Đăng ký lại webhook trên
https://my.hitechcloud.vnvới URL Production (bắt buộc HTTPS). - Thay secret trong máy chủ sang Production Secret Key và bật xác thực HMAC-SHA256.
- 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.
{
"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
}