Beta · The spec may still change before general availability. The API domain api.hensa.example is a placeholder. See changes →

Bank transactions

Every incoming transfer to linked accounts, with its reconciliation status.

List bank transactions

GET/v1/bank_transactions

Newest first. Poll periodically (e.g. every 15 minutes) as a safety net next to webhooks.

Parameters

reconciliationstring · query: Filter by reconciliation status.
limitinteger · query: Items per page (1–100, default 25).
cursorstring · query: The nextCursor value from the previous page.

Returns

200 · A page of BankTransaction plus nextCursor for the next page.

Possible errors

validation_error 400 Invalid request data – see 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": "…"
}

Retrieve a bank transaction

GET/v1/bank_transactions/{id}

Details of one incoming transfer.

Parameters

idstring · pathrequired: Bank transaction ID.

Returns

200 · BankTransaction

Possible errors

not_found 404 Not found (or not owned by this key's store).

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"
}

Reconcile a transaction manually

POST/v1/bank_transactions/{id}/reconcile

Requires Idempotency-Key

When the customer typed a wrong description: link the transaction to a payment request, one of your order refs, or mark it "not an order".

Parameters

idstring · pathrequired: Bank transaction ID.

Request body

Send one of these shapes:

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

Returns

200 · BankTransaction

Possible errors

not_found 404 Not found (or not owned by this key's store).
already_reconciled 409 The transaction is already reconciled.
validation_error 400 Invalid request data – see 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"
}

Objects

BankTransaction

idstringrequired

Transaction ID.

bankAccountIdstringrequired

The receiving bank account.

directionstringrequired

in incoming · out outgoing.

amountintegerrequired

Amount, integer VND.

currency"VND"required

Always VND.

descriptionstringrequired

Transfer description exactly as the bank sent it.

referenceCodestring | nullrequired

Hensa reference found in the description, if any.

counterpartyNamestring | nullrequired

Sender name, when the bank provides it.

counterpartyBankstring | nullrequired

Sender bank, when available.

channelstring | nullrequired

Sales channel, when known.

Values: counter website facebook zalo delivery

reconciliationstringrequired

matched · pending needs a human · unmatched not an order.

matchedOrderRefstring | nullrequired

Matched order ref, if any.

occurredAtstringrequired

When the money landed, per the bank.

{
  "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"
}