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

Sau khi cổng thanh toán báo kết quả cho Hub, Hub xác thực callback của cổng, cập nhật đơn rồi POST JSON tới notify_forward_url của website đã tạo đơn, kèm header:

Content-Type: application/json
X-Payment-Signature: sha256=<HMAC-SHA256(raw JSON body, notify_forward_secret)>
User-Agent: Apinganhang-PaymentHub/1.0

Chữ ký ký trên đúng chuỗi JSON đã gửi (không phải JSON decode/encode lại), dùng secret notify_forward_secret của website (xem tại app.apinganhang.net → Website đã đăng ký → icon mắt) — khác với website_secret dùng để ký request gọi Hub.

Envelope chung cho mọi cổng (WowPay, SharkPay, EeziePay, 1DPay)

{
  "event":     "payment.<gateway>.callback",
  "gateway":   "sharkpay",
  "timestamp": 1790856752,
  "data": {
    "gateway":            "sharkpay",
    "success":            true,
    "status":             "...",
    "amount":             100000,
    "merchant_order_no":  "ORDER_20260630_001"
    /* + các field gốc do cổng gửi, khác nhau theo từng cổng — xem bên dưới */
  }
}

event luôn là payment.<gateway>.callback (ví dụ payment.sharkpay.callback, payment.wowpay.callback, payment.eeziepay.callback, payment.1dpay.callback) — kể cả cho lệnh rút (payout), không có event riêng payout.confirmed. Phân biệt payin/payout bằng mã đơn (merchant_order_no) phía site tự quản lý, hoặc field order_type nếu cổng đó có trả (xem ví dụ 1DPay).

Xác thực chữ ký phía đối tác (giống nhau cho mọi cổng):

// 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');
}
$payload = json_decode($rawBody, true);
$data = $payload['data'] ?? [];
if (($data['success'] ?? false) === true) {
    // tìm đơn theo $data['merchant_order_no'] -> nếu chưa xử lý, cộng $data['amount']; đã xử lý -> bỏ qua
} else {
    // đang xử lý / thất bại -> không cộng tiền, tuỳ xử lý UI/hoàn tiền phía site
}
http_response_code(200); echo 'OK';

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>

1DPay — Tổng quan gateway=1dpay

1DPay là cổng nạp QR ngân hàng (VietQR) + chi hộ (rút tiền) VND. Mã cổng khi gọi Hub: "gateway": "1dpay". Toàn bộ phần mã hoá/ký riêng của 1DPay do Hub tự xử lý — website đối tác không cần mã hoá gì thêm, chỉ gọi Hub như các cổng khác: header Authorization: Bearer <token> + website_key + sign (HMAC-SHA256 bằng website_secret, xem Xác thực đối tác).

• Field notify_url trong request không được dùng cho 1DPay — Hub tự khai báo URL callback của Hub với 1DPay và chỉ forward về notify_forward_url của website.
• amount là số nguyên VND (không nhân ×100). Hub chấp nhận cả 100000, "100000", "100.000".
• merchant_order_no phải duy nhất cho mỗi đơn/lệnh (Hub cũng nhận alias mch_order_no, order_code).

1DPay Payin — Tạo đơn nạp QR ngân hàng

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

Kênh nạp (channel)

Hub không áp hạn mức nạp riêng cho 1DPay; nếu số tiền nằm ngoài hạn mức 1DPay áp cho merchant, 1DPay từ chối và Hub trả lỗi GATEWAY_FAILED kèm mã lỗi của cổng (xem Mã lỗi). Hạn mức hiển thị cho khách nên cấu hình ở phía site.

Ví dụ request

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

{
  "gateway": "1dpay",
  "website_key": "ws_live_xxxxxxxxxxxxxxxx",
  "merchant_order_no": "ORD20261002001",
  "amount": 100000,
  "channel": "QR",
  "member_id": "user123",
  "device_ip": "113.161.1.2",
  "return_url": "https://yourdomain.com/profile?page=transaction-history",
  "sign": "<hmac_sha256>"
}

Chuỗi ký (canonical, sort key ASCII, nối bằng |):

amount=100000|channel=QR|device_ip=113.161.1.2|gateway=1dpay|member_id=user123|merchant_order_no=ORD20261002001|return_url=https://yourdomain.com/profile?page=transaction-history|website_key=ws_live_xxxxxxxxxxxxxxxx

Response thành công

{
  "success": true,
  "message": "Order created",
  "data": {
    "gateway": "1dpay",
    "merchant_order_no": "ORD20261002001",
    "gateway_order_id": "D2026100110148101",
    "pay_url": "https://cashier.1dpayapp.com/Deposit/VietQRDeposit/?a=...",
    "qr_code": "00020101021138520010A000000727...6304ABCD",
    "qr_image_base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
    "bank_code": "EXB",
    "account_number": "1234567890",
    "account_name": "NGUYEN VAN B",
    "transfer_content": "KHOAN3JZ2TU",
    "amount": 100000,
    "actual_amount": 100000,
    "channel": "BQR",
    "raw": { "...": "phản hồi gốc của 1DPay (tham khảo, không cần dùng)" }
  }
}

1DPay Payout — Tạo lệnh rút 500.000 – 200.000.000 VND

Gọi qua Hub: POST /api/v1/payments/payouts/create.php với "gateway": "1dpay".

{
  "success": false,
  "message": "Số tiền rút qua 1dpay phải từ 500.000 đến 200.000.000 VND.",
  "data": { "code": "AMOUNT_OUT_OF_RANGE", "min": 500000, "max": 200000000 }
}

Ví dụ request

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

{
  "gateway": "1dpay",
  "website_key": "ws_live_xxxxxxxxxxxxxxxx",
  "merchant_order_no": "WD20261002001",
  "amount": 1500000,
  "bank_code": "VCB",
  "account_number": "0123456789",
  "account_name": "NGUYEN VAN A",
  "member_id": "user123",
  "sign": "<hmac_sha256>"
}

Response thành công (đã gửi lệnh sang 1DPay)

{
  "success": true,
  "message": "Payout submitted",
  "data": {
    "gateway": "1dpay",
    "merchant_order_no": "WD20261002001",
    "gateway_order_id": "W2026100200000001",
    "bank_code": "VCB",
    "raw": { "...": "phản hồi gốc của 1DPay" }
  }
}

success: true ở bước này chỉ có nghĩa là 1DPay đã nhận lệnh — tiền chưa chắc đã chuyển. Kết quả cuối cùng (thành công / thất bại) đến qua webhook hoặc tra cứu.

Danh sách bank_code 1DPay Payout

Mã ngân hàng nhận tiền khi rút qua 1DPay (khác một số mã của WowPay). Hub nhận cả mã 1DPay lẫn alias thông dụng / mã WowPay và tự chuyển đổi, ví dụ: VIETCOMBANK→VCB, TCB/TECHCOMBANK→TEC, VTB/VIETINBANK/CTG→VTN, MB/MBBANK→MBB, AGB/AGRIBANK→AGR, SAC/STB/SACOMBANK→SAB, EXIM/EIB→EXB, BACA→BAB, NAMA→NAB, SEA/SEABANK→SEAB, OCEAN→OB, CIMB→CIMBV, WOORI→WOO, SHINHAN→SHBVN, VIETCAPITALBANK/BVBANK→Viet Capital Bank. Mã không nhận diện được → HTTP 422 VALIDATION_FAILED (chưa gọi sang cổng).

ABB  ACB  ACBCORP  AGR  BAB  BIDV  BIDVCORP  BVB  CAKE  CIMBV  DAB  EXB  EXBCORP  GPB  HDB  HLB
HSBCVN  IVB  KLB  LIO  LPB  LPBANK  MBB  MBBCORP  MSB  MSBCORP  NAB  NCB  OB  OCB  OCBCORP  PBVN
PGB  PVCOM  SAB  SABCORP  SAIGON  SCB  SCBV  SEAB  SHB  SHBCORP  SHBVN  TCBCORP  TEC  TPB  TPBCORP
VAB  VBSP  VCB  VCBCORP  VIB  "Viet Capital Bank"  VIETB  VIKKI  VPB  VPBCORP  VRB  VTN  VTNCORP  WOO

Mã có hậu tố CORP là tài khoản doanh nghiệp của ngân hàng tương ứng.

1DPay — Tra cứu đơn nạp / lệnh rút

POST https://client.apinganhang.net/api/v1/payments/orders/query.php    (đơn nạp)
POST https://client.apinganhang.net/api/v1/payments/payouts/query.php   (lệnh rút)
Authorization: Bearer <token>
Content-Type: application/json

{
  "gateway": "1dpay",
  "website_key": "ws_live_xxxxxxxxxxxxxxxx",
  "merchant_order_no": "ORD20261002001",
  "sign": "<hmac_sha256>"
}

Response data gồm chi tiết giao dịch từ 1DPay, cộng thêm các field chuẩn hoá của Hub:

{
  "success": true,
  "message": "Queried",
  "data": {
    "...": "các field chi tiết của 1DPay (statusId, amount, ...)",
    "gateway": "1dpay",
    "merchant_order_no": "ORD20261002001",
    "gateway_order_id": "D2026100110148101",
    "gateway_status": "6",
    "state": "success"
  }
}

Bảng trạng thái

Lưu ý: mã thành công của nạp (6) và rút (4) khác nhau — nên dựa vào field state (hoặc success trong webhook) thay vì tự so mã số. Tra cứu đơn không tồn tại → NOT_FOUND.

1DPay — Webhook kết quả (Hub → site) X-Payment-Signature

Khi 1DPay báo kết quả, Hub xác thực callback của cổng, cập nhật đơn rồi POST JSON tới notify_forward_url của website đã tạo đơn, kèm header:

Content-Type: application/json
X-Payment-Signature: sha256=<HMAC-SHA256(raw JSON body, notify_forward_secret)>
User-Agent: Apinganhang-PaymentHub/1.0

Payload mẫu — nạp thành công

{
  "event": "payment.1dpay.callback",
  "gateway": "1dpay",
  "timestamp": 1790856752,
  "data": {
    "CurrencyCode": "VND",
    "MerchantTransactionId": "ORD20261002001",
    "Status": 6,
    "Amount": 100000,
    "NetAmount": 99400,
    "PaymentMethodCode": "BQR",
    "UniqueReferenceNo": "KHOAN3JZ2TU",
    "BankReferenceNo": null,
    "Remark": null,
    "merchant_order_no": "ORD20261002001",
    "order_id": "D2026100110148101",
    "order_type": "payin",
    "status": "6",
    "state": "success",
    "success": true,
    "amount": 100000,
    "gateway": "1dpay"
  }
}

Xác thực chữ ký (giống mọi cổng khác của Hub)

// PHP — ký trên RAW body, không decode rồi encode lại
$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, 'your_1dpay_notify_forward_secret');
if (!hash_equals($expected, $_SERVER['HTTP_X_PAYMENT_SIGNATURE'] ?? '')) {
    http_response_code(403); exit('bad signature');
}
$p = json_decode($raw, true);
$d = $p['data'] ?? [];
if (($p['gateway'] ?? '') !== '1dpay') { http_response_code(400); exit; }
if (($d['success'] ?? false) === true) {
    // tìm đơn theo $d['merchant_order_no'] + $d['order_type'];
    // nếu đơn chưa xử lý -> cộng $d['amount'] (nạp) / hoàn tất (rút); đã xử lý -> bỏ qua
} elseif (($d['state'] ?? '') === 'failed') {
    // đánh dấu thất bại (rút: hoàn tiền cho khách phía site)
}
http_response_code(200); echo 'OK';

// Node.js
const crypto = require('crypto');
const expected = 'sha256=' + crypto.createHmac('sha256', NOTIFY_FORWARD_SECRET).update(rawBody).digest('hex');
const ok = expected.length === sigHeader.length &&
           crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sigHeader));

• Secret dùng để verify là notify_forward_secret của website 1DPay (không phải website_secret, không phải secret của website cổng khác).
• Trả HTTP 2xx khi đã nhận. Hub chỉ forward webhook thành công 1 lần cho mỗi đơn; các callback trạng thái khác (đang xử lý / thất bại) vẫn được forward — site phải kiểm tra success/state, không coi mọi webhook là thành công.
• Site vẫn nên tự chống trùng theo merchant_order_no (đơn đã xử lý thì bỏ qua).

1DPay — Mã lỗi thường gặp

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)
• 1DPay — tổng quan & quy tắc website_key riêng
• 1DPay Payin — tạo đơn nạp QR (tóm tắt trên Hub)
• 1DPay Payout — tạo lệnh rút (tóm tắt trên Hub)
• Danh sách bank_code 1DPay (payout)
• 1DPay — tra cứu & bảng trạng thái
• 1DPay — webhook kết quả & xác thực chữ ký
• 1DPay — mã lỗi thường gặp
• SPA cấu hình: app.apinganhang.net/integration/1dpay
• 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