API Key 模式 - HTTP API 整合

使用 API Key 在服務端訪問商戶業務 HTTP API。API Key 認證成功後會繞過面向互動式登入的 Step-Up 重認證。

獲取 API Key

1. 登入 PolyPay 商戶後臺
2. 進入「API 金鑰」頁面
3. 點選「建立金鑰」
4. 選擇過期時間；新增 API Key 預設 7 天後過期。選擇永不過期時，該 API Key 不會自動失效；歷史 API Key 預設永不過期。
5. 安全儲存生成的 API Key

每個 API Key 可選配置來源 IP 白名單，支援單個 IPv4/IPv6 地址或 CIDR 網段；不配置時不限制來源 IP。白名單在 API Key 認證階段校驗，建議生產金鑰僅允許固定伺服器出口 IP。為防止洩露的舊 Key 維持訪問，API Key 不能建立新 API Key。

套餐額度與計費口徑

• 訂閱套餐按商戶生效。每個商戶獨立計算本月成功訂單、錢包地址、通知額度和可用通知渠道；切換商戶不會繼承或消耗其他商戶的套餐。
• 公開定價見定價頁。PolyPay 不抽取交易流水，按套餐額度和按量用量收費。
• 每個帳號首個建立的商戶會固定持有 Free 收款資格，禁用其他商戶不會轉移該資格；額外商戶需要為該商戶啟用用多少付多少、Pro 或 Business 後才能建立收款訂單或 Checkout。
• 帳號餘額按使用者維度儲存，並分為實付餘額和贈金餘額；消費時優先使用贈金。訂閱餘額不足時會預佔可用餘額，並將剩餘金額帶到加密貨幣收銀臺；支付失敗或超時後原路釋放預佔。套餐頁的可選套餐下方會分頁展示充值、消費帳務流水以及待處理、已完成或已拒絕的提現申請，並標明狀態。
• 實付餘額和贈金餘額都可以申請 USDT 提現。收款地址可從當前商戶已啟用、網路匹配且支援 USDT 的錢包中選擇，也可自定義輸入。手續費由後端按所選網路的實時快速費率加 20% 波動餘量計價，提交時重新計算，並與提現金額一起凍結、從贈金開始扣減。後端不會自動發起鏈上轉帳；人工轉帳完成或拒絕後，由運維機器人按鈕完成扣帳或按原餘額型別退回。
• Pro 和 Business 等付費定期套餐可按商戶分別開啟餘額自動續費。套餐到期後系統會從共享帳號餘額扣除該商戶下一週期費用；餘額不足時不會扣款，該商戶套餐按過期處理。
• 用多少付多少按商戶獨立啟用。該商戶的訂單、通知和錢包地址從第一筆用量開始按對應單價從共享帳號餘額扣費；不會為其他商戶自動開通。
• 支付 Webhook 回撥用於訂單狀態同步，不計入外部提醒通知額度。
• Telegram、Email、WhatsApp、通知 Webhook、企業微信、Discord 等商戶業務提醒按當前商戶套餐額度統計；站內通知和套餐訂閱到期類系統通知不計入額度。
• 套餐訂閱即將到期和已到期通知由 PolyPay 使用固定系統文案傳送，商戶不能在通知模板中自定義修改。
• 自定義域名和 AI Agent 收款是有效訂閱能力，Pay-as-you-go 也可使用。套餐過期或未啟用訂閱後配置會保留但進入凍結狀態：不能管理配置，自定義域名會從 PolyPay 的 Cloudflare 路由中移除（使用者側 DNS 記錄可保留），x402 verify/settle 會拒絕執行；恢復有效訂閱後 PolyPay 會自動重新增立自定義主機名並恢復。

API 介面文件

基礎資訊

認證方式

商戶業務介面同時接受後臺登入 JWT 和 API Key。API Key 請求無需傳入 Step-Up Ticket；服務端呼叫時可使用以下任一方式，推薦使用含義明確的 X-API-Key：

跳轉到託管 Checkout

如果希望由 PolyPay 展示支付方式選擇頁，不要先呼叫 /order/add。服務端使用 API Key 呼叫下面的介面獲取 checkout_url，然後把使用者重定向到該地址。未傳 currency/network 時，系統會立即建立 Method pending 訂單並進入支付方式選擇頁。付款連結本身就是完整的公開付款入口，客戶端無需儲存 checkout session；頁面只允許客戶選擇 currency/network，金額、商戶訂單號和回撥地址始終從已建立的訂單讀取。連結使用 /pay/{trade_id}，選擇或更換支付方式後繼續保留同一 trade_id 和 URL。同時傳入 currency 和 network 時會跳過選擇頁。訂單過期後可使用同一商戶訂單號重新獲取 checkout_url。選擇本位幣時，收銀臺會展示實時 USD 參考匯率和預估支付數量。

POST /order/checkout

curl -X POST https://api.polypay.ai/api/v1/pay/sdk/order/checkout \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "mch_order_id": "ORDER_001",
    "amount": 10.00,
    "notify_url": "https://your-site.com/webhook",
    "redirect_url": "https://your-site.com/success",
    "locale": "en"
  }'

響應示例：

{
  "code": 0,
  "message": "",
  "data": {
    "checkout_url": "https://checkout.polypay.ai/en/pay/202607311785497228532519443",
    "payment_url": "https://checkout.polypay.ai/en/pay/202607311785497228532519443"
  }
}

建立訂單

POST /order/add

請求引數

響應引數

程式碼示例

curl -X POST https://api.polypay.ai/api/v1/pay/sdk/order/add \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USDT",
    "network": "tron",
    "amount": 100.00,
    "mch_order_id": "ORDER_123456",
    "notify_url": "https://your-site.com/webhook",
    "redirect_url": "https://your-site.com/success"
  }'

響應示例

{
  "code": 0,
  "message": "success",
  "data": {
    "trade_id": "PP202412110001",
    "currency": "USDT",
    "network": "tron",
    "amount": 100.00,
    "actual_amount": 100.0001,
    "address": "TXxx...xxx",
    "expiration_time": 1704067200,
    "payment_url": "https://checkout.polypay.ai/status/PP202412110001"
  }
}

查詢訂單

POST /order/detail

請求引數

trade_id 和 mch_order_id 至少傳入一個；如果同時傳入，優先按 trade_id 查詢。

響應示例

curl -X POST https://api.polypay.ai/api/v1/pay/sdk/order/detail \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trade_id": "PP202412110001"
  }'

取消訂單

POST /order/cancel

當你的平臺取消、作廢或替換尚未支付的訂單時，應同步取消 PolyPay 訂單。取消成功會立即釋放該訂單佔用的“收款地址 + 實付金額”，避免後續相同金額訂單因為舊佔用而調整實付金額（穩定幣通常增加 0.01）。介面支援透過 trade_id 或 mch_order_id 定位訂單；已經支付或過期的訂單不能取消。舊版 /order/cancel-by-trade-id 路徑繼續保留用於相容已有接入。

請求引數

至少傳入一個訂單標識；如果同時傳入，優先按 trade_id 取消。

curl -X POST https://api.polypay.ai/api/v1/pay/sdk/order/cancel \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trade_id": "PP202412110001"
  }'

Webhook 回撥

訂單建立以及訂單狀態變化時，我們會向你配置的 Webhook URL 傳送 HTTP POST 請求。

回撥載荷示例

{
  "order_no": "ORDER_123456",
  "status": 2,
  "amount": 100.0001,
  "currency": "USDT",
  "currency_name": "usdt",
  "network": "Tron",
  "contract_addr": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "hash": "abc123...",
  "wallet_address": "TXxx...xxx",
  "environment": "production",
  "event_id": "evt_xxx"
}

network 表示支付鏈；currency_name 是小寫幣種名（例如 usdt/usdc）；hash 為鏈上交易雜湊。主幣或暫未配置合約的幣種 contract_addr 為空字串。

狀態型別

驗證 Webhook v2 簽名

Webhook v2 使用 PolyPay 平臺 Ed25519 金鑰簽名，不依賴商戶 API Key。服務端必須使用原始請求體，並從平臺 JWKS 獲取公鑰完成驗籤。

驗證流程（服務端）

1. 要求 X-Webhook-Signature-Version 為 v2，並讀取 Key ID、商戶 ID、環境、時間戳、nonce 和 v2 簽名請求頭。
2. 校驗商戶 ID 和環境與服務端預期值完全一致，並限制時間戳視窗為 300 秒。
3. 根據 Key ID 從 /api/v1/pay/public/webhook-jwks 選擇 Ed25519 公鑰，使用原始請求體驗證簽名。
4. 在 Redis 等共享儲存中原子消費 nonce，拒絕重複請求。
5. 驗籤成功後再解析事件，並按 environment 和 event_id 冪等處理。

<?php
use PolyPay\PolyPay;
use PolyPay\WebhookHandler;
use PolyPay\Exception\SignatureException;

$polypay = new PolyPay(getenv('POLYPAY_API_KEY') ?: '');

try {
    $event = $polypay
        ->webhookV2('MCH_YOUR_ID', 'production')
        ->handle();

    $status = WebhookHandler::resolveStatus($event);
    if ($status === 'paid') {
        handleOrderPaidIdempotently($event);
    }

    http_response_code(200);
    echo 'OK';
} catch (SignatureException $e) {
    http_response_code($e->getHttpStatus());
    echo 'Unauthorized';
}

完整的請求頭、簽名原文和 Node.js 示例請檢視 Webhook 安全指南。

錯誤碼

安全最佳實踐

• 保護 API Key：永遠不要在前端程式碼、Git 倉庫或日誌中暴露 API Key
• 使用環境變數：將 API Key 儲存在環境變數中
• 驗證 Webhook 簽名：始終驗證 Webhook 請求的簽名
• 使用 HTTPS：確保你的 Webhook 端點使用 HTTPS
• 實現冪等性：Webhook 可能會重複傳送，處理邏輯要保證冪等性