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.

Payment Hub — Hướng dẫn đối tác

Dùng chung cho đối tác kết nối nạp/chi qua Payment Hub. Tài liệu không chứa tài khoản, key thật hay cấu hình của đơn vị khác.

Thông tin cần được cấp

• API base: https://client.apinganhang.net/api/v1/payments
• Bearer token của tài khoản Hub riêng của đối tác.
• website_key, website_secret cho website đăng ký.
• URL nhận webhook HTTPS và notify_forward_secret tương ứng.
• Cổng được bật, merchant được phép dùng, hạn mức và IP máy chủ đối tác được phép chi.

API

Gửi POST JSON với Content-Type: application/json và Authorization: Bearer <TOKEN_DOI_TAC>. Các cổng hiện có: anpay, 1dpay, minipay, sharkpay, wowpay, eeziepay — chỉ dùng cổng đã được cấu hình và bật cho tài khoản đó.

Payment Hub — Ký request

1. Thêm website_key và timestamp (Unix giây, lệch đồng hồ tối đa 300 giây) trước khi ký.
2. Loại các field sign, website_secret, website_secret_plain, website_secret_runtime, secret; bỏ null, chuỗi rỗng và array/object.
3. Trim tên/giá trị, sắp xếp tên field theo thứ tự chuỗi, nối key=value bằng |.
4. Ký HMAC-SHA256 bằng website_secret, xuất hex chữ thường. Không URL-encode chuỗi ký.
5. Gửi chữ ký trong field sign; không gửi secret.

Ví dụ PHP

function hubSign(array $input, string $secret): string {
    $skip = ['sign','website_secret','website_secret_plain','website_secret_runtime','secret'];
    $pairs = [];
    foreach ($input as $k => $v) {
        $k = trim((string)$k);
        if ($k === '' || in_array(strtolower($k), $skip, true) || !is_scalar($v)) continue;
        $v = trim((string)$v);
        if ($v !== '') $pairs[$k] = $v;
    }
    ksort($pairs, SORT_STRING);
    $parts = [];
    foreach ($pairs as $k => $v) $parts[] = $k . '=' . $v;
    return hash_hmac('sha256', implode('|', $parts), $secret);
}

$body = [
    'website_key'       => getenv('HUB_WEBSITE_KEY'),
    'timestamp'         => time(),
    'gateway'           => 'anpay',
    'merchant_order_no' => 'PARTNER_DEP_20261012_0001',
    'amount'            => 100000,
    'currency'          => 'VND',
    'member_id'         => 'customer_001',
    'anpay_pay_type'    => 7,
    'return_url'        => 'https://partner.example/payment/result',
];
$body['sign'] = hubSign($body, getenv('HUB_WEBSITE_SECRET'));
// POST $body tới /orders/create.php từ backend, kèm Bearer token.

Payment Hub — Anpay: nạp

gateway=anpay; anpay_pay_type:

Khi response success=true, đọc data: merchant_order_no, gateway_order_id, amount, pay_url, account_number, account_name, bank_code, transfer_content, qr_content, qr_image_base64. Hiển thị đúng QR/STK/nội dung của đơn vừa tạo, không tái sử dụng đơn cũ. Có thể bỏ bank_code để cổng tự chọn ngân hàng.

Hạn mức phụ thuộc merchant/kênh được cấp; không lấy hạn mức của merchant khác làm mặc định.

Payment Hub — Anpay: chi

Payload tạo chi gồm các field xác thực ở trên + gateway=anpay, merchant_order_no, amount, currency=VND, bank_code (BIN ngân hàng), account_number, account_name, member_id.

• Hub chặn Anpay ngoài khoảng 100.000 – 200.000.000 VND; merchant hoặc hạn mức riêng có thể chặt hơn.
• IP backend gọi Hub phải được khai whitelist chi.

Payment Hub — Tra cứu & kết quả cuối

Tra cứu bằng gateway, merchant_order_no cùng thông tin xác thực. Với Anpay, dùng trạng thái chuẩn hoá data.state: success | processing | failed.

• Chỉ cập nhật tiền sau khi kiểm tra: đơn tồn tại, đúng cổng, đúng loại, đúng số tiền và trạng thái cuối.
• HTTP 409 với AMOUNT_REVIEW/manual_review: giữ đối soát thủ công, không chi lại hoặc tự cộng/hoàn.
• Poll có backoff, không gọi dồn mỗi vài giây; gặp giới hạn tần suất thì giãn thời gian.

Payment Hub — Nhận webhook

Hub POST JSON với header X-Payment-Signature: sha256=<hex>. Xác thực bằng HMAC-SHA256 trên nguyên raw body với notify_forward_secret — KHÔNG decode/encode lại rồi ký, KHÔNG dùng website_secret.

$raw      = file_get_contents('php://input');
$received = $_SERVER['HTTP_X_PAYMENT_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $raw, getenv('HUB_NOTIFY_SECRET'));
if (!hash_equals($expected, $received)) {
    http_response_code(403); exit;
}
$event = json_decode($raw, true);
// Lưu bền vững vào inbox/queue trước khi ACK 2xx.
// Worker kiểm tra đơn và xử lý tiền idempotent trong transaction DB.

Envelope có event=payment.anpay.callback, gateway, timestamp, data. Event này dùng cho cả nạp và chi — xác định loại đơn từ dữ liệu đã lưu, không suy ra từ tên event. Không coi mọi webhook là thành công.

Payment Hub — Nghiệm thu trước khi bật thật

• Ký đúng/sai; timestamp cũ; IP chi ngoài whitelist bị từ chối.
• Nạp thử có phê duyệt: tạo QR, nhận kết quả thật, đúng số tiền, chỉ cộng một lần.
• Webhook lặp/sai chữ ký, dịch vụ nhận tạm ngừng: không cộng sai, đối soát phục hồi được.
• Chi thử có phê duyệt: định tuyến URL/secret đúng, xử lý thành công/thất bại/timeout không chi hoặc hoàn lặp.
• Token/key không xuất hiện ở frontend hoặc log; từng đối tác có tài khoản và quyền riêng.

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