Tổng quan

Hensa Connect API giúp hệ thống của bạn biết ngay khi tiền về tài khoản ngân hàng của cửa hàng – không cần nhân viên mở app ngân hàng kiểm tra, không cần đối chiếu sao kê cuối ngày.

Hoạt động thế nào

1. Bạn tạo một yêu cầu thanh toán cho từng đơn → Hensa trả về mã VietQR động với số tiền và mã tham chiếu riêng (vd. LK7F3K9).
2. Khách quét mã bằng bất kỳ app ngân hàng nào và chuyển khoản – tiền vào thẳng tài khoản của cửa hàng, Hensa không giữ tiền.
3. Hensa nhận biến động số dư, khớp giao dịch với yêu cầu thanh toán qua mã tham chiếu.
4. Hensa gửi webhook có chữ ký payment_request.paid tới máy chủ của bạn – bạn xác nhận đơn, giao hàng.

Khách ghi sai nội dung? Giao dịch vẫn đến qua bank_transaction.created với trạng thái pending – bạn (hoặc nhân viên trong Dashboard) khớp thủ công.

Các đối tượng chính

Đối tượng	Tiền tố ID	Là gì
Yêu cầu thanh toán	prq_	Một mã VietQR động cho một đơn, có hạn 15 phút
Giao dịch ngân hàng	btx_	Một khoản tiền vào tài khoản đã liên kết
Endpoint webhook	whe_	Một URL của bạn nhận sự kiện
Sự kiện	evt_	Một thông báo gửi tới webhook (có thể gửi lặp – hãy xử lý chống trùng)

Quy ước chung

• URL gốc: https://api.hensa.example/v1 (tạm thời – xem Phiên bản API).
• Xác thực: Authorization: Bearer hk_test_… hoặc hk_live_… – xem Xác thực.
• Tiền: số nguyên VND, không có phần thập phân: 150000 = 150.000 ₫.
• Thời gian: ISO 8601 có múi giờ, vd. 2026-11-03T08:00:00Z.
• Tạo mới / chạm tới tiền: bắt buộc header Idempotency-Key.

Bắt đầu nhanh (5 phút)Tạo mã QR, mô phỏng tiền về, nhận webhook đầu tiên.

WebhookSự kiện, chữ ký, thử lại, gửi lại.

API ReferenceMọi endpoint, trường, lỗi – sinh tự động từ contract.

Test modeThử toàn bộ luồng mà không cần tiền thật.