Guides

Marketplace Payment

If your business is an approved marketplace, one extra header takes the payment for one of your sellers instead of for you — and splits the settlement in the same on-chain transaction.

Prerequisite

Your business must have an active marketplace capability (you apply from the dashboard and are approved by a platform operator). See the Marketplace API for the seller model and the fee split.

Step 1 — create a seller

Create the seller first; its id is what you'll reference on the payment.

TypeScript

await fetch(`${SERVER}/marketplace/sellers`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "Authorization": `Bearer ${API_KEY}` },
  body: JSON.stringify({
    name: "Ada's Ceramics",
    external_id: "seller-42",              // idempotency key
    sweep_destination: "SellerWa11et...",  // where their money lands
  }),
});
// response.seller.id is what goes in X-Zuuppa-On-Behalf-Of

Step 2 — take the payment for the seller

Create an ordinary intent with one extra header and one extra requirement:

TypeScript

const res = await fetch(`${SERVER}/intents`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${API_KEY}`,
    "X-Zuuppa-On-Behalf-Of": sellerId,     // from POST /marketplace/sellers
  },
  body: JSON.stringify({
    amount_usd_cents: Math.round(usd * 100),
    accepted_tokens: [{ kind: "sol" }],
    reference: orderId,
    application_fee_bps: 400,              // optional: your cut on this payment
    customer: { email: buyerEmail },       // REQUIRED for a seller's payment
  }),
});

Three differences from your own payment#

customer.email is required — a create without it is a 400. A seller has no login and the platform sends no email.
The settlement splits three ways in one transaction: the seller's share to the seller's wallet, your cut to yours, the platform fee to the platform. Marketplace splitting is SOL only today.

Everything downstream is unchanged — the same client_secret, payment_uri, and /status reads. Webhooks arrive at your endpoint, signed with your secret, and carry account.is_seller: true so you know whose payment it was.

The cut rate (application_fee_bps, 0–5000) is resolved once at create time and frozen onto the intent as marketplace_fee_bps: the request's application_fee_bps, else the seller's override, else the marketplace's default. Any bad X-Zuuppa-On-Behalf-Of value answers a uniform 404 seller not found.

Full seller management (create, edit, archive, payouts, stats, audit) is in the Marketplace API. Handling the split in settlement is covered under Webhooks.