API Documentation

What the current credentials are allowed to do. Returns the role behind a dashboard session, or null for an API key, which carries the account's full authority.

{
  "success": true,
  "data": {
    "userId": "usr_...",
    "merchantId": "mch_...",
    "role": "admin",
    "permissions": ["data:read", "money:write", "settings:write",
                    "webhooks:write", "keys:write", "payout:write", "team:write"]
  }
}

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": {
    "token": "eyJhbG...",
    "refreshToken": "eyJhbG...",
    "merchant": { "id": "...", "plan": "free" }
  }
}

Which sign-in methods this deployment has configured. Render only what is listed - a provider without credentials is not offered.

{
  "success": true,
  "data": {
    "providers": ["google", "microsoft", "apple"],
    "email": true
  }
}

Begin an OAuth sign-in. Redirects (302) to the provider. Send the browser here - do not fetch it. State, nonce and the PKCE verifier are held server-side for 10 minutes.

The provider returns the customer here; PayZap verifies the ID token and redirects to your dashboard callback with the JWT pair in the URL fragment (#access=…&refresh=…), so tokens never reach server logs or a Referer header. On failure the fragment carries #error= instead.

Exchange an API key for a JWT. The server-to-server path: an sp_ key authenticates this one call, and the returned token authorizes the rest of the API.

{
  "success": true,
  "data": {
    "token": "eyJhbGciOi...",
    "refreshToken": "eyJhbGciOi...",
    "merchant": { "id": "...", "plan": "free" }
  }
}

Refresh an expired access token.

Every account the signed-in person can open - their own and the ones they were invited to - with the role held in each. Needs only a valid session, so somebody removed from the account they are looking at can still find the way out to one they belong to.

{
  "success": true,
  "data": [
    { "merchantId": "9f2c…", "role": "admin", "email": "ops@acme.example", "brandName": "Acme" },
    { "merchantId": "3b7a…", "role": "viewer", "email": "finance@client.example", "brandName": null }
  ]
}

Open another of the person's accounts: a fresh token pair for an account they are a member of. From then on every way they sign in - the emailed link, Google - lands in that account until they switch again. Refused for an account they are not in.

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 the session with the address to pay. An API key is optional: with it, amount and currency set the price; without it the product price applies (a tip product takes the buyer's amount).

{
  "success": true,
  "data": {
    "id": "sess_...",
    "productId": "...",
    "merchantWallet": "0x...",
    "amount": "49.00",
    "asset": "USDT",
    "chain": "evm",
    "status": "pending",
    "orderRef": "order_98765",
    "expiresAt": "2026-03-17T12:30:00Z",
    // the hosted page that pays exactly this session (null for exchange pay)
    "checkoutUrl": "https://payzap.cc/pay/s/sess_...",

    // present only when `currency` was set - the locked quote.
    // fxRate is the effective rate, spread already applied.
    "fiatAmount": "558.84",
    "fiatCurrency": "BOB",
    "fxRate": "11.4048",
    "fxSource": "binance-p2p",
    "fxLockedAt": "2026-03-17T12:15:00Z"
  }
}

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

Declare the wallet that will pay this session (EVM, Tron, Solana). The hosted session page calls it when the wallet connects; call it yourself if you run your own wallet UI. When several open payments fit a transfer - same wallet, same amount - the one whose declared payer sent it wins, and the webhook says so. Can change until a transaction is claimed. Public - the session id is the credential.

{ "success": true, "data": { "payerAddress": "0xabc…" } }

Claim the transaction the wallet returned for this session. Needs a declared payer, and counts only if that payer is the sender on chain - claiming someone else's transaction does nothing. One transaction pays one session: 409 TX_CLAIMED when another holds it, CLAIM_LOCKED when this one holds a different one. The same claim again is a no-op. Public.

{ "success": true, "data": { "claimedTxHash": "0x…" } }

Everything the hosted session page renders: the session, its network and chain id, product name, merchant branding, and the payer and transaction already declared. Checkout sessions only. Public.

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.

Open a setup session and get a widget URL to show the customer once. They pick a method and authorize; you charge afterwards without them present.

{
  "success": true,
  "data": {
    "id": "8f2c...",
    "status": "pending",
    "customerRef": "user_44219",
    "setupUrl": "https://payzap.cc/setup/8f2c...",
    "setupExpiresAt": "2026-03-18T12:00:00Z",
    "returnUrl": "https://app.example.com/wallet/done",
    "metadata": { "regionCode": "BO-L" },
    "createdAt": "2026-03-17T12:00:00Z"
  }
}

Charge a customer's active mandate off-session. Returns immediately as pending; settlement is asynchronous - usually seconds, on-chain or when Binance confirms the deduction. Accepts an Idempotency-Key header - orderRef is NOT deduplicated on its own.

{
  "success": true,
  "data": {
    "id": "pay_...",
    "status": "pending",
    "customerRef": "user_44219",
    "orderRef": "order_98765",
    "mandateId": "8f2c...",        // which authorization was debited
    "amount": "6.53",
    "currency": "USD",
    "fiat": {                       // null unless a non-USD currency was sent
      "amount": 45.5,
      "currency": "BOB",
      "exchangeRate": { "rate": "11.2664", "lockedAt": "2026-03-17T12:15:00Z" }
    },
    "metadata": { "driverId": "drv_123" }
  }
}

List mandates. Filter by customerRef to find a customer's authorization, or by status to audit.

{
  "success": true,
  "data": [
    {
      "id": "8f2c...",
      "status": "active",
      "customerRef": "user_44219",
      "setupExpiresAt": "2026-03-18T12:00:00Z",
      "metadata": {},
      "createdAt": "2026-03-17T12:00:00Z"
    }
  ],
  "pagination": { "total": 1, "limit": 20, "offset": 0 }
}

Fetch one mandate, with the instruments bound to it. isActive marks the one future charges use; displayName is what to print on a saved-method row. A wallet is named only when its connector identified itself at bind time, so anything bound earlier reads as "Crypto wallet" - the label is the client's word and not something the chain records. capUnits and remainingUnits are base units: divide by 10^tokenDecimals. remainingUnits is null when the allowance could not be read just then. The list endpoint omits methods, since reading them touches the chain per instrument.

{
  "success": true,
  "data": {
    "id": "8f2c...",
    "status": "active",
    "customerRef": "user_44219",
    "setupExpiresAt": "2026-03-18T12:00:00Z",
    "metadata": { "regionCode": "BO-L" },
    "createdAt": "2026-03-17T12:00:00Z",
    "methods": [
      {
        "id": "3d91...",
        "kind": "evm_wallet",
        "displayName": "MetaMask",
        "isActive": true,
        "network": "polygon",
        "tokenSymbol": "USDT",
        "tokenDecimals": 6,
        "customerWallet": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
        "capUnits": "5000000000",
        "remainingUnits": "4870000000",
        "revokedAt": null
      },
      {
        "id": "a17b...",
        "kind": "binance_pay",
        "displayName": "Binance",
        "isActive": false,
        "network": null,
        "tokenSymbol": "USDT",
        "tokenDecimals": null,
        "customerWallet": null,
        "capUnits": null,
        "remainingUnits": null,
        "revokedAt": null
      }
    ]
  }
}

The active mandate for one of your users, addressed by your own id, with the same methods array as GET /v1/mandates/:id. Saves storing our mandate id alongside your user record and keeping the two in sync. 404 when that customer has no active authorization.

Revoke by your own user id. Same effect as revoking by mandate id - emits mandate.revoked with reason "api".

Re-open the widget for a customer who is ALREADY set up, so they can see or change their payment method. Use this rather than creating another setup session: a second session mints a second mandate, and the customer only discovers the problem at the end, when binding fails against the one-active-per-customer rule after they have already signed.

{
  "success": true,
  "data": {
    "id": "8f2c...",
    "status": "active",
    "customerRef": "user_44219",
    "setupUrl": "https://payzap.cc/setup/8f2c..."
  }
}

End an authorization from your side - the customer deleted their payment method, closed the account, or anti-fraud fired. Emits mandate.revoked with reason "api". Idempotent: revoking twice does not emit twice. A Binance contract behind it is ended at Binance too, within about a minute.

Everything the setup page renders: which bind options this merchant can offer, the networks a charge can actually settle on, the address an on-chain approval must name, and every method already connected. Public - possession of the unguessable link is the authorization, so it carries only what a payer needs and never the merchant's other data.

{
  "success": true,
  "data": {
    "id": "9f2c1d5e-4a3b-4c8d-9e10-7b6a5c4d3e2f",
    // pending | active | revoked | expired
    "status": "active",
    // your own id for this customer, as sent at session creation
    "customerRef": "fleet_4417",
    "setupExpiresAt": "2026-08-19T10:00:00.000Z",

    // The address the customer's approve() must name. Null when the
    // facilitator is not configured, in which case evm_wallet is absent
    // from availableKinds too.
    "spenderAddress": "0x...",
    // Base58 addresses a Tron approve and a Solana delegation must name.
    // Null where that chain is not offered.
    "tronSpenderAddress": "T...",
    "solanaDelegateAddress": "Ba3j...",

    // What this page may offer. Driven by what is actually usable:
    // evm_wallet needs the facilitator, binance_pay needs the merchant's
    // own exchange credentials on file.
    "availableKinds": ["evm_wallet", "binance_pay"],

    // The per-payment limit a Binance contract may carry (Binance's own
    // default). Null when binance_pay is not offered.
    "binanceMaxLimit": 50,

    // Networks a charge can settle on - narrower than the chain list used
    // for checkout, so the page must not offer the difference.
    "supportedNetworks": ["polygon", "arbitrum", "base", "ethereum"],

    // Shown so the customer sees WHO will be charging them. Approving an
    // allowance to an unnamed page reads as a drainer.
    "merchant": {
      "brandName": "Yango",
      "logoUrl": "https://...",
      "accentColor": "#FF0000"
    },

    // Where the page sends the customer once they are done - the returnUrl
    // set on the session or on manage. Null when none was set.
    "returnUrl": "https://app.example.com/wallet/done",

    // Every connected instrument. Exactly one has isActive: true - the
    // database enforces it - and that is the one future charges use.
    "methods": [
      {
        "id": "3e8a...",
        // evm_wallet | tron_wallet | solana_wallet | binance_pay
        "kind": "evm_wallet",
        "isActive": true,
        "network": "polygon",
        "tokenSymbol": "USDT",
        "customerWallet": "0x...",
        // What the customer APPROVED, in the token's base units, as a
        // string. Divide by 10^tokenDecimals for a human figure.
        // MAX_UINT256 means they approved an unlimited allowance.
        "capUnits": "1000000000",
        // What is actually LEFT, read from the chain when this was built.
        // Charging draws the allowance down, so this is the number that
        // decides whether the next charge succeeds. Null means we could
        // not reach the chain - unknown, never zero.
        "remainingUnits": "300000000",
        "tokenDecimals": 6,
        // Set once revoked; a revoked method can never be made active.
        "revokedAt": null
      }
    ]
  }
}

Choose which connected method future charges use. A failed charge never moves to another instrument on its own - that is the customer's money and their choice - so this is how the choice gets made. Refuses a revoked method and a revoked mandate rather than activating something the next charge would fail on.

{
  "success": true,
  "data": {
    // The full line-up after the switch, same shape as in mandate-setup.
    // Exactly one carries isActive: true.
    "methods": [
      { "id": "3e8a...", "kind": "evm_wallet", "isActive": true, "...": "..." },
      { "id": "7b1c...", "kind": "binance_pay", "isActive": false, "...": "..." }
    ]
  }
}

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). B2B deposits are refused: a top-up is a partner funding their own balance, and reversing one would send your money to whatever address it happened to arrive from while the credit on your platform stayed put. Correct those in your own ledger.

// 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).

Open a top-up from a figure in the partner's own currency, before they have chosen a network. Returns a locked rate and no address - the address depends on the network, which they pick next. Server-to-server: the partner never asserts who they are. Refused with 400 VALIDATION_ERROR until deposits are activated for your account.

{
  "success": true,
  "data": {
    "id": "9f2c1d5e-4a3b-4c8d-9e10-7b6a5c4d3e2f",
    "status": "draft",
    "partnerRef": "fleet_4417",
    "asset": "USDT",
    // what they will send, held for the window below; if they choose a
    // network after it, the figure is re-quoted first
    "estimatedAmount": 441.85,
    "credit": {
      "amount": 5000,
      "currency": "BOB",
      "rate": 11.3157,
      "lockedAt": "2026-08-15T10:00:00.000Z"
    },
    // short: this holds a rate they are looking at and have not acted on
    "expiresAt": "2026-08-15T10:15:00.000Z"
  }
}

The partner has chosen where they are sending from. Issues this deposit its own address and fixes the amount, and returns the same shape as a created deposit. Public - this happens in their browser, so possession of the unguessable id is the authorization. The rate is the one locked at the draft, never re-quoted. Choosing twice is refused.

Open a top-up for one of your partners. Returns the amount they must send and an address issued for this deposit alone. Idempotent - a retry with the same Idempotency-Key returns the original deposit rather than opening a second one. Refused with 400 VALIDATION_ERROR until deposits are activated for your account.

{
  "success": true,
  "data": {
    "id": "9f2c1d5e-4a3b-4c8d-9e10-7b6a5c4d3e2f",
    "status": "pending",
    "partnerRef": "fleet_4417",
    "chain": "evm",
    "network": "polygon",
    "asset": "USDT",

    // what they must send - exactly what was asked for
    "amount": 500,
    // the same figure, kept for readers of the older shape
    "requestedAmount": 500,
    // this deposit's own address, never reused
    "address": "0x...",
    "receiverKind": "derived",

    // present only when `creditCurrency` was set
    "credit": {
      "amount": 5702.74,
      "currency": "BOB",
      "rate": 11.4048,
      "lockedAt": "2026-08-13T22:21:52.791Z"
    },
    "expiresAt": "2026-08-14T22:21:52.791Z"
  }
}

List your deposits. Filter by status or partnerRef.

Get a single deposit by ID. Carries a receiving block: the address the partner was given, and - for a per-deposit address - every sweep of it into your treasury, with the transaction hash and whether the chain confirmed it. That is what reconciliation needs and used to have no source for: the deposit said completed and the money had moved on without a trace here. Once completed, the credit is the one for what arrived, and metadata keeps receivedAmount and the credit first quoted (quotedCredit).

Edit a deposit that has not been sent to a partner yet. Only while it is a draft: once a network is chosen the partner is looking at an address and an exact amount, and may already be sending it. Changing the fiat side re-quotes, so the crypto figure follows and the quote window restarts.

Withdraw a deposit. A draft is removed outright - nothing was handed out, so nothing can arrive against it. Anything with an address issued is expired instead and stops being watched, because that address is already in your partner's hands: a transfer that crosses with the cancellation shows up in the unmatched queue rather than disappearing. A deposit already confirming or completed is refused.

{
  "success": true,
  "data": {
    "id": "630eda47-0eef-47bd-8af0-afcc9937a1ec",
    "deleted": false,
    "status": "expired"
  }
}

Totals across your deposits. Volume is in the stablecoin rather than fiat - partners may be credited in several currencies at once. Counted over completed deposits only: a pending one is an invitation, not money. successRate is null until at least one deposit reaches an end state, and excludes those still waiting.

{
  "success": true,
  "data": {
    "volume": 12480.5,
    "completed": 37,
    "awaiting": 2,
    "unpaid": 5,
    "successRate": 88.09523809523809
  }
}

Arrivals that matched no open deposit - a deposit's address paid after the deposit expired or was cancelled, or paid a second time. A short transfer to an open deposit does not land here: it settles, credited for what arrived. The money is already yours; this is the queue for deciding whose it is.

Credit an unmatched arrival to one of your deposits, or dismiss it. Settles through the same path an automatic match takes, so your webhook fires exactly as it would have - a reviewed deposit is not a second kind of event to handle.

What the deposit page renders. Public - possession of the unguessable id is the authorization, same as a checkout session. Carries only what a payer needs: it does not name your other addresses or the partner's balance.

Who signs for the account's receiving wallet and how many of them must: the signers, the threshold, the actions still waiting for signatures - each saying whether you have already signed it and whether it can still be signed - and the code you have requested but not yet entered. Dashboard session; any role.

{
  "success": true,
  "data": {
    "owners": [
      { "userId": "63a0…", "userName": "admin ops@acme.example", "userEmail": "ops@acme.example" },
      { "userId": "f859…", "userName": "owner cfo@acme.example", "userEmail": "cfo@acme.example" }
    ],
    "threshold": 2,
    "pending": [
      {
        "fingerprint": "sha256:5fc2…",
        "title": "Owners set to 1 with threshold 1 of 1",
        "status": "consensus-needed",
        "initiatedBy": "ops@acme.example",
        "votes": [{ "who": "ops@acme.example", "selection": "approved", "at": "2026-09-15T21:57:07.000Z" }],
        "signedByMe": true,
        "stale": false
      }
    ],
    "myRequest": null
  }
}

Name an action and ask for the code that signs it. The action is checked first - an address that is not one, a threshold nobody could reach, a proposal already signed by you - and refused in words before any code goes out. Then a one-time code is emailed to the address you are signed in with, and the code is good for that one action. Signers, threshold, payout address and schedule need settings:write; paying out needs money:write; approving and rejecting need only to be a signer.

{
  "success": true,
  "data": {
    "sentTo": "ops@acme.example",
    "summary": "Set the EVM payout address to 0x53ae…25ae"
  }
}

Enter the code. The action named at request time is carried out with a key that the code unlocks for the signer alone; the platform never holds it beyond the moment. "completed" means done. "consensus-needed" means your signature is in and the other signers have been emailed; nothing changes until enough of them approve, within a day. "failed" carries the wallet's reason.

{
  "success": true,
  "data": {
    "status": "consensus-needed",
    "summary": "Set the EVM payout address to 0x53ae…25ae",
    "fingerprint": "sha256:9a1b…",
    "waiting": "the new payout address",
    "failure": null
  }
}

The wallet's own log, in words, newest first: every address issued, every sweep and payout signed, every signer added, every code sent and entered. Kept outside our database, so it is the record that cannot be edited from here.

Where the treasury is paid out to per chain family - read back from the wallet's own policy, so a change that has just collected its last signature shows up here - alongside the treasury addresses, the schedule, whether a payout pass is running right now, and the history of payouts with their transaction hashes.

{
  "success": true,
  "data": {
    "config": {
      "addresses": { "evm": "0x53ae…25ae" },
      "interval": "weekly", "hourUtc": 9, "weekday": 1, "minAmount": 100,
      "lastRunAt": "2026-09-17T11:33:28.371Z", "updatedBy": "ops@acme.example"
    },
    "treasury": { "evm": "0x6462…4e69", "tron": "TTb7…JBHN" },
    "run": null,
    "payouts": [
      {
        "id": "…", "chain": "polygon", "asset": "USDT", "rawAmount": "500000",
        "fromAddress": "0x6462…4e69", "toAddress": "0x53ae…25ae",
        "txHash": "0xcfa2…55d9", "status": "confirmed", "failure": null,
        "initiatedBy": "ops@acme.example", "createdAt": "2026-09-17T11:33:28.280Z", "confirmedAt": "2026-09-17T11:33:41.000Z"
      }
    ]
  }
}

Everything anybody changed in this account from the dashboard, newest first: who, what, and when - in words, without secrets. This is the account's own log; the wallet's signatures are in /v1/merchant/signers/history.

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..."
  }
}

The settlement register for a day: every payment that confirmed and every refund that settled, one stream, with the commission charged on each. Refunds carry a negative amount so a period nets without special-casing rows. Figures come from what was recorded at settlement, so re-requesting an old day returns the same file.

{
  "success": true,
  "period": { "from": "2026-03-17T00:00:00Z", "to": "2026-03-18T00:00:00Z" },
  "count": 2,
  "data": [
    {
      "trust_payment_id": "order_98765",   // your order id
      "transaction_id": "pay_01jt6cd...",  // ours
      "trust_refund_id": null,
      "refund_id": null,
      "amount": "45.50",
      "currency": "USDT",
      "commission": "0.34",
      "currency_commission": "USD",
      "payment_method": "evm",             // where the money went
      "network": "polygon",
      "status": "completed",
      "settled_at": "2026-03-17T12:04:11Z"
    },
    {
      "trust_payment_id": "order_98765",
      "transaction_id": "pay_01jt6cd...",
      "trust_refund_id": "yandex_refund_11",
      "refund_id": "rfnd_01jt...",
      "amount": "-45.50",                  // negative: it reverses the row above
      "currency": "USDT",
      "commission": "0",
      "currency_commission": "USD",
      "payment_method": "evm",
      "network": "polygon",
      "status": "confirmed",
      "settled_at": "2026-03-17T15:20:03Z"
    }
  ]
}

Period totals. Opening and closing balance are always zero and chargebacks are always zero - funds move from payer to merchant without resting with us, and an on-chain transfer cannot be reversed by an issuer. The lines are kept rather than dropped so the shape matches a conventional acquirer report.

{
  "success": true,
  "data": {
    "period": { "from": "2026-03-01T00:00:00Z", "to": "2026-04-01T00:00:00Z" },
    "opening_balance": 0,
    "total_authorized": 128450.75,
    "total_refunded": 3200.00,
    "total_chargebacks": 0,
    "commission": 962.51,
    "transferred_to_merchant": 125250.75,
    "closing_balance": 0
  }
}

Create a webhook endpoint. Takes an API key, so an integration can set up its own notifications without a trip through the dashboard. The secret is returned only once - store it securely, it is what verifies our signature. URLs pointing at private or internal networks are refused.

{
  "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.

Change where an existing key may be used from, without reissuing it. Use this when your servers move.

List API keys (without secret values).

Revoke an API key.

Get your enabled payment methods and EVM networks, and the state of B2B deposits: whether they are switched on, whether they are active (the receiving wallet has been set up), and the treasury address per chain that deposits are collected into.

{
  "success": true,
  "data": {
    "enabledMethods": ["evm", "ton", "binance_pay"],
    "evmNetworks": ["ethereum", "base", "arbitrum"],
    "depositsEnabled": true,
    "depositsActive": true,
    "treasury": { "evm": "0x...", "tron": "T..." }
  }
}

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. Binance mandates (Direct Debit) also need three things on Binance's side: Direct Debit enabled for your merchant account (Binance whitelists it through merchant@binance.com); if the API key is restricted by IP, our server addresses on it (ask your PayZap contact); and https://api.payzap.cc/v1/webhooks/binance-pay as the webhook URL in the Binance merchant portal. Without that webhook a signature is still picked up seconds later, but a contract cancelled in the Binance app is only noticed at the next charge.

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