Transactions API

Authentication

⚠️ QUY ĐỊNH SỬ DỤNG API — ÁP DỤNG CHO MỌI AUTH METHOD

Polling liên tục = lạm dụng, áp dụng với CẢ JWT và API key:

• Treo hệ thống — gọi API liên tục tăng tải DB, ảnh hưởng toàn bộ user khác
• BeePay sẽ tự động khoá tài khoản nếu phát hiện:
  • Gọi > 1000 request/giờ
  • Polling chu kỳ < 30 giây
  • Nhiều kết nối song song bất thường
• Khoá vĩnh viễn, không hoàn phí plan còn lại

Cách đúng để nhận giao dịch realtime → dùng Webhook, KHÔNG polling.

API chỉ nên dùng cho:

• Debug / xem nhanh trong browser
• Tra cứu / báo cáo không realtime (tần suất ≥ 5 phút/lần)
• Fallback khi webhook lỗi

BeePay hỗ trợ 2 cách xác thực:

Cách 1: JWT Bearer token (ngắn hạn, 7 ngày)

Dành cho dashboard / app người dùng cuối:

# Login
curl -X POST https://id.beepay.vn/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"xxx"}'
# → { "success": true, "token": "eyJ..." }

# Dùng
curl -H "Authorization: Bearer eyJ..." \
  https://id.beepay.vn/api/transactions

Token hết hạn sau 7 ngày → login lại.

Cách 2: API Key (vĩnh viễn, cho tích hợp server)

Dành cho tích hợp tự động. Lấy API key tại id.beepay.vn/account (rotate bất cứ lúc nào, key cũ invalidate ngay).

3 cách truyền API key:

# Header (khuyến nghị production)
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://id.beepay.vn/api/transactions

# Query string (tiện test, mở trực tiếp trong browser)
https://id.beepay.vn/api/transactions?api_key=YOUR_API_KEY&page=1

Bảo mật API Key

• Không commit API key lên Git public
• Không expose trong URL share / log — production dùng header X-Api-Key
• Query ?api_key= chỉ tiện cho debug / xem nhanh trong browser
• Nếu lộ, rotate ngay trong Dashboard (key cũ invalidate)
• Lạm dụng → khoá tài khoản vĩnh viễn (không hoàn phí plan còn lại)

---

List transactions

GET /api/transactions
Authorization: Bearer <JWT>

Trả danh sách giao dịch của user đang login (filter cứng WHERE user_id = :me).

Query params

Param	Loại	Default	Mô tả
page	int	1	Phân trang (30 records/trang cố định)
bank_code	string	—	Mã ngân hàng: MB, VCB, TCB, ACB, BIDV, VIB...
type	string	—	credit (tiền vào) / debit (tiền ra)
source_type	string	—	sms / notification / email / api
date_from	YYYY-MM-DD	—	Từ ngày (so theo transaction_date)
date_to	YYYY-MM-DD	—	Đến ngày
search	string	—	Tìm trong description, transaction_ref, order_id (LIKE)

Field PII đã strip mặc định

Để tránh lộ thông tin, API mặc định không trả các field PII sau:

• description — nội dung SMS/notification gốc (có thể chứa số tài khoản, tên người chuyển)
• raw_data — JSON gốc từ device/email
• balance_after — số dư sau giao dịch
• counterpart_account — số tài khoản người gửi
• account_name — tên chủ tài khoản

Nếu bạn cần debug chi tiết, thêm query ?include_raw=1 (chỉ dùng nội bộ, không expose response cho 3rd party).

Response

{
  "success": true,
  "data": [
    {
      "id": 5669,
      "user_id": 1,
      "source_type": "notification",
      "bank_code": "VCB",
      "bank_name": "Vietcombank",
      "transaction_type": "credit",
      "amount": "2000.00",
      "currency": "VND",
      "account_number": "1022439999",
      "account_name": null,
      "transaction_ref": "6111IBT1k1X52TNM",
      "transaction_date": "2026-04-21T08:25:04.000Z",
      "counterpart_account": null,
      "counterpart_name": null,
      "counterpart_bank": null,
      "description": "Thông báo VCB Số dư TK VCB ...",
      "order_id": null,
      "webhook_status": "skipped",
      "raw_data": "{\"appName\":\"VCB Digibank\",...}",
      "created_at": "2026-04-21T08:25:04.000Z",
      "updated_at": "2026-04-21T08:25:04.000Z"
    }
  ],
  "total": 155,
  "page": 1,
  "limit": 30,
  "prefixes": ["BEEPAY", "SHOP"]
}

webhook_status values

Value	Ý nghĩa
pending	Đang chờ gửi
success	Webhook trả 2xx
failed	Webhook lỗi sau hết retry
no_match	Không match được order_id với prefix nào
skipped	Không có order_id → không bắn
plan_upgraded	Giao dịch thanh toán plan BeePay, đã upgrade xong
already_run	Đã xử lý lần trước (idempotent)

Field prefixes

Danh sách payment_prefix từ các hệ thống (connected_systems) của user. Dùng để frontend highlight match pattern.

---

Get single transaction

GET /api/transactions/:id
Authorization: Bearer <JWT>

Trả chi tiết 1 giao dịch kèm lịch sử webhook deliveries:

{
  "success": true,
  "data": {
    "id": 5669,
    "...": "...",
    "deliveries": [
      {
        "id": 999,
        "webhook_url": "https://yourshop.com/beepay-webhook",
        "http_status": 200,
        "response_body": "{\"ok\":true}",
        "attempt": 1,
        "sent_at": "2026-04-21T08:25:06.000Z"
      }
    ]
  }
}

Lỗi:

• 404 — giao dịch không tồn tại hoặc không thuộc user này

---

Retry webhook

POST /api/transactions/:id/retry
Authorization: Bearer <JWT>

Queue lại webhook cho giao dịch đã failed hoặc no_match. Trả:

{ "success": true, "message": "Đã queue retry" }

---

Delete transaction

DELETE /api/transactions/:id
Authorization: Bearer <JWT>

Xoá giao dịch + toàn bộ deliveries liên quan.

---

Ví dụ thực tế

Check giao dịch theo order_id

curl -H "Authorization: Bearer $TOKEN" \
  "https://id.beepay.vn/api/transactions?search=SHOP123"

Trả các giao dịch có SHOP123 trong description/ref/order_id. E-commerce dùng để confirm đơn hàng đã chuyển tiền chưa.

Lấy giao dịch MB tháng 4

curl -H "Authorization: Bearer $TOKEN" \
  "https://id.beepay.vn/api/transactions?bank_code=MB&date_from=2026-04-01&date_to=2026-04-30"

Mở trực tiếp trong browser (API key)

Paste vào thanh địa chỉ:

https://id.beepay.vn/api/transactions?api_key=YOUR_API_KEY

Browser hiển thị JSON ngay, không cần Postman / curl. Dùng để:

• Debug nhanh khi dev
• Tích hợp với Google Sheets (IMPORTDATA), Zapier, n8n, Make.com...

Ví dụ Google Sheets:

=IMPORTDATA("https://id.beepay.vn/api/transactions?api_key=XXX&search=SHOP123")

Polling (KHÔNG khuyến nghị)

Đừng polling liên tục

Polling API mỗi vài giây = lạm dụng, BeePay sẽ chặn + khoá tài khoản. Dùng webhook để nhận realtime thay vì polling.

Nếu phải polling (edge case): tối thiểu 5 phút/lần.

# MIN 5 PHÚT — vượt ngưỡng sẽ bị rate limit
while true; do
  curl -s -H "Authorization: Bearer $TOKEN" \
    "https://id.beepay.vn/api/transactions?page=1" \
    | jq '.data[0]'
  sleep 300
done