ZeroPay

Create & query orders

The /v1 order endpoints in full detail.

POST /v1/orders

FieldTypeRequiredNotes
amount_usdnumberyesOrder value in USD. Stablecoins convert 1:1; non-stable assets use the USD price from the NEAR Intents token catalog.
pay_chainstringyesChain the customer pays on, e.g. arb, base, sol, btc, near, aptos, sui, ton.
pay_assetstringyesPay asset asset_key, e.g. usdc, usdt, cbbtc, wbtc, xbtc, eth, weth, sol; legacy native is still accepted.
refund_addressstringyesThe payer's own address on pay_chain. Failed or late payments are automatically refunded here.
settle_chainstringyesChain you receive on. Requires a configured receiving address.
settle_assetstringnoSettlement asset asset_key. If omitted, ZeroPay picks the preferred USDC/USDT/BTC/native asset on the settle chain.
external_idstringnoYour idempotency key (e.g. invoice id). Reusing it returns the existing order instead of creating a new one.
webhook_urlstringnoHTTPS endpoint for signed status callbacks.
refund_address must be an address the payer controls — collect it from your customer at checkout (for wallet checkouts, use the connected wallet address). ZeroPay cannot verify ownership; funds sent to a wrong refund address are unrecoverable. If the order fails or expires after a deposit, NEAR Intents refunds to this address automatically.
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)

Response

201 response
{
  "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 is the exact amount in smallest units that must arrive at deposit_address before deadline. The response includes pay/settle token snapshots (asset_id, symbol, decimals), so historical order display does not depend on future catalog changes. amount_out_expected reflects NEAR Intents bridge/network costs and any non-zero ZeroPay fee; during the promotion fee_bps is 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

Pagination via page/size (max 100). Filters: status, chain, from/to (ISO dates) and q — a search expression supporting free text plus field terms like 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

Optional: submit the payer's transaction hash to speed up deposit detection.

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..."}'
Create & query orders · Docs · ZeroPay