Authentication

Two auth domains: Boss console JWT and merchant API keys.

Boss console (JWT)

Console endpoints under /api/v1/boss use a Bearer JWT obtained by email code login. Tokens are valid for 7 days.

request a code

curl -X POST https://api.zeropay.top/api/v1/auth/code \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

exchange for a JWT

curl -X POST https://api.zeropay.top/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "code": "123456"}'

# => { "code": 0, "data": { "token": "eyJhbGciOi...", "merchant": { ... } } }

Merchant API (X-API-Key)

All payment endpoints under /v1 authenticate with an API key sent in the X-API-Key header (an Authorization: Bearer header also works).

create a key (console JWT required)

curl -X POST https://api.zeropay.top/api/v1/boss/appkeys \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{"name": "production"}'

# => {
#   "code": 0,
#   "data": {
#     "api_key": "zp_live_4f6f1f3a9b2c8d7e6a5b4c3d2e1f0a9b",
#     "webhook_secret": "whsec_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
#     "fee_bps": 0
#   }
# }

Keep API keys server-side only. Never embed them in a browser or mobile app — anyone holding the key can create orders that settle to your addresses, and can read your order data.

Receiving addresses (prerequisite)

set per-chain receiving address

curl -X PUT https://api.zeropay.top/api/v1/boss/addresses \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{"chain": "base", "address": "0xYourReceivingAddress"}'

Address formats are validated per chain: EVM (0x + 40 hex), Solana (base58), Bitcoin/UTXO, NEAR, Aptos/Sui, TON, Tron, Stellar, XRP, Cardano, Starknet, Aleo and other major families.