API Documentation

Get a one-time nonce for wallet signature authentication. Nonces expire after 5 minutes.

{
  "success": true,
  "data": {
    "nonce": "a1b2c3d4...",
    "message": "Sign in to PayZap\n\nNonce: a1b2c3d4..."
  }
}

Authenticate with a wallet signature. Returns JWT access + refresh tokens.

{
  "success": true,
  "data": {
    "accessToken": "eyJhbG...",
    "refreshToken": "eyJhbG...",
    "merchant": { "id": "...", "plan": "free" }
  }
}

Refresh an expired access token.

Create a new product.

List your products.

Get a single product by ID.

Update a product. All fields optional.

Deactivate a product (soft delete).

Resolve a short-link slug to its productId. Public — no auth. Atomically increments the slug click counter (used for influencer / channel attribution). The /r/<slug> page on payzap.cc calls this internally before redirecting to /pay/<productId>; merchants typically don't hit this directly except for analytics tooling.

{
  "success": true,
  "data": {
    "productId": "13463560-8a8b-44e1-8216-63c2bf205a43",
    "slug": "coffee",
    "clicks": 1247
  }
}

Create a payment session. Returns a session with wallet address and payment link. Public endpoint — no auth required.

{
  "success": true,
  "data": {
    "id": "sess_...",
    "productId": "...",
    "merchantWallet": "0x...",
    "amount": "49.00",
    "asset": "USDT",
    "chain": "evm",
    "status": "pending",
    "expiresAt": "2026-03-17T12:30:00Z",
    "paymentUrl": "https://payzap.cc/pay/prod_..."
  }
}

Get session status. Use for polling from your frontend. Public — no auth.

List your payment sessions. Supports filtering by customerRef (the external order ID you passed at session creation — exact match) and status. Useful when an upstream system like a taxi backend needs to round-trip "what is the state of order_42?" without keeping its own session-id mapping.

Get a single payment by ID.

Initiate a refund for a completed payment. Returns a discriminated union keyed on `refundMode`. Cross-chain — works for EVM (permit + sponsored), Tron, and Solana. The shape of the response tells the merchant exactly what to do next: sign typed-data (permit), build an ERC-20 transfer (sponsored), build a TRC-20 transfer (tron), or sign a pre-built fee_payer transaction (solana).

// EVM permit-mode (USDC / DAI / ERC-3009)
{
  "success": true,
  "data": {
    "refundId": "rfnd_...",
    "amount": 49,
    "asset": "USDC",
    "buyerWallet": "0x...",
    "refundMode": "permit",
    "permitData": {
      "domain": { "name": "USD Coin", "version": "2", "chainId": 8453, "verifyingContract": "0x..." },
      "types": { "Permit": [...] },
      "primaryType": "Permit",
      "message": { "owner": "0x...", "spender": "0x...", "value": "49000000", "nonce": "0", "deadline": "..." }
    }
  }
}

// EVM sponsored-mode (USDT, BSC USDC, etc — non-permit tokens)
{
  "success": true,
  "data": {
    "refundId": "rfnd_...",
    "amount": 49,
    "asset": "USDT",
    "buyerWallet": "0x...",
    "refundMode": "sponsored",
    "merchantWallet": "0x...",
    "tokenAddress": "0x...",
    "chainId": 8453,
    "rawAmount": "49000000",
    "gasSponsored": true,
    "gasSponsorTxHash": "0x..."
  }
}

// Tron-mode (USDT / USDC TRC-20)
// energyDelegated=true means PayZap rented ~65k energy + bandwidth via
// TronZap and delegated it to the merchant address for 1 hour, so the
// refund broadcast costs the merchant 0 TRX (PayZap absorbs ~$1).
{
  "success": true,
  "data": {
    "refundId": "rfnd_...",
    "amount": 49,
    "asset": "USDT",
    "buyerWallet": "T...",
    "refundMode": "tron-transfer",
    "merchantWallet": "T...",
    "tokenAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "rawAmount": "49000000",
    "energyDelegated": true,
    "energyAmount": 64285,
    "energyTransactionId": "01kqq..."
  }
}

// Solana-mode (USDC / USDT SPL)
// serializedTx, when non-null, is base64 of a transaction with feePayer
// set to PayZap's facilitator and partial-signature already applied.
// Merchant adds their token-authority signature in their wallet and
// submits — pays 0 SOL. If serializedTx is null, the facilitator was
// unavailable; merchant builds + sends the SPL transfer themselves
// (paying ~$0.0004 in SOL).
{
  "success": true,
  "data": {
    "refundId": "rfnd_...",
    "amount": 49,
    "asset": "USDC",
    "buyerWallet": "Buyer11...",
    "refundMode": "solana-transfer",
    "merchantWallet": "Merch11...",
    "mintAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "rawAmount": "49000000",
    "decimals": 6,
    "serializedTx": "AQA...base64...",
    "feePayer": "FacilitatorAddr11..."
  }
}

Submit a signed permit for a refund (EVM permit-mode only — USDC, DAI, ERC-3009 tokens). Enqueues `permit() + transferFrom(merchant → buyer)` via the x402 settlement queue. Returns immediately; the refund.completed webhook fires when the on-chain settlement confirms.

Confirm a refund where the merchant has already broadcast the on-chain transfer. Multi-chain — backend dispatches based on the refund's chain. EVM: 0x-prefixed 64-hex tx hash; backend reads receipt + verifies the Transfer event recipient + amount within 0.1%. Tron: 64-char hex txID (with or without 0x); backend hits TronGrid getTransactionInfoByID and matches the TRC-20 Transfer event. Solana: base58 transaction signature; backend reads getTransaction.meta.postTokenBalances delta on the buyer's ATA and requires it == expected raw amount within 0.1%. Each chain enforces a 0.1% tolerance on the amount delta to catch wrong-amount refunds; rejects fire `refund.failed` webhook.

List all refunds for a payment session, including past attempts (cancelled, failed) for audit.

Get a single refund by ID with current status (pending, submitted, confirmed, failed, cancelled).

Build EIP-2612 permit data for a gasless USDC/DAI payment. Buyer's wallet signs the returned typed-data; the signed permit is then submitted via /permit. Public — no auth.

Submit a signed EIP-2612 permit. Backend enqueues `permit() + transferFrom()` for on-chain settlement. Public — no auth.

Send a small amount of native gas (ETH/MATIC/BNB) to the buyer so they can broadcast a normal ERC-20 transfer. Used for USDT and BSC USDC where there's no permit. Public — no auth, rate-limited.

Rent ~65k Energy + ~1.5k Bandwidth from TronZap and delegate to the buyer's TRON address so a TRC-20 USDT transfer costs 0 TRX. Idempotent. Public — no auth, rate-limited.

Quote-only — returns the estimated Energy + cost for delegating to a buyer's TRON address. Used by the widget to show gas-fee badges. Public.

Build an SPL transfer with feePayer set to PayZap's Solana facilitator and pre-sign as fee_payer. Returns the base64 transaction; the buyer's wallet adds their signature and broadcasts. Buyer pays 0 SOL. Public — no auth.

{
  "success": true,
  "data": {
    "serializedTx": "base64...",
    "feePayer": "Ba3jY..."
  }
}

Create a webhook endpoint. The secret is returned only once — store it securely.

{
  "success": true,
  "data": {
    "id": "whk_...",
    "url": "https://example.com/webhook",
    "events": ["payment.completed", "payment.failed"],
    "secret": "whsec_..."
  }
}

List your webhook endpoints.

Update a webhook URL or event filter.

Delete a webhook endpoint.

Send a test webhook event to verify your endpoint.

Get your merchant profile, wallets, and usage.

List your connected wallets.

Add a new wallet address.

Remove a wallet.

Create an API key. The raw key is returned only once.

List API keys (without secret values).

Revoke an API key.

Get your enabled payment methods and EVM networks.

{
  "success": true,
  "data": {
    "enabledMethods": ["evm", "ton", "binance_pay"],
    "evmNetworks": ["ethereum", "base", "arbitrum"]
  }
}

Update enabled payment methods and EVM networks.

List your exchange API credentials (secrets are masked).

{
  "success": true,
  "data": [
    {
      "id": "...",
      "provider": "binance_pay",
      "apiKey": "abc***xyz",
      "merchantIdExt": "123456",
      "active": true
    }
  ]
}

Add or update exchange API credentials. Required to accept Binance Pay or Bybit Pay.

Remove exchange credentials. Provider: "binance_pay" or "bybit_pay".