Authentication

API keys (sk_)#

sk_ API key· Backend — Authorization: Bearer sk_… — your secret API key authenticates your backend to the payments API and the marketplace API. Its format is sk_<mode>_<random>, e.g. sk_live_... for production or sk_test_....

Where to get it#

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 is shown once at creation — store it securely.

How to send it#

An Authorization header:

Authorization: Bearer sk_live_...

What it can do#

Everything for the business the key belongs to — create and read intents (POST /intents, GET /intents, GET /status), sweep and cancel (POST /sweep, POST /cancel), and, if the business is an approved marketplace, the whole /marketplace/* surface and subscription management endpoints.

Scope#

A key acts as exactly one business (account). It cannot read or act on another business, and it never exposes buyer-facing secrets.

Rules#

• Keep it server-side. Never ship it to a browser or mobile app. For live buyer-facing UX, proxy status reads through your own backend, or use the per-intent cs_ client secret below.
• A request to a key-protected endpoint without a valid key returns 401.
• You can create and revoke keys from the dashboard at any time.

Client secrets (cs_) — the buyer SDK credential#

cs_ client secret· Browser / untrusted client — every POST /intents returns a client_secret (cs_...): a one-time, single-intent token. It authorizes the client-facing checkout endpoints so an untrusted client (a browser or mobile app) can drive checkout without ever seeing your sk_ key.

What it's for#

Reading one intent's live status, letting the buyer pick a pay-in token, previewing quotes, attaching buyer details, and cancelling — all scoped to that single intent.

Where to get it#

It is returned only on the first POST /intents response (the client_secret field). Only its hash is stored server-side, so it is never shown again; an idempotent-reference retry returns client_secret: null. Forward it to your client if you use the checkout SDK; otherwise ignore it.

How to send it#

In the request body ({"client_secret": "cs_..."}) or as a query param (?client_secret=cs_...), depending on the endpoint.

What it can't do#

It cannot read your account, other intents, or any merchant-only field. A leak exposes only that one payment. It is safe to embed in a client precisely for that reason.

Marketplace on-behalf-of header#

Marketplace header· sk_ + X-Zuuppa-On-Behalf-Of — an approved marketplace takes a payment for one of its sellers by adding one header to POST /intents:

X-Zuuppa-On-Behalf-Of: <seller_id>

The payment is created as that seller: its deposit address, its payout, its audit trail. The seller_id comes from POST /marketplace/sellers.

• The calling sk_ key must belong to a business with an active marketplace capability, and the seller must belong to that marketplace.
• customer.email becomes required on the create (a seller has no login).
• Every failure mode — a malformed UUID, a foreign or archived seller, an ordinary business id, or a revoked capability — answers a uniform 404 seller not found, so you can never probe for accounts you don't own.

Full detail in Marketplace API.

What is not covered here#

Dashboard login (used by the web/app UI) and platform-operator credentials are not part of the integration API and are not documented here. Everything a merchant integration needs is the sk_ key, the per-intent cs_ secret, and — for marketplaces — the on-behalf-of header.