ZeroPay

创建与查询订单

/v1 订单接口完整说明。

POST /v1/orders

字段类型必填说明
amount_usdnumber是订单美元金额。稳定币按 1:1 换算；非稳定币使用 NearIntents token catalog 的 USD 价格。
pay_chainstring是买家付款链，如 arb、base、sol、btc、near、aptos、sui、ton。
pay_assetstring是付款资产 asset_key，如 usdc、usdt、cbbtc、wbtc、xbtc、eth、weth、sol；legacy native 仍兼容。
refund_addressstring是付款人在 pay_chain 上自己的地址。支付失败或超时后资金自动退回此地址。
settle_chainstring是你收款的链，必须已配置收款地址。
settle_assetstring否结算资产 asset_key；不传时默认选择结算链 USDC/USDT/BTC/原生资产的优先项。
external_idstring否你的幂等键（如发票号）。重复使用会返回已存在的订单而非重复创建。
webhook_urlstring否接收签名状态回调的 HTTPS 地址。
refund_address 必须是付款人真实控制的地址——请在收银台向买家收集（钱包收银台直接用已连接的钱包地址）。ZeroPay 无法验证地址归属；退到错误地址的资金无法找回。订单失败或入金超时后，NEAR Intents 会自动退款到该地址。
curl
curl -X POST https://api.zeropay.top/v1/orders \
  -H "X-API-Key: zp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "inv_10086",
    "amount_usd": 49.9,
    "pay_chain": "arb",
    "pay_asset": "usdc",
    "settle_chain": "base",
    "settle_asset": "usdc",
    "refund_address": "0xPayerWalletAddress",
    "webhook_url": "https://your.app/webhooks/zeropay"
  }'
JavaScript
const res = await fetch("https://api.zeropay.top/v1/orders", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.ZEROPAY_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    external_id: "inv_10086",
    amount_usd: 49.9,
    pay_chain: "arb",
    pay_asset: "usdc",
    settle_chain: "base",
    settle_asset: "usdc",
    refund_address: payerAddress, // collected from your customer
    webhook_url: "https://your.app/webhooks/zeropay",
  }),
});
const { code, data, msg } = await res.json();
if (code !== 0) throw new Error(msg);
// Show data.deposit_address + data.pay_amount_formatted to the payer
Go
payload := map[string]any{
    "external_id":    "inv_10086",
    "amount_usd":     49.9,
    "pay_chain":      "arb",
    "pay_asset":      "usdc",
    "settle_chain":   "base",
    "settle_asset":   "usdc",
    "refund_address": payerAddress,
    "webhook_url":    "https://your.app/webhooks/zeropay",
}
body, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", "https://api.zeropay.top/v1/orders", bytes.NewReader(body))
req.Header.Set("X-API-Key", os.Getenv("ZEROPAY_API_KEY"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)

响应

响应示例
{
  "code": 0,
  "msg": "ok",
  "data": {
    "order_no": "zp_ord_9f2c41d8a3b7e6f0a1d2",
    "status": "pending_deposit",
    "amount_usd": 49.9,
    "pay_chain": "arb",
    "pay_asset": "usdc",
    "pay_asset_symbol": "USDC",
    "pay_asset_decimals": 6,
    "pay_amount": "49900000",
    "pay_amount_formatted": "49.9",
    "pay_chain_id": 42161,
    "pay_token_contract": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
    "settle_chain": "base",
    "settle_asset": "usdc",
    "settle_asset_symbol": "USDC",
    "settle_asset_decimals": 6,
    "deposit_address": "0x4dCa...8bF1",
    "amount_out_expected": "49260000",
    "fee_bps": 0,
    "deadline": "2026-06-12T16:30:00Z",
    "created_at": "2026-06-12T16:00:00Z"
  }
}

pay_amount 是 deadline 前必须到达 deposit_address 的最小单位精确金额。响应包含付款/结算 token 的 asset_id、symbol、decimals 快照，历史订单展示不依赖未来 token 列表变化。amount_out_expected 会反映 NEAR Intents 跨链/网络费用以及任何非 0 的 ZeroPay 费用；宣传期 fee_bps 为 0。

GET /v1/orders/{order_no}

curl https://api.zeropay.top/v1/orders/zp_ord_9f2c41d8a3b7e6f0a1d2 \
  -H "X-API-Key: zp_live_..."

GET /v1/orders

page/size 分页（size 上限 100）。过滤项：status、chain、from/to（ISO 日期）与 q——支持自由文本及 status:success chain:arb external:inv_1 这类字段表达式。

curl "https://api.zeropay.top/v1/orders?page=1&size=20&status=success&from=2026-06-01" \
  -H "X-API-Key: zp_live_..."

# => { "code": 0, "data": { "total": 132, "page": 1, "size": 20, "list": [ ... ] } }

POST /v1/orders/{order_no}/deposit

可选：提交付款交易哈希，加速入金检测。

curl -X POST https://api.zeropay.top/v1/orders/zp_ord_9f2c.../deposit \
  -H "X-API-Key: zp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"tx_hash": "0xabc123..."}'