Guides

Integration Guide

Practical, end-to-end walkthroughs. Examples are in TypeScript/Node, but the flow is language-agnostic — it's just HTTPS. Base URL https://api.zuuppa.com.

Golden rule

Your backend calls POST /intents and reads /status — both need your sk_ key. Your frontend can drive checkout with the per-intent cs_ client secret. Order fulfillment is a backend decision keyed off the swept status or the intent.swept webhook — never trusted from the browser.

The payment flow#

Text

┌─────────────┐        ┌──────────────┐        ┌─────────────────┐
│ Your        │        │ Your         │        │ Zuuppa          │
│ Frontend    │        │ Backend      │        │ api.zuuppa.com  │
└──────┬──────┘        └──────┬───────┘        └────────┬────────┘
       │  checkout            │                         │
       │─────────────────────▶│  POST /intents          │
       │                      │────────────────────────▶│
       │  address + cs_       │◀────────────────────────│
       │◀─────────────────────│                         │
       │  POST /intents/select-token  (cs_, no API key)   │
       │────────────────────────────────────────────────▶│
       │  amount + payment_uri (QR)                      │
       │◀────────────────────────────────────────────────│
   [payer sends funds on-chain] ───────────────────────▶ (Zuuppa detects, auto-sweeps)
       │  poll / webhook      │  GET /status?index=N     │
       │─────────────────────▶│────────────────────────▶ │
       │  "swept" + amount    │◀──────────────────────── │
       │◀─────────────────────│  fulfill order           │

The three tracks#

Track 1

Custom checkout

You price the order in USD cents and list the assets the buyer may pay in.

Track 2

Marketplace payment

Take a payment for one of your sellers and split the settlement in one transaction.

Track 3

Subscription

Recurring billing: the subscriber authorizes an on-chain allowance once, you charge each period.

Every track ends the same way: your backend learns the outcome from the webhook (recommended) or by polling GET /status, and fulfills on swept.