Payments API

Request body#

Optional headers#

Examples#

{
  "amount_usd_cents": 5000,
  "accepted_tokens": [
    { "kind": "sol" },
    { "kind": "spl", "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" }
  ],
  "reference": "order-1001"
}

{
  "id": "d0714125-193a-4706-91d1-80854d829214",
  "derivation_index": 42,
  "address": "9xQe...pump",
  "client_secret": "cs_7pKf...9dQ2",
  "price_usd_cents": 5000,
  "mint": null,
  "mint_decimals": null,
  "expected_lamports": null,
  "status": "pending",
  "received_lamports": 0,
  "reference": "order-1001",
  "expires_at": "2026-07-26T13:10:00Z",
  "created_at": "2026-07-26T13:00:00Z",
  "updated_at": "2026-07-26T13:00:00Z",
  "refund_sender": null
}

mint, mint_decimals, and expected_lamports are null because the asset is not chosen yet, and payment_uri is absent for the same reason. Both fill in once the buyer calls POST /intents/select-token.

• A payment for a seller additionally carries marketplace_fee_bps, the cut rate frozen at create time.

Save derivation_index (poll status with it) and show address to the payer. Forward client_secret to your client if it will drive checkout.

The payment_uri#

payment_uri is a Solana Pay URI for address, built server-side. Render it as your QR code rather than assembling one yourself:

solana:<address>?amount=<ui_amount>&spl-token=<mint-if-token>&label=<your account name>

It is omitted while there is no amount to ask for (any USD-priced intent before token selection) and absent once the intent can no longer be paid (paid, swept, cancelled, refunding, refunded). It is present only while pending or underpaid, and on an underpaid intent the amount is the remaining shortfall. It is rebuilt on every status read — re-render from the latest response after a token selection or partial payment.

Errors#

{
  "tokens": [
    {
      "mint": "So11111111111111111111111111111111111111112",
      "is_native": true,
      "name": "Solana",
      "ticker": "SOL",
      "decimals": 9,
      "image_url": "https://assets.zuuppa.com/tokens/.../img-1a2b3c4d.png"
    },
    {
      "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "is_native": false,
      "name": "USD Coin",
      "ticker": "USDC",
      "decimals": 6,
      "image_url": null
    }
  ]
}

is_native marks native SOL — build its accepted_tokens entry as { "kind": "sol" }; every other row is an SPL token you reference as { "kind": "spl", "mint": "<mint>" }. image_url is null until an image has been uploaded (or if image storage isn't configured).

Response 200 OK, the same PaymentIntent object as POST /intents (this one does not include payment_uri; it returns the stored intent alone). Errors: 404 no intent for that reference.

curl -H 'Authorization: Bearer sk_live_...' \
  "https://api.zuuppa.com/intents?reference=order-1001"

{
  "id": "d0714125-...",
  "derivation_index": 42,
  "address": "9xQe...pump",
  "mint": null,
  "mint_decimals": null,
  "expected_lamports": 500000000,
  "status": "swept",
  "received_lamports": 500000000,
  "reference": "order-1001",
  "expires_at": "2026-07-26T13:15:00Z",
  "refund_sender": "Fx3X...gsy",
  "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..."]
  }
}

Response fields: the flattened PaymentIntent plus:

The settlement object#

The source of truth for accounting.

Errors: 404 no intent for that index.

Request body#

{ "index": 42 }

{
  "signature": "4bd...",
  "lamports_swept": 499995000,
  "platform_fee_lamports": 0,
  "from": "9xQe...pump",
  "to": "BLTpUS6b..."
}

• lamports_swept: base units delivered to the destination (net of platform fee).
• platform_fee_lamports: base units to the platform wallet.

Errors#

Request body#

{ "index": 42 }

Response 200 OK, the intent's status (same shape as GET /status), now cancelled (or refunding/refunded if a partial SOL balance is being returned).

Behavior#

• Only acts while the intent is pending/underpaid. If a payment already advanced it, the cancel is refused with 409.
• Idempotent: cancelling an already-cancelled/refunding/refunded intent returns 200 with its current status.
• Race-safe: if a payment confirms at the same instant, the payment wins and the cancel returns 409.
• A webhook fires either way: intent.cancelled, or intent.refunding then intent.refunded. An idempotent second cancel does not duplicate the event.

Errors#