Beta · Đặc tả có thể còn thay đổi trước khi ra mắt chính thức. Tên miền API api.hensa.example là tạm thời. Xem thay đổi →

Yêu cầu thanh toán

Tạo mã VietQR động cho từng đơn. Khi khách chuyển đúng, Hensa tự khớp và gửi payment_request.paid.

Tạo yêu cầu thanh toán

POST/v1/payment_requests

Cần Idempotency-Key

Tạo mã VietQR động với số tiền và mã tham chiếu riêng (referenceCode). Hiển thị qrPayload thành mã QR cho khách quét – hoặc chuyển khách sang trang thanh toán Hensa ở payUrl. Mã hết hạn sau 15 phút.

Nội dung gửi lên

amountintegerbắt buộc: Số tiền cần thu, số nguyên VND, tối thiểu 1.000.
externalOrderRefstring: Mã đơn trong hệ thống của bạn (tối đa 64 ký tự). Trả lại nguyên vẹn trong webhook.

Trả về

201 · PaymentRequest

Lỗi có thể gặp

validation_error 400 Dữ liệu gửi lên không hợp lệ – xem message.
idempotency_conflict 409 Cùng Idempotency-Key nhưng nội dung khác.
no_active_bank_account 422 Cửa hàng chưa có tài khoản ngân hàng đang hoạt động.
merchant_name_required 422 Cửa hàng chưa đặt tên – đặt tên trong Dashboard trước khi tạo QR (chỉ ở chế độ thật).
plan_limit 422 Vượt giới hạn của gói hiện tại.

curl -X POST https://api.hensa.example/v1/payment_requests \
  -H "Authorization: Bearer $HENSA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amount":150000,"externalOrderRef":"DH-1024"}'

const res = await fetch('https://api.hensa.example/v1/payment_requests', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.HENSA_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "amount": 150000,
    "externalOrderRef": "DH-1024"
  })
})
const data = await res.json()

<?php
$ch = curl_init('https://api.hensa.example/v1/payment_requests');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('HENSA_API_KEY'),
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{"amount":150000,"externalOrderRef":"DH-1024"}',
]);
$data = json_decode(curl_exec($ch), true);

import os, uuid, requests

res = requests.post(
    "https://api.hensa.example/v1/payment_requests",
    headers={
        "Authorization": f"Bearer {os.environ['HENSA_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
      "amount": 150000,
      "externalOrderRef": "DH-1024"
    },
    timeout=10,
)
res.raise_for_status()

{
  "id": "prq_01JD7Q8M4K2X9V3T6B5N0R1W8Y",
  "amount": 150000,
  "amountReceived": 0,
  "currency": "VND",
  "referenceCode": "LK7F3K9",
  "status": "pending",
  "qrPayload": "00020101021238…",
  "receiver": {
    "name": "CA PHE MOC",
    "bankName": "MB Bank",
    "accountMasked": "•••• 6789"
  },
  "externalOrderRef": "DH-1024",
  "payUrl": "https://pay.hensa.vn/r/pt_7Hq2mX9vKd4RtY1nB8cZ0w",
  "expiresAt": "2026-11-03T08:15:00Z",
  "createdAt": "2026-11-03T08:00:00Z"
}

POST/v1/payment_requests

Nội dung

Dữ liệu mô phỏng · chạy ngay trong trình duyệt, không gửi đi đâu

Lấy một yêu cầu thanh toán

GET/v1/payment_requests/{id}

Dùng để kiểm tra lại trạng thái khi chưa nhận được webhook.

Tham số

idstring · đường dẫnbắt buộc: ID yêu cầu thanh toán.

Trả về

200 · PaymentRequest

Lỗi có thể gặp

not_found 404 Không tìm thấy (hoặc không thuộc cửa hàng của khóa này).

curl https://api.hensa.example/v1/payment_requests/prq_01JD7Q8M4K2X9V3T6B5N0R1W8Y \
  -H "Authorization: Bearer $HENSA_API_KEY"

const res = await fetch('https://api.hensa.example/v1/payment_requests/prq_01JD7Q8M4K2X9V3T6B5N0R1W8Y', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.HENSA_API_KEY}`,
  },
})
const data = await res.json()

<?php
$ch = curl_init('https://api.hensa.example/v1/payment_requests/prq_01JD7Q8M4K2X9V3T6B5N0R1W8Y');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('HENSA_API_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);

import os, requests

res = requests.get(
    "https://api.hensa.example/v1/payment_requests/prq_01JD7Q8M4K2X9V3T6B5N0R1W8Y",
    headers={
        "Authorization": f"Bearer {os.environ['HENSA_API_KEY']}",
    },
    timeout=10,
)
res.raise_for_status()

{
  "id": "prq_01JD7Q8M4K2X9V3T6B5N0R1W8Y",
  "amount": 150000,
  "amountReceived": 0,
  "currency": "VND",
  "referenceCode": "LK7F3K9",
  "status": "pending",
  "qrPayload": "00020101021238…",
  "receiver": {
    "name": "CA PHE MOC",
    "bankName": "MB Bank",
    "accountMasked": "•••• 6789"
  },
  "externalOrderRef": "DH-1024",
  "payUrl": "https://pay.hensa.vn/r/pt_7Hq2mX9vKd4RtY1nB8cZ0w",
  "expiresAt": "2026-11-03T08:15:00Z",
  "createdAt": "2026-11-03T08:00:00Z"
}

Liệt kê yêu cầu thanh toán

GET/v1/payment_requests

Mới nhất trước. Phân trang bằng con trỏ.

Tham số

statusstring · query: Lọc theo trạng thái.
limitinteger · query: Số bản ghi mỗi trang (1–100, mặc định 25).
cursorstring · query: Giá trị nextCursor của trang trước.

Trả về

200 · Một trang PaymentRequest và nextCursor để lấy trang tiếp theo.

Lỗi có thể gặp

validation_error 400 Dữ liệu gửi lên không hợp lệ – xem message.

curl https://api.hensa.example/v1/payment_requests?limit=25 \
  -H "Authorization: Bearer $HENSA_API_KEY"

const res = await fetch('https://api.hensa.example/v1/payment_requests?limit=25', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.HENSA_API_KEY}`,
  },
})
const data = await res.json()

<?php
$ch = curl_init('https://api.hensa.example/v1/payment_requests?limit=25');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('HENSA_API_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);

import os, requests

res = requests.get(
    "https://api.hensa.example/v1/payment_requests?limit=25",
    headers={
        "Authorization": f"Bearer {os.environ['HENSA_API_KEY']}",
    },
    timeout=10,
)
res.raise_for_status()

{
  "data": [
    {
      "id": "prq_01JD7Q8M4K2X9V3T6B5N0R1W8Y",
      "amount": 150000,
      "amountReceived": 0,
      "currency": "VND",
      "referenceCode": "LK7F3K9",
      "status": "pending",
      "qrPayload": "00020101021238…",
      "receiver": {
        "name": "CA PHE MOC",
        "bankName": "MB Bank",
        "accountMasked": "•••• 6789"
      },
      "externalOrderRef": "DH-1024",
      "payUrl": "https://pay.hensa.vn/r/pt_7Hq2mX9vKd4RtY1nB8cZ0w",
      "expiresAt": "2026-11-03T08:15:00Z",
      "createdAt": "2026-11-03T08:00:00Z"
    }
  ],
  "nextCursor": "…"
}

Đối tượng

PaymentRequest

idstringbắt buộc: ID yêu cầu thanh toán.
amountintegerbắt buộc: Số tiền cần thu, số nguyên VND.
amountReceivedintegerbắt buộc: Tổng tiền đã nhận được khớp với yêu cầu này. Nhỏ hơn amount khi partially_paid; có thể lớn hơn nếu khách chuyển thừa.
currency"VND"bắt buộc: Luôn là VND.
referenceCodestringbắt buộc: Mã tham chiếu khách ghi vào nội dung chuyển khoản – dùng để tự khớp.
statusstringbắt buộc: pending chờ trả · paid đã trả đủ · partially_paid trả thiếu · expired hết hạn · cancelled đã hủy.
qrPayloadstringbắt buộc: Chuỗi VietQR (EMVCo) – vẽ thành mã QR cho khách quét.
receiverobjectbắt buộc: Người nhận hiển thị cho khách kiểm tra trước khi chuyển.
receiver.namestringbắt buộc
receiver.bankNamestringbắt buộc
receiver.accountMaskedstringbắt buộc
externalOrderRefstring | nullbắt buộc: Mã đơn trong hệ thống của bạn (nếu gửi khi tạo).
payUrlstring | nullbắt buộc: Trang thanh toán Hensa cho yêu cầu này (QR, nút mở app ngân hàng, biên nhận). Gửi cho người mua hoặc chuyển hướng họ tới đây thay vì tự hiển thị QR. URL chứa mã bí mật – chỉ gửi cho người trả tiền. null nếu trang đã bị thu hồi.
expiresAtstringbắt buộc: Hết hạn sau 15 phút kể từ khi tạo.
createdAtstringbắt buộc: Thời điểm tạo.

{
  "id": "prq_01JD7Q8M4K2X9V3T6B5N0R1W8Y",
  "amount": 150000,
  "amountReceived": 0,
  "currency": "VND",
  "referenceCode": "LK7F3K9",
  "status": "pending",
  "qrPayload": "00020101021238…",
  "receiver": {
    "name": "CA PHE MOC",
    "bankName": "MB Bank",
    "accountMasked": "•••• 6789"
  },
  "externalOrderRef": "DH-1024",
  "payUrl": "https://pay.hensa.vn/r/pt_7Hq2mX9vKd4RtY1nB8cZ0w",
  "expiresAt": "2026-11-03T08:15:00Z",
  "createdAt": "2026-11-03T08:00:00Z"
}