Test mode

Chỉ dùng với khóa hk_test_. Mô phỏng tiền về để thử toàn bộ luồng mà không cần chuyển tiền thật.

POST/v1/test/bank_transfersMô phỏng tiền về

Mô phỏng tiền về

POST/v1/test/bank_transfers

Chỉ test modeCần Idempotency-Key

Tạo một giao dịch tiền về giả và phát sự kiện thật như production. Ghi referenceCode của một yêu cầu thanh toán vào description để thử luồng tự khớp.

Nội dung gửi lên

amountintegerbắt buộc

Số tiền giả lập, số nguyên VND, tối thiểu 1.000.

descriptionstringbắt buộc

Nội dung chuyển khoản như khách gõ. Ghi referenceCode để thử tự khớp.

counterpartyNamestring

Tên người chuyển (tùy chọn).

Trả về

201 · BankTransaction

Lỗi có thể gặp

• test_mode_only 403 Chỉ dùng được với khóa hk_test_.
• validation_error 400 Dữ liệu gửi lên không hợp lệ – xem 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()

Phản hồi 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"
}

Gọi thử

Đố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.

BankTransaction · Ví dụ

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