Payment Hub API

Tổng quan

• Base URL: https://client.apinganhang.net/api/v1/payments/
• Xác thực: Authorization: Bearer <token> (user API) hoặc HMAC website (website_key + website_secret) cho orders/payouts.
• Callback Hub: /api/v1/payments/callbacks/{gateway}.php — cấu hình URL này trên cổng hoặc để Hub tự điền qua backend_url / notify_url.
• Forward site: Hub POST JSON tới notify_forward_url kèm header X-Payment-Signature: sha256=....

Endpoints chính

Xác thực đối tác — Website HMAC Bắt buộc

Mọi request gọi Hub từ phía đối tác (tạo đơn, rút tiền, tra cứu) đều phải xác thực bằng cặp website_key / website_secret. Lấy hai giá trị này tại app.apinganhang.net → Cổng thanh toán → Website đã đăng ký.

Thuật toán ký

1. Thu thập tất cả field của request (JSON body hoặc form-data).
2. Loại bỏ các field: sign, website_secret, website_secret_plain, website_secret_runtime, secret.
3. Loại bỏ field có giá trị rỗng ("") và field kiểu array/object.
4. Sắp xếp các field còn lại theo tên key — thứ tự bảng chữ cái ASCII (case-sensitive, chữ hoa trước chữ thường).
5. Nối chuỗi: key1=value1|key2=value2|key3=value3 — dấu pipe | ngăn cách giữa các cặp, không có dấu cách, không trailing pipe.
6. Ký HMAC-SHA256: HMAC-SHA256(canonical_string, website_secret) — kết quả là chuỗi hex thường (lowercase).
7. Gửi chữ ký trong field sign cùng với website_key trong body request.

Ví dụ minh hoạ — tạo đơn nạp (Payin)

Request body (trước khi ký):

{
  "website_key": "wk_abc123",
  "gateway":     "sharkpay",
  "amount":      100000,
  "channel":     "bank_transfer",
  "merchant_order_no": "ORDER_20260630_001",
  "notify_url":  "https://yourdomain.com/payment/callback",
  "return_url":  "https://yourdomain.com/payment/result"
}

Bước 1–3: giữ tất cả field, không field nào bị loại (không có sign/rỗng).

Bước 4: Sort theo key alphabetically:

amount, channel, gateway, merchant_order_no, notify_url, return_url, website_key

Bước 5: Canonical string:

amount=100000|channel=bank_transfer|gateway=sharkpay|merchant_order_no=ORDER_20260630_001|notify_url=https://yourdomain.com/payment/callback|return_url=https://yourdomain.com/payment/result|website_key=wk_abc123

Bước 6: HMAC-SHA256(canonical, "your_website_secret") → ví dụ: 3a7f9c2e...

Bước 7: Request cuối cùng:

{
  "website_key": "wk_abc123",
  "gateway":     "sharkpay",
  "amount":      100000,
  "channel":     "bank_transfer",
  "merchant_order_no": "ORDER_20260630_001",
  "notify_url":  "https://yourdomain.com/payment/callback",
  "return_url":  "https://yourdomain.com/payment/result",
  "sign": "3a7f9c2e..."
}

Implement mẫu — PHP

function hubSign(array $params, string $secret): string {
    $skip = ['sign', 'website_secret', 'website_secret_plain', 'website_secret_runtime', 'secret'];
    $pairs = [];
    foreach ($params as $k => $v) {
        if (in_array($k, $skip, true)) continue;
        if (is_array($v) || is_object($v)) continue;
        $val = trim((string)$v);
        if ($val === '') continue;
        $pairs[$k] = $val;
    }
    ksort($pairs, SORT_STRING);
    $canonical = implode('|', array_map(fn($k, $v) => "$k=$v", array_keys($pairs), $pairs));
    return hash_hmac('sha256', $canonical, $secret);
}

$body = [
    'website_key'       => 'wk_abc123',
    'gateway'           => 'sharkpay',
    'amount'            => 100000,
    'channel'           => 'bank_transfer',
    'merchant_order_no' => 'ORDER_20260630_001',
    'notify_url'        => 'https://yourdomain.com/payment/callback',
];
$body['sign'] = hubSign($body, 'your_website_secret');

$ch = curl_init('https://client.apinganhang.net/api/v1/payments/orders/create.php');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($body),
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 20,
]);
$res = json_decode(curl_exec($ch), true);

Implement mẫu — JavaScript (Node.js)

const crypto = require('crypto');

function hubSign(params, secret) {
  const skip = new Set(['sign','website_secret','website_secret_plain','website_secret_runtime','secret']);
  const pairs = {};
  for (const [k, v] of Object.entries(params)) {
    if (skip.has(k)) continue;
    if (typeof v === 'object' && v !== null) continue;
    const val = String(v).trim();
    if (val === '') continue;
    pairs[k] = val;
  }
  const canonical = Object.keys(pairs).sort().map(k => `${k}=${pairs[k]}`).join('|');
  return crypto.createHmac('sha256', secret).update(canonical).digest('hex');
}

const body = {
  website_key:       'wk_abc123',
  gateway:           'sharkpay',
  amount:            100000,
  channel:           'bank_transfer',
  merchant_order_no: 'ORDER_20260630_001',
  notify_url:        'https://yourdomain.com/payment/callback',
};
body.sign = hubSign(body, 'your_website_secret');

await fetch('https://client.apinganhang.net/api/v1/payments/orders/create.php', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(body),
});

Implement mẫu — Python

import hmac, hashlib, json, requests

def hub_sign(params: dict, secret: str) -> str:
    skip = {'sign','website_secret','website_secret_plain','website_secret_runtime','secret'}
    pairs = {k: str(v).strip() for k, v in params.items()
             if k not in skip and not isinstance(v, (dict, list)) and str(v).strip() != ''}
    canonical = '|'.join(f'{k}={v}' for k, v in sorted(pairs.items()))
    return hmac.new(secret.encode(), canonical.encode(), hashlib.sha256).hexdigest()

body = {
    'website_key':       'wk_abc123',
    'gateway':           'sharkpay',
    'amount':            100000,
    'channel':           'bank_transfer',
    'merchant_order_no': 'ORDER_20260630_001',
    'notify_url':        'https://yourdomain.com/payment/callback',
}
body['sign'] = hub_sign(body, 'your_website_secret')
resp = requests.post(
    'https://client.apinganhang.net/api/v1/payments/orders/create.php',
    json=body, timeout=20
).json()

Callback webhook từ Hub về site đối tác

Sau khi giao dịch được xác nhận, Hub POST JSON đến notify_forward_url (cấu hình tại app.apinganhang.net) kèm header:

X-Payment-Signature: sha256=<HMAC-SHA256 của raw JSON body>

Secret dùng để ký là notify_forward_secret (xem tại app.apinganhang.net → Website đã đăng ký → icon mắt). Cách xác thực phía đối tác:

// PHP
$rawBody = file_get_contents('php://input');
$sigHeader = $_SERVER['HTTP_X_PAYMENT_SIGNATURE'] ?? ''; // "sha256=abc..."
$secret = 'your_notify_forward_secret';
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
if (!hash_equals($expected, $sigHeader)) {
    http_response_code(403); exit('bad signature');
}
$data = json_decode($rawBody, true);

Lỗi xác thực thường gặp

Webhook callback — payload mẫu từ Hub về site

JSON body mà Hub POST về notify_forward_url sau khi giao dịch hoàn thành:

Payin thành công

{
  "event":      "payment.confirmed",
  "gateway":    "sharkpay",
  "order_id":   "HUB_20260630_xyzabc",
  "merchant_order_no": "ORDER_20260630_001",
  "amount":     100000,
  "currency":   "VND",
  "status":     "confirmed",
  "paid_at":    "2026-06-30T10:15:30+07:00"
}

Payout thành công

{
  "event":      "payout.confirmed",
  "gateway":    "sharkpay",
  "order_id":   "HUB_PAYOUT_20260630_abc",
  "merchant_order_no": "PAYOUT_001",
  "amount":     50000,
  "currency":   "VND",
  "status":     "confirmed",
  "paid_at":    "2026-06-30T10:20:00+07:00"
}

Site đối tác trả về HTTP 200 với body bất kỳ để báo đã nhận. Nếu Hub nhận status khác 2xx, sẽ retry.

Luồng Payin — EeziePay Form POST

EeziePay dùng form POST mở tab mới tới fundtransfer.php (không iframe). Hub trả về form_action + form_fields để site render form.

Ký SHA1 (deposit v3.1)

UPPER(SHA1("service_version=3.1&partner_code=...&partner_orderid=...&...&key=EncryptionKey"))

Thứ tự field theo tài liệu chính thức; bỏ field rỗng; remarks không ký. Callback thành công: status 000 hoặc 002. Hub trả XML:

<xml><billno>...</billno><status>OK</status></xml>

Bank codes VND — Online banking & QR

EeziePay chọn kênh qua field bank_code khi tạo đơn. Hub forward nguyên giá trị vào form_fields.bank_code.

Hoặc truyền pay_type + bank thay cho bank_code:

// Online banking Vietcombank
{ "pay_type": "online_banking", "bank": "VCB" }  → bank_code = VCB.VN

// QR Vietcombank
{ "pay_type": "qr", "bank": "VCB" }              → bank_code = VCB.QR.VN

// QR MoMo
{ "pay_type": "qr", "bank": "MOMO" }             → bank_code = MM.QR.VN

Danh sách đầy đủ theo merchant: EeziePay Deposit API.

Cấu hình Domain API & endpoint paths

Domain API chỉ là gốc, ví dụ https://gogomart168com.com — không dán path fundtransfer.php hoặc fundtransfer_enquiry.php vào ô Domain.

5 path endpoint (Fund Transfer / Query / Payout / …) nhập riêng từng file trên dashboard. Hub ghép: {Domain}/{fundtransfer.php}. Nếu thấy URL dạng .../fundtransfer_enquiry.php/fundtransfer.php → Domain hoặc path bị cấu hình nhầm.

Luồng Payout — EeziePay

Luồng Payin/Payout — WowPay JSON API

WowPay dùng JSON API thuần (không form/iframe). Hub ký MD5 uppercase rồi POST trực tiếp tới {Domain API}/api/payin/create/ hoặc /api/payout/create/.

Ký MD5

UPPER(MD5(sort_by_key_asc("key1=value1&key2=value2&...&key=SecretKey")))

Field rỗng/null không tham gia ký. Áp dụng cho mọi request (payin/payout/query/balance) và cả callback gửi tới Hub.

Cấu hình WowPay Dashboard

Thiết lập tại app.apinganhang.net/integration/wowpay (yêu cầu gói VIP).

user_id (bắt buộc theo API WowPay)

WowPay yêu cầu field user_id ở mọi request tạo đơn/payout — đây là ID khách hàng cuối (do website đối tác tự định danh), không phải ID cấu hình tĩnh của merchant. WowPay dùng field này để kiểm soát rủi ro/blacklist theo từng khách (xem mã lỗi 1225 User in blacklist).

WowPay Payin API Tóm tắt

Gọi qua Hub: POST /api/v1/payments/orders/create.php với "gateway": "wowpay".

Response data từ Hub: gateway_order_id (order_no của WowPay), pay_url (charge_info — link mở để thanh toán), qr_code (cashier_info.qrcode nếu có), amount, channel.

WowPay Payout API Tóm tắt

Gọi qua Hub: POST /api/v1/payments/payouts/create.php với "gateway": "wowpay". WowPay hiện chỉ hỗ trợ pay_type=bankcard (Hub tự gửi cố định).

Danh sách bank_code WowPay Bắt buộc khi bankcard/bankcard_qr/payout

Áp dụng cho bank_code ở payin (pay_type=bankcard hoặc bankcard_qr) và payout_bank_code ở payout. Đây là mã WowPay yêu cầu — khác với mã ngân hàng dùng ở phần xác minh giao dịch ngân hàng (vd Hub dùng VIETCOMBANK, WowPay dùng VCB).

Hub tự chuẩn hoá (viết hoa, bỏ khoảng trắng, map vài alias tên đầy đủ phổ biến: VIETCOMBANK→VCB, MBBANK→MB, VIETTINBANK→VTB, TPBANK→TPB, SEABANK→SEA...). Nếu gửi mã không nhận diện được, Hub trả lỗi VALIDATION_FAILED ngay (không cần đợi gọi WowPay).

Ví dụ tạo đơn WowPay

Payin — MoMo

POST /api/v1/payments/orders/create.php
Authorization: Bearer <token>
Content-Type: application/json

{
  "gateway": "wowpay",
  "merchant_order_no": "ORD20260623001",
  "amount": 50000,
  "pay_type": "momo",
  "user_id": "user123",
  "return_url": "https://shop.example.com/return"
}

Response thành công:

{
  "success": true,
  "data": {
    "gateway": "wowpay",
    "merchant_order_no": "ORD20260623001",
    "gateway_order_id": "2301051608200009",
    "pay_url": "https://pay.cashier.com/cashier/?token=...",
    "qr_code": "2|99|0936434203|PHAM VAN SINH||0|0|50000|9W6T7|transfer_myqr",
    "amount": 50000,
    "channel": "momo"
  }
}

Payin — Quét mã QR ngân hàng (bankcard_qr)

bank_code là field cấp cao nhất, bắt buộc khi pay_type là bankcard hoặc bankcard_qr:

{
  "gateway": "wowpay",
  "merchant_order_no": "ORD20260623002",
  "amount": 200000,
  "pay_type": "bankcard_qr",
  "bank_code": "VCB",
  "user_id": "user123"
}

Payout

POST /api/v1/payments/payouts/create.php
Authorization: Bearer <token>
Content-Type: application/json

{
  "gateway": "wowpay",
  "merchant_order_no": "POUT20260623001",
  "amount": 300000,
  "payout_name": "NGUYEN VAN A",
  "payout_bank_code": "VCB",
  "payout_account_no": "0123456789",
  "user_id": "user123"
}

Cấu hình SharkPay Dashboard

Thiết lập tại app.apinganhang.net/integration/sharkpay (yêu cầu gói VIP).

SharkPay Payin API Tóm tắt

Gọi qua Hub: POST /api/v1/payments/orders/create.php với "gateway": "sharkpay".

Response data từ Hub: gateway_order_id (payOrderId), pay_url (payUrl/codeUrl), qr_code, amount.

Ví dụ

POST /api/v1/payments/orders/create.php
Authorization: Bearer <token>
Content-Type: application/json

{
  "gateway": "sharkpay",
  "merchant_order_no": "ORD20260629001",
  "amount": 100000,
  "subject": "Nap tien tai khoan"
}

SharkPay Payout API Tóm tắt — Agent Pay

Gọi qua Hub: POST /api/v1/payments/payouts/create.php với "gateway": "sharkpay" (mặc định dùng Agent Pay — xem Settlement nếu cần hệ thống rút tiền thứ 2).

SharkPay — Settlement Hệ thống rút tiền thứ 2

SharkPay có 2 hệ thống rút tiền độc lập: Agent Pay (/api/agentpay/*, mặc định) và Settlement (/api/settlement/*, balance/field/status khác hẳn). Chọn bằng field payout_method khi gọi POST /api/v1/payments/payouts/create.php.

Ví dụ tạo lệnh Settlement

POST /api/v1/payments/payouts/create.php
Authorization: Bearer <token>
Content-Type: application/json

{
  "gateway": "sharkpay",
  "payout_method": "settlement",
  "merchant_order_no": "SETT20260629001",
  "amount": 300000,
  "account_name": "NGUYEN VAN A",
  "account_no": "0123456789",
  "bank_name": "Vietcombank",
  "bank_net_name": "CN Ha Noi",
  "user_id": "user123"
}

Tra cứu lại lệnh Settlement (truyền lại đúng payout_method=settlement, không cần biết settleOrderId — Hub tự tra theo merchant_order_no đã lưu):

POST /api/v1/payments/payouts/query.php
Authorization: Bearer <token>
Content-Type: application/json

{
  "gateway": "sharkpay",
  "payout_method": "settlement",
  "merchant_order_no": "SETT20260629001"
}

So sánh cổng

Cấu hình EeziePay Dashboard

Thiết lập tại app.apinganhang.net/integration/eeziepay (yêu cầu gói VIP). Các trường trên form khớp với cấu hình merchant EeziePay như sau:

Quy trình cấu hình (khuyến nghị)

1. Lấy Domain API, Merchant ID, Encryption Key và 5 đường dẫn API từ merchant EeziePay.
2. Điền các trường trên vào tab EeziePay, bật cổng, nhấn Lưu.
3. Copy URL callback Hub dán vào merchant EeziePay (nếu bảng điều khiển yêu cầu đăng ký URL cố định).
4. Nhấn Kiểm tra kết nối — gọi balance inquiry qua Hub (endpoint cấu hình querybalance.php hoặc tương đương).
5. Nhấn Cập nhật số dư — xem Fund Transfer (nạp) và Fund Out (chi hộ).
6. Thêm Website Integration phía dưới nếu nhiều site; mỗi site có website_key + website_secret riêng.

Balance inquiry

EeziePay có API balance (thường POST {base_url}/querybalance.php hoặc balance.php tùy merchant). Hub bọc qua:

POST /api/v1/payments/balance.php
Authorization: Bearer <token>
Content-Type: application/json

{
  "gateway": "eeziepay",
  "currency": "VND"
}

Response mẫu:

{
  "success": true,
  "data": {
    "currency": "VND",
    "items": [
      { "type": "Fund Transfer", "available": "1000000", "current": "1000000" },
      { "type": "Fund Out", "available": "500000", "current": "500000" }
    ]
  }
}

Fund Transfer = số dư dùng nạp tiền; Fund Out = số dư chi hộ. Hỗ trợ VND và IDR.

EeziePay Deposit API Tóm tắt

Form POST tới {Domain API}/fundtransfer.php. Ký SHA1 uppercase theo thứ tự field:

service_version, partner_code, partner_orderid, member_id, member_ip,
currency, amount, backend_url, redirect_url, bank_code, trans_time

bank_code quyết định kênh online banking hay QR (xem bảng ở trên). Bỏ trống nếu để EeziePay hiển thị trang chọn ngân hàng.

Hub trả form_action + form_fields + pay_channel khi gọi POST /api/v1/payments/orders/create.php với gateway=eeziepay.

Tài liệu gốc: EeziePay Deposit EN

Ví dụ tạo đơn EeziePay

Online banking (Vietcombank)

POST /api/v1/payments/orders/create.php
Authorization: Bearer <token>
Content-Type: application/json

{
  "gateway": "eeziepay",
  "website_key": "wk_xxx",
  "website_secret": "ws_xxx",
  "merchant_order_no": "ORD20260614001",
  "amount": 100000,
  "currency": "VND",
  "bank_code": "VCB.VN",
  "member_id": "user123",
  "member_ip": "1.2.3.4",
  "return_url": "https://shop.example.com/return"
}

QR chuyển khoản (Vietcombank QR)

{
  "gateway": "eeziepay",
  "merchant_order_no": "ORD20260614002",
  "amount": 200000,
  "currency": "VND",
  "pay_type": "qr",
  "bank": "VCB",
  "return_url": "https://shop.example.com/return",
  "member_id": "user123",
  "member_ip": "1.2.3.4"
}

Response thành công:

{
  "success": true,
  "data": {
    "form_action": "https://gogomart168com.com/fundtransfer.php",
    "form_fields": { "...": "...", "bank_code": "VCB.QR.VN" },
    "pay_channel": "qr",
    "bank_code": "VCB.QR.VN"
  }
}

Site render form:

<form method="POST" action="{form_action}" target="_blank">
  <!-- hidden inputs từ form_fields -->
  <button type="submit">Thanh toán</button>
</form>

Tham khảo

• Xác thực đối tác — Website HMAC (thuật toán + code mẫu PHP/JS/Python)
• Webhook callback payload mẫu (Hub → site)
• Quản lý website_key / website_secret tại dashboard
• Cấu hình SharkPay (tóm tắt trên Hub)
• SharkPay Payin API (tóm tắt trên Hub)
• SharkPay Payout API — Agent Pay (tóm tắt trên Hub)
• SharkPay Settlement — hệ thống rút tiền thứ 2 (tóm tắt trên Hub)
• SharkPay Payin/Settlement API (vendor)
• SharkPay Agent Pay API (vendor)
• SPA cấu hình: app.apinganhang.net/integration/sharkpay
• Cấu hình WowPay (tóm tắt trên Hub)
• WowPay Payin API (tóm tắt trên Hub)
• WowPay Payout API (tóm tắt trên Hub)
• Danh sách bank_code WowPay (bankcard/bankcard_qr/payout)
• SPA cấu hình: app.apinganhang.net/integration/wowpay
• EeziePay API Documentation
• EeziePay Deposit API (tóm tắt trên Hub)
• EeziePay Balance API (tóm tắt trên Hub)
• EeziePay Deposit API (vendor)
• EeziePay Balance API (vendor)
• API docs chung (xác thực giao dịch ngân hàng — sản phẩm khác, không liên quan Payment Hub)
• SPA cấu hình: app.apinganhang.net/integration/eeziepay