Test mode

Only with hk_test_ keys. Simulate incoming money to exercise the whole flow without real transfers.

POST/v1/test/bank_transfersSimulate an incoming transfer

Simulate an incoming transfer

POST/v1/test/bank_transfers

Test mode onlyRequires Idempotency-Key

Creates a fake incoming transfer and emits real events exactly like production. Put a payment request's referenceCode in description to test auto-matching.

Request body

amountintegerrequired

Simulated amount, integer VND, minimum 1,000.

descriptionstringrequired

Transfer description as typed by the customer. Include a referenceCode to test auto-matching.

counterpartyNamestring

Sender name (optional).

Returns

201 · BankTransaction

Possible errors

• test_mode_only 403 Only available with hk_test_ keys.
• validation_error 400 Invalid request data – see message.

cURL

curl -X POST https://api.hensa.example/v1/test/bank_transfers \
  -H "Authorization: Bearer $HENSA_TEST_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amount":150000,"description":"LK7F3K9 thanh toan don hang","counterpartyName":"NGUYEN VAN AN"}'

Node.js

const res = await fetch('https://api.hensa.example/v1/test/bank_transfers', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.HENSA_TEST_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "amount": 150000,
    "description": "LK7F3K9 thanh toan don hang",
    "counterpartyName": "NGUYEN VAN AN"
  })
})
const data = await res.json()

PHP

<?php
$ch = curl_init('https://api.hensa.example/v1/test/bank_transfers');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('HENSA_TEST_KEY'),
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{"amount":150000,"description":"LK7F3K9 thanh toan don hang","counterpartyName":"NGUYEN VAN AN"}',
]);
$data = json_decode(curl_exec($ch), true);

Python

import os, uuid, requests

res = requests.post(
    "https://api.hensa.example/v1/test/bank_transfers",
    headers={
        "Authorization": f"Bearer {os.environ['HENSA_TEST_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
      "amount": 150000,
      "description": "LK7F3K9 thanh toan don hang",
      "counterpartyName": "NGUYEN VAN AN"
    },
    timeout=10,
)
res.raise_for_status()

Response 201

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

Try it

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.

BankTransaction · Example

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