Giao dịch

Giao dịch vào các tài khoản ngân hàng đã liên kết, cùng dữ liệu với sự kiện webhook transaction.received. Dùng để đối soát định kỳ hoặc lấy lại giao dịch khi hệ thống của bạn lỡ webhook.

Đối tượng transaction

Các trường

idstring
ID giao dịch trong BankOpenAPI, tiền tố txn_.
objectstring
Luôn là "transaction".
livemodeboolean
false với giao dịch giả lập của sandbox.
typestring
"credit" (tiền vào) hoặc "debit" (tiền ra). Sự kiện transaction.received luôn là "credit".
amountinteger
Số tiền, đơn vị VND.
currencystring
Luôn là "VND".
contentstring | null
Nội dung chuyển khoản ngân hàng gửi về. Ngân hàng thường thêm tên người chuyển, đổi chữ hoa, bỏ dấu. Có ngân hàng không gửi nội dung.
referencestring
Mã tham chiếu giao dịch phía ngân hàng.
receivingNumberstring | null
Tài khoản nhận báo có: virtual account hoặc số tài khoản.
paymentRequestIdstring | null
ID yêu cầu thanh toán đã khớp với giao dịch, null nếu không khớp yêu cầu nào.
notifiedAtstring | null
Thời điểm BankOpenAPI đã báo có giao dịch (webhook, kênh báo có). null nếu chưa báo, ví dụ tiền về lúc báo có tạm dừng.
bankAccountobject
Tài khoản nhận tiền: id, bank.bin, bank.name, accountNumber, label.
transactedAtstring
Thời điểm giao dịch theo ngân hàng.
createdAtstring
Thời điểm BankOpenAPI ghi nhận giao dịch.

Đối tượng transaction

{
  "id": "txn_5Rk8Wm2Qp7Xn4Bv9Ls3Ht6Jc",
  "object": "transaction",
  "livemode": true,
  "type": "credit",
  "amount": 150000,
  "currency": "VND",
  "content": "NGUYEN VAN BINH chuyen tien TT7K3M9Q",
  "reference": "FT25309871234567",
  "receivingNumber": "0123456789",
  "paymentRequestId": "pr_3fK9mQ2xLwA7nB5vR8tY1cZd",
  "notifiedAt": null,
  "bankAccount": {
    "id": "ba_8Hn2PqR5sT7vW9xY3zA4bC6d",
    "bank": {
      "bin": "970422",
      "name": "MB Bank"
    },
    "accountNumber": "0123456789",
    "label": "MB Bank •••• 6789"
  },
  "transactedAt": "2026-11-05T03:24:50.000Z",
  "createdAt": "2026-11-05T03:24:51.000Z"
}

Liệt kê giao dịch

GET/v1/transactions

Trả danh sách mới nhất trước (theo transactedAt). Còn trang sau thì hasMore là true: gọi lại vớistarting_after là id của phần tử cuối.

Tham số query

bank_accountstringkhông bắt buộc
Chỉ lấy giao dịch của một tài khoản ngân hàng (ID ba_…).
typeenumkhông bắt buộc
credit (tiền vào) hoặc debit (tiền ra).
fromstringkhông bắt buộc
Từ thời điểm (ISO 8601), tính theo transactedAt.
tostringkhông bắt buộc
Đến thời điểm (ISO 8601).
limitintegerkhông bắt buộc
Số phần tử mỗi trang, 1–100, mặc định 50.
starting_afterstringkhông bắt buộc
ID của phần tử cuối ở trang trước, để lấy trang tiếp theo.

Lỗi

400 INVALID_CURSOR
starting_after không phải ID giao dịch của bạn.

GET /v1/transactions

curl "https://app.bankopenapi.com/api/v1/transactions?type=credit&from=2026-11-01T00%3A00%3A00%2B07%3A00&limit=20" \
  -H "Authorization: Bearer $BANKOPENAPI_API_KEY"

const res = await fetch("https://app.bankopenapi.com/api/v1/transactions?type=credit&from=2026-11-01T00%3A00%3A00%2B07%3A00&limit=20", {
  headers: {
    Authorization: `Bearer ${process.env.BANKOPENAPI_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);

<?php
$ch = curl_init('https://app.bankopenapi.com/api/v1/transactions?type=credit&from=2026-11-01T00%3A00%3A00%2B07%3A00&limit=20');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('BANKOPENAPI_API_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status >= 400) {
    throw new Exception($data['error']['code'] . ': ' . $data['error']['message']);
}
print_r($data);

import os
import requests

res = requests.get(
    "https://app.bankopenapi.com/api/v1/transactions",
    headers={"Authorization": f"Bearer {os.environ['BANKOPENAPI_API_KEY']}"},
    params={
        "type": "credit",
        "from": "2026-11-01T00:00:00+07:00",
        "limit": 20,
    },
    timeout=15,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)

Response 200

{
  "object": "list",
  "data": [
    {
      "id": "txn_5Rk8Wm2Qp7Xn4Bv9Ls3Ht6Jc",
      "object": "transaction",
      "livemode": true,
      "type": "credit",
      "amount": 150000,
      "currency": "VND",
      "content": "NGUYEN VAN BINH chuyen tien TT7K3M9Q",
      "reference": "FT25309871234567",
      "receivingNumber": "0123456789",
      "paymentRequestId": "pr_3fK9mQ2xLwA7nB5vR8tY1cZd",
      "notifiedAt": null,
      "bankAccount": {
        "id": "ba_8Hn2PqR5sT7vW9xY3zA4bC6d",
        "bank": {
          "bin": "970422",
          "name": "MB Bank"
        },
        "accountNumber": "0123456789",
        "label": "MB Bank •••• 6789"
      },
      "transactedAt": "2026-11-05T03:24:50.000Z",
      "createdAt": "2026-11-05T03:24:51.000Z"
    }
  ],
  "hasMore": false
}

Xem một giao dịch

GET/v1/transactions/:id

Trả đối tượng transaction theo ID (tiền tố txn_), vd. ID lấy từ webhook.

Lỗi

404 NOT_FOUND
Không có giao dịch với ID này trong tài khoản của bạn.

GET /v1/transactions/:id

curl https://app.bankopenapi.com/api/v1/transactions/txn_5Rk8Wm2Qp7Xn4Bv9Ls3Ht6Jc \
  -H "Authorization: Bearer $BANKOPENAPI_API_KEY"

const res = await fetch("https://app.bankopenapi.com/api/v1/transactions/txn_5Rk8Wm2Qp7Xn4Bv9Ls3Ht6Jc", {
  headers: {
    Authorization: `Bearer ${process.env.BANKOPENAPI_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);

<?php
$ch = curl_init('https://app.bankopenapi.com/api/v1/transactions/txn_5Rk8Wm2Qp7Xn4Bv9Ls3Ht6Jc');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('BANKOPENAPI_API_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status >= 400) {
    throw new Exception($data['error']['code'] . ': ' . $data['error']['message']);
}
print_r($data);

import os
import requests

res = requests.get(
    "https://app.bankopenapi.com/api/v1/transactions/txn_5Rk8Wm2Qp7Xn4Bv9Ls3Ht6Jc",
    headers={"Authorization": f"Bearer {os.environ['BANKOPENAPI_API_KEY']}"},
    timeout=15,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)

Response 200

{
  "id": "txn_5Rk8Wm2Qp7Xn4Bv9Ls3Ht6Jc",
  "object": "transaction",
  "livemode": true,
  "type": "credit",
  "amount": 150000,
  "currency": "VND",
  "content": "NGUYEN VAN BINH chuyen tien TT7K3M9Q",
  "reference": "FT25309871234567",
  "receivingNumber": "0123456789",
  "paymentRequestId": "pr_3fK9mQ2xLwA7nB5vR8tY1cZd",
  "notifiedAt": null,
  "bankAccount": {
    "id": "ba_8Hn2PqR5sT7vW9xY3zA4bC6d",
    "bank": {
      "bin": "970422",
      "name": "MB Bank"
    },
    "accountNumber": "0123456789",
    "label": "MB Bank •••• 6789"
  },
  "transactedAt": "2026-11-05T03:24:50.000Z",
  "createdAt": "2026-11-05T03:24:51.000Z"
}

Response 404

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Không tìm thấy giao dịch."
  }
}

Khóa chỉ đọc gọi được các endpoint này.

Giao dịch

Đối tượng transaction

Các trường

Liệt kê giao dịch

Tham số query

Lỗi

Xem một giao dịch

Lỗi

Bắt đầu với BankOpenAPI