API Reference

Mọi trang tham chiếu được sinh từ contract mà máy chủ Hensa dùng để kiểm tra request – tài liệu và API không thể nói khác nhau.

URL gốc

https://api.hensa.example/v1

Tên miền chính thức sẽ được công bố khi ra mắt; đường dẫn và cấu trúc giữ nguyên.

Request

Xác thực	Authorization: Bearer hk_test_… hoặc hk_live_… – xem Xác thực
Định dạng	JSON (Content-Type: application/json), mã hóa UTF-8
Tạo mới / chạm tới tiền	Header Idempotency-Key bắt buộc – xem Idempotency
Phiên bản	Header Hensa-Version: 2026-11-01 (tùy chọn) – xem Phiên bản API
Tiền	Số nguyên VND: 150000 = 150.000 ₫
Thời gian	ISO 8601 có múi giờ
ID	Chuỗi có tiền tố: prq_, btx_, whe_, whd_, evt_
Danh sách	Phân trang con trỏ: limit + cursor → nextCursor – xem Phân trang
Lỗi	{ "error": { "code", "message", "request_id" } } – xem Lỗi

Tài nguyên

Yêu cầu thanh toánTạo, lấy và liệt kê mã VietQR động.

Giao dịch ngân hàngTiền vào tài khoản đã liên kết và đối soát thủ công.

Quản lý webhookĐăng ký URL, đổi secret, xem và gửi lại sự kiện.

Test modeMô phỏng tiền về bằng khóa thử nghiệm.

Sự kiện webhook và cấu trúc payload: Webhook.

Đặc tả OpenAPI

Tải đặc tả OpenAPI 3.1 để nhập vào Postman, Insomnia, Bruno hoặc sinh client cho ngôn ngữ của bạn:

• openapi.vi.json – mô tả tiếng Việt
• openapi.en.json – mô tả tiếng Anh