Apinganhang API v1

REST API xác thực giao dịch ngân hàng, quản lý tài khoản, kết nối OTP, và tích hợp cổng thanh toán tự động.

Xác thực

Tất cả endpoint (trừ ping.php) yêu cầu header Authorization: Bearer <token>.

Token nhận được từ endpoint POST /auth/login.php. Token không có thời hạn hết hạn — cookie được duy trì lâu dài trừ khi user đăng xuất hoặc admin reset token.

Mã lỗi & Response format

Mọi response đều là JSON với field success (boolean).

Rate Limit

Chưa áp dụng rate limiting cứng. Khuyến nghị polling giao dịch tối đa mỗi 10–30 giây. Bank cron cập nhật mỗi 1 phút.

Số dư ngân hàng — GET /accounts/balances.php

Endpoint gọn dành cho đối tác (site cá cược, cổng nạp...) lấy nhanh số dư các tài khoản ngân hàng của mình, phục vụ việc tự chọn ngân hàng công ty nhận tiền — ví dụ: luôn ưu tiên ngân hàng đang có số dư thấp nhất để dàn đều dòng tiền.

Xác thực

Bearer token như mọi endpoint /api/v1 khác: Authorization: Bearer <token>. Không có token → HTTP 401.

Query params (tất cả tuỳ chọn)

Ví dụ

curl -H "Authorization: Bearer $TOKEN" \
  "https://client.apinganhang.net/api/v1/accounts/balances.php?accounts=ACB:68868983,ACB:22769257,BIDV:96247TPH8866&pick=lowest"

{
  "success": true,
  "message": "Balances loaded",
  "data": {
    "items": [
      {
        "id": 80,
        "source_table": "account_acb",
        "bank_code": "ACB",
        "account_number": "68868983",
        "holder_name": "TUNG VU THANH",
        "active": true,
        "connected": true,
        "need_relogin": false,
        "last_error": "",
        "sync_source": "direct",
        "balance": 31321,
        "balance_source": "last_transaction",
        "transaction_count": 223,
        "last_transaction_at": 1787032562
      }
    ],
    "count": 3,
    "selected": { "bank_code": "ACB", "account_number": "68868983", "balance": 31321 },
    "generated_at": 1787000000
  }
}

Ý nghĩa balance_source

Use case: chọn ngân hàng công ty có số dư thấp nhất

1. Site lấy danh sách ngân hàng công ty đang mở trong admin của mình.
2. Gọi balances.php?accounts=<danh sách BANK:STK>&pick=lowest.
3. Dùng data.selected làm ngân hàng nhận tiền cho lệnh nạp; nếu API lỗi/timeout thì fallback chọn ngẫu nhiên như cũ.
4. Nên cache kết quả 30–60 giây phía site — cron ngân hàng cũng chỉ cập nhật mỗi 1 phút.

USDT Crypto — Tổng quan

Hệ thống hỗ trợ nhận tiền tự động qua 2 mạng USDT: TRC20 (Tron) và BEP20 (BSC). Cron job chạy mỗi 1 phút để quét giao dịch mới, quy đổi sang VND và ghi vào logs_history.

Tỷ giá USDT/VND — Binance P2P

Tỷ giá được lấy tự động từ Binance P2P API — không cần cấu hình thủ công:

1. Gọi API P2P Binance, lấy top 10 merchant đang đăng bán USDT nhận VND (SELL order, amount ≥ 10,000,000 VND).
2. Tính trung bình cộng các mức giá (chỉ lấy mức ≥ 20,000 VND/USDT để loại outlier).
3. Kết quả làm tròn xuống (floor) → ví dụ: 25,740 VND/USDT.
4. Cache 5 phút — tự refresh mỗi lần cache hết hạn.
5. Fallback 25,000 VND/USDT nếu Binance không phản hồi.

Luồng tổng quát

1. User thêm địa chỉ ví USDT vào hệ thống tại app.apinganhang.net → Tài khoản → Thêm ví USDT.
2. Cron job chạy mỗi 1 phút, gọi API blockchain để lấy giao dịch 14 ngày gần nhất.
3. Lọc chỉ giao dịch vào ví (to === địa_chỉ_ví), bỏ qua giao dịch ra.
4. Dedup theo tx_hash + method + ABS(amount VND) — mỗi giao dịch chỉ ghi 1 lần.
5. Quy đổi USDT → VND theo tỷ giá Binance P2P hiện tại, ghi vào logs_history.
6. Gửi thông báo Telegram + dispatch webhook transaction.received về site.

USDT TRC20 — Tron Network

Cấu hình TronGrid API Key

TronGrid miễn phí nhưng giới hạn rate nếu không có API key. Khi thiếu key, cron sẽ gặp lỗi "Không lấy được lịch sử từ TronGrid".

1. Đăng ký tại trongrid.io → lấy API key miễn phí.
2. Vào app.apinganhang.net → Cài đặt → nhập TronGrid API Key.
3. Hệ thống tự thêm header TRON-PRO-API-KEY: <key> vào mọi request TronGrid.

Thêm ví USDT Tron

Gọi API POST /accounts/store.php (hoặc dùng giao diện app) với:

{
  "bank_code": "TRON USDT",
  "account_number": "THa1vvKpShrkGNo2XjZsDVKzQdHwSMjfCp",
  "account_name": "Ví USDT Tron chính"
}

Response giao dịch USDT Tron (trong logs_history)

{
  "id": 1234,
  "bank":        "TRON USDT",
  "trans_id":    "abc123def456...",
  "amount":      2574000,
  "usdt_amount": 100.0,
  "type":        "in",
  "description": "Nhận 100 USDT (2,574,000 VND) từ TXabc...",
  "account":     "THa1vvKpShrkGNo2XjZsDVKzQdHwSMjfCp",
  "transaction_time": 1751234567,
  "status":      "SUCCESS"
}

USDT BEP20 — Binance Smart Chain

Cấu hình BscScan API Key (bắt buộc)

BEP20 bắt buộc phải có BscScan API key — không có key sẽ không lấy được giao dịch.

1. Đăng ký tại bscscan.com/myapikey → tạo API key miễn phí.
2. Khi thêm ví BEP20 tại app.apinganhang.net, nhập API key vào trường Password / API Key.
3. API key được mã hoá AES-256-GCM trước khi lưu DB.

Thêm ví USDT BEP20

{
  "bank_code":      "BEP20 USDT",
  "account_number": "0xAbCd1234...",
  "account_name":   "Ví USDT BEP20 chính",
  "password":       "<BscScan API Key>"
}

Response giao dịch USDT BEP20 (trong logs_history)

{
  "id": 5678,
  "bank":        "BEP20 USDT",
  "trans_id":    "0xabc123...",
  "amount":      2574000,
  "usdt_amount": 100.0,
  "type":        "in",
  "description": "Nhận 100 USDT (2,574,000 VND) từ 0xsender...",
  "account":     "0xAbCd1234...",
  "transaction_time": 1751234567,
  "status":      "SUCCESS"
}

Webhook — Giao dịch USDT

Khi cron phát hiện giao dịch USDT mới hợp lệ, hệ thống dispatch event transaction.received về webhook URL đã cấu hình. Payload tương tự giao dịch ngân hàng nhưng bổ sung field usdt_amount:

Ví dụ payload webhook USDT Tron

{
  "event":        "transaction.received",
  "bank":         "TRON USDT",
  "trans_id":     "f3a4b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5",
  "amount":       2574000,
  "usdt_amount":  100.0,
  "type":         "in",
  "description":  "Nhận 100 USDT (2,574,000 VND) từ TXsenderAddress...",
  "account":      "THa1vvKpShrkGNo2XjZsDVKzQdHwSMjfCp",
  "balance_after": null
}

Xác minh thanh toán USDT

Luồng xác minh cho site nhận USDT — so sánh usdt_amount (không phải amount VND, vì tỷ giá biến động):

1. Tạo đơn, hiển thị địa chỉ ví USDT + số USDT cần chuyển (ví dụ: 100 USDT).
2. Khách gửi đúng số USDT đến địa chỉ ví trên Tron/BSC.
3. Webhook nhận event transaction.received, kiểm tra usdt_amount === 100 và bank === "TRON USDT".
4. Hoặc polling: GET /transactions/index.php?bank=TRON+USDT&limit=10, tìm usdt_amount khớp.

BTC / ETH — Tổng quan

Ngoài USDT (TRC20/BEP20), hệ thống hỗ trợ nhận tiền tự động qua 2 đồng coin gốc (native coin): Bitcoin (BTC) và Ethereum (ETH). Cron job chạy mỗi 1 phút để quét giao dịch mới, quy đổi sang VND và ghi vào logs_history — cùng cơ chế với USDT/ngân hàng.

Tỷ giá BTC/USDT, ETH/USDT

Lấy trực tiếp từ Binance Spot API (GET /api/v3/ticker/price), cache 60 giây. Sau đó quy đổi USDT → VND theo tỷ giá Binance P2P hiện tại (giống USDT TRC20/BEP20).

Luồng tổng quát

1. User thêm ví BTC/ETH tại app.apinganhang.net → Tài khoản → Thêm tài khoản.
2. Cron job chạy mỗi 1 phút, gọi API blockchain lấy giao dịch tối đa 14 ngày gần nhất.
3. Lọc chỉ giao dịch vào ví (nhận tiền), bỏ qua giao dịch ra.
4. Dedup theo trans_id + method + ABS(amount VND) — mỗi giao dịch chỉ ghi 1 lần.
5. Quy đổi ra VND, ghi logs_history, gửi Telegram + dispatch webhook transaction.received.

Bitcoin (BTC)

Thêm ví BTC

Gọi API POST /accounts/store.php (hoặc dùng giao diện app) với:

{
  "bank_code": "BTC",
  "account_number": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  "account_name": "Ví BTC chính"
}

Chỉ cần địa chỉ ví công khai — không cần private key hay API key, hệ thống chỉ theo dõi giao dịch nhận (không thể và không cần quyền chuyển tiền đi).

Response giao dịch BTC (trong logs_history)

{
  "id": 9001,
  "bank":        "BTC",
  "trans_id":    "6d292792a6b3d1078bd6edcc15e30a5f9d123198db1f736ebb1c003948b20f8",
  "amount":      167990,
  "type":        "in",
  "description": "Nhận 0.0001 BTC (~6.51 USDT / 167,990 VND)",
  "account":     "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  "transaction_time": 1786304133,
  "status":      "SUCCESS"
}

Ethereum (ETH)

Cấu hình Etherscan API Key (bắt buộc)

ETH bắt buộc phải có Etherscan API key — không có key sẽ trả lỗi "Thiếu Etherscan API key" và không lấy được giao dịch.

1. Đăng ký tại etherscan.io/myapikey → tạo API key miễn phí.
2. Khi thêm ví ETH tại app.apinganhang.net, nhập API key vào trường Password / API Key.
3. API key được mã hoá AES-256-GCM trước khi lưu DB (giống BEP20/BSC).

Thêm ví ETH

{
  "bank_code":      "ETH",
  "account_number": "0xAbCd1234...",
  "account_name":   "Ví ETH chính",
  "password":       "<Etherscan API Key>"
}

Response giao dịch ETH (trong logs_history)

{
  "id": 9002,
  "bank":        "ETH",
  "trans_id":    "0xabc123...",
  "amount":      2574000,
  "type":        "in",
  "description": "Nhận 0.052 ETH (~100 USDT / 2,574,000 VND)",
  "account":     "0xAbCd1234...",
  "transaction_time": 1751234567,
  "status":      "SUCCESS"
}

Webhook — Giao dịch BTC/ETH

Khi cron phát hiện giao dịch BTC/ETH mới hợp lệ, hệ thống dispatch event transaction.received về webhook URL đã cấu hình — cùng cơ chế với USDT/ngân hàng.

Xác minh thanh toán BTC/ETH

1. Tạo đơn, hiển thị địa chỉ ví BTC/ETH + số tiền VND cần thanh toán.
2. Khách gửi BTC/ETH đến đúng địa chỉ ví trên đúng mạng (Bitcoin mainnet / Ethereum mainnet).
3. Webhook nhận event transaction.received, kiểm tra bank === "BTC" hoặc "ETH" + amount.
4. Hoặc polling: GET /transactions/index.php?bank=BTC&limit=10 (tương tự cho ETH).

Use Case: Xác minh thanh toán tự động

Luồng xác minh giao dịch cho website bán hàng / SaaS / game topup.

1. Tạo đơn hàng trên website với order_code duy nhất + số tiền.
2. Hiển thị QR / thông tin CK — yêu cầu khách ghi order_code vào nội dung.
3. Polling API mỗi 10-30s: GET /transactions/index.php?search={order_code}&type=INCOME&limit=5
4. Khớp giao dịch: so amount + description chứa order_code + type=in
5. Cập nhật đơn paid khi tìm thấy.

Use Case: Webhook Callback

Nhận push notification thay vì polling. Server gửi callback khi có giao dịch mới.

Payload mẫu

Use Case: OTP Flow — Kết nối BIDV trong app

1. User nhập login_id + password + account_number BIDV SmartBanking.
2. Gọi Step 1: POST /accounts/connect.php với action: "request_otp".
3. Hệ thống login BIDV, BIDV gửi SMS OTP đến SĐT user.
4. User nhập OTP vào ô trên app.
5. Gọi Step 2: POST /accounts/connect.php với action: "verify_otp" + otp: "123456".
6. Nếu đúng, tài khoản được lưu với session đã xác thực, cron tự động đồng bộ giao dịch.

Demo trực tiếp

Test API ngay từ trình duyệt.

// Kết quả sẽ hiện ở đây...