Zuuppa API

It works for native SOL and any SPL token (including Token-2022). You integrate using an API key from your dashboard and never touch private keys, Solana RPC, or on-chain logic — the platform owns all of that.

Who this is for#

Anyone building a payments flow on Solana who wants:

• A unique deposit address per order/user/invoice — no address reuse.
• Server-side payment detection: your app polls a status endpoint or receives a signed webhook.
• Automatic settlement: funds swept to your treasury as soon as they arrive, with automatic refunds for overpayments, expiries, and wrong assets.
• Exact accounting: the precise amount that landed in your wallet per order.
• Optional platform fees.
• Marketplace payments: take a payment that belongs to another business, settle it directly to that business, and keep a cut in the same transaction.
• Recurring billing: subscriptions authorized on-chain, charged automatically.

Typical uses: e-commerce checkout, event ticketing, invoicing, top-ups, marketplaces, donations, and subscriptions.

How it works in 30 seconds#

1. Your backend  ──POST /intents──▶  Zuuppa   → returns a deposit address + client_secret
2. The buyer picks which asset to pay in (POST /intents/select-token)
3. Your frontend shows that address (+ QR from payment_uri) to the payer
4. Payer sends SOL/USDC/etc. to the address
5. Zuuppa detects it, sweeps it to YOUR wallet (minus any platform fee)
6. Your backend learns via webhook (or GET /status?index=N): "swept", exact amounts

Every payment is priced in USD. The buyer chooses the asset at checkout and the server converts the USD price to that asset's base units at spot. There is no way to price an intent directly in a token's base units.

You only ever call the HTTPS API. The server holds one master seed and derives every deposit address from it, so it can sign the sweep for any address without storing per-address keys.

Quick example#

Create a $50.00 invoice payable in SOL or USDC:

curl -X POST https://api.zuuppa.com/intents \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount_usd_cents": 5000,
        "accepted_tokens": [
          { "kind": "sol" },
          { "kind": "spl", "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" }
        ],
        "reference": "order-1001"
      }'

The sk_... API key comes from your dashboard: sign up, set your sweep destination, fee, and webhook in Settings, then create a key.

{
  "id": "1c9e...",
  "derivation_index": 42,
  "address": "9xQe...pump",
  "price_usd_cents": 5000,
  "mint": null,
  "mint_decimals": null,
  "expected_lamports": null,
  "status": "pending",
  "client_secret": "cs_...",
  "expires_at": "2026-08-18T14:08:02Z"
}

mint and expected_lamports are null because the asset is not chosen yet. Show address to the payer, and have the buyer select an asset:

curl -X POST https://api.zuuppa.com/intents/select-token \
  -H 'Content-Type: application/json' \
  -d '{"client_secret": "cs_...", "mint": null}'

That locks mint, mint_decimals, and expected_lamports, and returns a payment_uri (a Solana Pay URI) to render as the QR code. Then poll:

curl -H 'Authorization: Bearer sk_live_...' \
  "https://api.zuuppa.com/status?index=42"

When paid and settled:

{
  "status": "swept",
  "action": "swept",
  "message": "Payment received and settled.",
  "settlement": {
    "asset": "SOL", "decimals": 9,
    "destination_amount": 499995000, "destination_ui": 0.499995,
    "platform_fee_amount": 0, "platform_fee_ui": 0.0,
    "signatures": ["4bd..."]
  }
}

settlement.destination_amount is exactly what landed in your treasury wallet for order-1001.

Public configuration#

GET https://api.zuuppa.com/config is open (no auth) and returns the platform's current client-facing facts: the checkout window in seconds, the Solana network fee, the platform fee in force, the list of webhook event types, the maximum marketplace fee in basis points, and (when enabled) subscription limits. Read it at startup rather than hard-coding these values.

Where to go next#

Read in order for a full integration, or jump to what you need:

• Core concepts — intents, unique deposit addresses, USD pricing, assets, the settlement lifecycle, and the business / seller / marketplace model. Read this first.
• Authentication — the three credentials: sk_ keys, per-intent cs_ client secrets, and the on-behalf-of header.
• Payments API — the core create/read/sweep/cancel contract, with errors and idempotency.
• Checkout SDK — the client-facing cs_ endpoints, in call order.
• Marketplace API and Subscriptions API — sellers, fee splits, and recurring billing.
• Webhooks — event types, signature verification, retries.
• Integration guides — end-to-end walkthroughs for the three flows.