Quickstart

You'll need an sk_ API key. Your backend calls POST /intents and reads GET /status (both need the key); your frontend can drive checkout with the per-intent cs_ client secret returned on create. Order fulfillment is always a backend decision keyed off the swept status or the intent.swept webhook — never trusted from the browser.

Five steps to your first payment#

1. 1

   Get an API key

   Sign up for a dashboard account, set your sweep destination, platform-fee handling, and webhook on the Settings page, then create an API key. The full key (sk_live_... or sk_test_...) is shown once at creation — store it securely and keep it server-side.

   Shell

   export ZUUPPA_API_KEY="sk_live_..."   # from your dashboard, kept on the server

2. 2

   Create a payment intent

   Price in USD cents and list the assets the buyer may pay in. Pass a stable reference (your order id) — it doubles as the idempotency key, so a retry returns the same deposit address instead of creating a second one.

   cURL

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

   200 OKPOST /intents

   JSON

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

   Store derivation_index against your order (you poll status with it), show address to the payer, and forward client_secret to your client if it will select the token. mint and expected_lamports are null until the buyer picks an asset.

3. 3

   Let the buyer pick an asset

   Nothing is payable until the buyer chooses one of accepted_tokens. This call is authorized by the cs_ client secret, so an untrusted client can make it directly — no API key needed.

   cURL

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

   This locks mint, mint_decimals, and expected_lamports (the USD price converted at spot), and returns a payment_uri that now carries the amount. Selection is re-runnable while pending and refused with 409 once a payment lands. To show what each option costs first, read GET /intents/quote?client_secret=cs_....

4. 4

   Show the deposit address

   Render payment_uri as the QR code and show address as text beside it — it's a Solana Pay URI built server-side, so don't assemble one yourself. It's omitted before token selection (fall back to a QR of the bare address) and once the intent can no longer be paid; on an underpaid intent it asks for the remaining shortfall. Re-render from the latest status response.

5. 5

   Learn the outcome and fulfill

   Prefer webhooks for fulfillment; use polling for live UI. Poll GET /status?index=N until the status is terminal:

   cURL

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

   When the payment is received and settled:

   200 OKGET /status?index=42

   JSON

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

   swept means the money is yours. settlement.destination_amount is exactly what landed in your treasury wallet (net of the network fee, any platform fee, and any refunded overpayment) — use it for your books.