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 →

Giao dịch ngân hàng

Mọi khoản tiền vào tài khoản đã liên kết, kèm trạng thái đối soát.

Liệt kê giao dịch

GET/v1/bank_transactions

Mới nhất trước. Dùng định kỳ (vd. mỗi 15 phút) làm lưới an toàn bên cạnh webhook.

Tham số

reconciliationstring · query: Lọc theo trạng thái đối soát.
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 BankTransaction 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/bank_transactions?limit=25 \
  -H "Authorization: Bearer $HENSA_API_KEY"

const res = await fetch('https://api.hensa.example/v1/bank_transactions?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/bank_transactions?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/bank_transactions?limit=25",
    headers={
        "Authorization": f"Bearer {os.environ['HENSA_API_KEY']}",
    },
    timeout=10,
)
res.raise_for_status()

{
  "data": [
    {
      "id": "btx_01JD7QA9F3W5Y7Z1B3D5G7J9KM",
      "bankAccountId": "bac_01JD5A2B4C6D8E0F2G4H6J8K0M",
      "direction": "in",
      "amount": 150000,
      "currency": "VND",
      "description": "LK7F3K9 thanh toan don hang",
      "referenceCode": "LK7F3K9",
      "counterpartyName": "NGUYEN VAN AN",
      "counterpartyBank": "VCB",
      "channel": "website",
      "reconciliation": "matched",
      "matchedOrderRef": "DH-1024",
      "occurredAt": "2026-11-03T08:03:10Z"
    }
  ],
  "nextCursor": "…"
}

Lấy một giao dịch

GET/v1/bank_transactions/{id}

Chi tiết một khoản tiền vào.

Tham số

idstring · đường dẫnbắt buộc: ID giao dịch.

Trả về

200 · BankTransaction

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/bank_transactions/btx_01JD7QA9F3W5Y7Z1B3D5G7J9KM \
  -H "Authorization: Bearer $HENSA_API_KEY"

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

<?php
$ch = curl_init('https://api.hensa.example/v1/bank_transactions/btx_01JD7QA9F3W5Y7Z1B3D5G7J9KM');
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/bank_transactions/btx_01JD7QA9F3W5Y7Z1B3D5G7J9KM",
    headers={
        "Authorization": f"Bearer {os.environ['HENSA_API_KEY']}",
    },
    timeout=10,
)
res.raise_for_status()

{
  "id": "btx_01JD7QA9F3W5Y7Z1B3D5G7J9KM",
  "bankAccountId": "bac_01JD5A2B4C6D8E0F2G4H6J8K0M",
  "direction": "in",
  "amount": 150000,
  "currency": "VND",
  "description": "LK7F3K9 thanh toan don hang",
  "referenceCode": "LK7F3K9",
  "counterpartyName": "NGUYEN VAN AN",
  "counterpartyBank": "VCB",
  "channel": "website",
  "reconciliation": "matched",
  "matchedOrderRef": "DH-1024",
  "occurredAt": "2026-11-03T08:03:10Z"
}

Khớp giao dịch thủ công

POST/v1/bank_transactions/{id}/reconcile

Cần Idempotency-Key

Khi khách ghi sai nội dung chuyển khoản: gắn giao dịch với một yêu cầu thanh toán, một mã đơn của bạn, hoặc đánh dấu "không phải đơn".

Tham số

idstring · đường dẫnbắt buộc: ID giao dịch.

Nội dung gửi lên

Gửi một trong các dạng sau:

{"paymentRequestId":"…"}
{"orderRef":"…"}
{"notAnOrder":true}

Trả về

200 · BankTransaction

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).
already_reconciled 409 Giao dịch đã được khớp trước đó.
validation_error 400 Dữ liệu gửi lên không hợp lệ – xem message.

curl -X POST https://api.hensa.example/v1/bank_transactions/btx_01JD7QA9F3W5Y7Z1B3D5G7J9KM/reconcile \
  -H "Authorization: Bearer $HENSA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"paymentRequestId":"prq_01JD7Q8M4K2X9V3T6B5N0R1W8Y"}'

const res = await fetch('https://api.hensa.example/v1/bank_transactions/btx_01JD7QA9F3W5Y7Z1B3D5G7J9KM/reconcile', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.HENSA_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "paymentRequestId": "prq_01JD7Q8M4K2X9V3T6B5N0R1W8Y"
  })
})
const data = await res.json()

<?php
$ch = curl_init('https://api.hensa.example/v1/bank_transactions/btx_01JD7QA9F3W5Y7Z1B3D5G7J9KM/reconcile');
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 => '{"paymentRequestId":"prq_01JD7Q8M4K2X9V3T6B5N0R1W8Y"}',
]);
$data = json_decode(curl_exec($ch), true);

import os, uuid, requests

res = requests.post(
    "https://api.hensa.example/v1/bank_transactions/btx_01JD7QA9F3W5Y7Z1B3D5G7J9KM/reconcile",
    headers={
        "Authorization": f"Bearer {os.environ['HENSA_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
      "paymentRequestId": "prq_01JD7Q8M4K2X9V3T6B5N0R1W8Y"
    },
    timeout=10,
)
res.raise_for_status()

{
  "id": "btx_01JD7QA9F3W5Y7Z1B3D5G7J9KM",
  "bankAccountId": "bac_01JD5A2B4C6D8E0F2G4H6J8K0M",
  "direction": "in",
  "amount": 150000,
  "currency": "VND",
  "description": "LK7F3K9 thanh toan don hang",
  "referenceCode": "LK7F3K9",
  "counterpartyName": "NGUYEN VAN AN",
  "counterpartyBank": "VCB",
  "channel": "website",
  "reconciliation": "matched",
  "matchedOrderRef": "DH-1024",
  "occurredAt": "2026-11-03T08:03:10Z"
}

POST/v1/bank_transactions//reconcile

Nội dung

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

Đối tượng

BankTransaction

idstringbắt buộc

ID giao dịch.

bankAccountIdstringbắt buộc

Tài khoản ngân hàng nhận tiền.

directionstringbắt buộc

in tiền vào · out tiền ra.

amountintegerbắt buộc

Số tiền, số nguyên VND.

currency"VND"bắt buộc

Luôn là VND.

descriptionstringbắt buộc

Nội dung chuyển khoản đúng như ngân hàng gửi.

referenceCodestring | nullbắt buộc

Mã tham chiếu Hensa tìm thấy trong nội dung (nếu có).

counterpartyNamestring | nullbắt buộc

Tên người chuyển (nếu ngân hàng cung cấp).

counterpartyBankstring | nullbắt buộc

Ngân hàng người chuyển (nếu có).

channelstring | nullbắt buộc

Kênh bán gắn với giao dịch (nếu biết).

Giá trị: counter website facebook zalo delivery

reconciliationstringbắt buộc

matched đã khớp · pending cần xử lý · unmatched không phải đơn.

matchedOrderRefstring | nullbắt buộc

Mã đơn đã khớp (nếu có).

occurredAtstringbắt buộc

Thời điểm tiền vào tài khoản theo ngân hàng.

{
  "id": "btx_01JD7QA9F3W5Y7Z1B3D5G7J9KM",
  "bankAccountId": "bac_01JD5A2B4C6D8E0F2G4H6J8K0M",
  "direction": "in",
  "amount": 150000,
  "currency": "VND",
  "description": "LK7F3K9 thanh toan don hang",
  "referenceCode": "LK7F3K9",
  "counterpartyName": "NGUYEN VAN AN",
  "counterpartyBank": "VCB",
  "channel": "website",
  "reconciliation": "matched",
  "matchedOrderRef": "DH-1024",
  "occurredAt": "2026-11-03T08:03:10Z"
}