Use cases

Find what you’re building. Each recipe lists the objects, calls and events it uses. New to the objects? Read Core concepts first.

You’re building	Recipe
A SaaS that sells something once	One-off checkout
A SaaS on monthly plans	Subscriptions
A shop with no code at all	Payment links
A marketplace or vertical software	Connect
An API agents pay for, per request	HTTP 402
An agent that buys things	Agent cards
A bookings site	Deposits and no-shows
UK collections from bank accounts	Direct Debit (UK businesses only; US bank debits come later) (SEPA Direct Debit in Europe, by application)

SaaS one-off checkout

When: a customer buys one thing (a plan upgrade, a report, credits) and you fulfil it.

1. CreatePOST /v1/payments
2. Payapproval_url or client_secret
3. Hearpayment.succeeded
4. Fulfilyour code

	Hosted page	Embedded checkout
Payer	Leaves for our page (approval_url)	Stays on yours
You build	A redirect	Card fields with @tuppence/js and your pk_… key
3-D Secure	The page runs it	sheet.confirm() runs it
Events	payment.succeeded, payment.failed	Same

Use: Take a payment · Webhooks · Testing

SaaS subscriptions

When: customers pay the same amount every month or year.

1. PlanPOST /v1/plans
2. Subscribelink with mode: "subscription", or POST /v1/subscriptions
3. Renewssubscription.renewed, invoice.paid
4. Self-servePOST /v1/portal_sessions

Objects	Calls	Events
Plan, customer, saved card, subscription, invoice	POST /v1/plans, /v1/payment_links (mode: "subscription"), /v1/subscriptions, …/preview + …/change, /v1/portal_sessions	subscription.started, .renewed, .payment_failed, .recovered, .canceled, invoice.paid

Failed renewals retry automatically after 1, 3, 7 and 14 days. Use: Subscriptions

No-code seller with payment links

When: you sell from a chat, an email, an Instagram bio or a QR code on a market stall.

1. Createdashboard, or POST /v1/payment_links
2. Shareurl or …/qr
3. Paidpayment.succeeded

Objects	Calls	Events
Payment link, payment	POST /v1/payment_links, GET /v1/payment_links/{id}/qr	payment.succeeded, payment_link.completed

Fixed or payer-chosen amounts, single-use or reusable. Use: Quickstart · Payment links

Marketplace or platform with Connect

When: businesses sell through your software, and you take a cut.

Scroll sideways to see all of it →

Objects	Calls	Events
Connected account, account link, application fee, transfer	POST /v1/accounts, /v1/account_links, any call with Tuppence-Account: acct_…, application_fee_amount, POST /v1/transfers	On a connect: true endpoint: account.updated, application_fee.created, transfer.created, and the account’s own events with account set

Each connected account is a whole Tuppence account in your platform’s region. You bear its losses. Use: Connect · Onboarding · Money for platforms

Agents paying you, request by request

When: your API is worth paying for per request, by people or by their agents.

Scroll sideways to see all of it →

Pieces	How
Your route	http402({ tuppence, price, currency, account }) in Node; Http402Middleware / PayWall in Python
A receipt	A JWT bound to the route and amount, used once, verified against /.well-known/jwks.json with no call to us
Agents with prepaid credit	Give the route a meter (credits: { meter }); mint a capped token with POST /v1/credits/{customer}/tokens; the agent sends Authorization: Tuppence-Credits <token>

Use: HTTP 402 · Agent frameworks

An AI agent that pays

When: an agent buys on someone’s behalf: SaaS, API credits, a booking, a flight.

Scroll sideways to see all of it →

Pieces	How
Tools	The MCP server at https://api.tuppence.ai/mcp, with a restricted key (rk_…) scoped to what the agent may do, each request signed as the agent
Its rules	A person gives the agent a default spending policy first: its limits and approval threshold. The agent’s key can’t change them
Ask first	request_approval, then get_approval
The card	create_agent_card: single-use, one purchase at one merchant, for the agent itself only, on its default policy; freeze_card stops it. Within the account’s card limits. What a restricted key can do
A web checkout	get_card_details, only with a card_details:read key where the owner allowed it (card details). A 3-D Secure code goes to the cardholder: the agent stops and asks
Who did it	Agent identity: the agent signs each request, and a mandate records what a person agreed it may buy
Events	approval.decided, card.created, card_transaction.created, card.details_retrieved

A bookings site with deposits

When: clients book appointments, and missed slots cost you money.

1. Policydeposit, card_required
2. Publishbooking page or embed
3. Client booksbooking.deposit_paid
4. No-show?POST /v1/bookings/{id}/charge_fee

Objects	Calls	Events
Service, staff, booking policy, booking page, booking	POST /v1/services, /v1/booking_policy, /v1/booking_page/publish, /v1/bookings/{id}/no_show, …/charge_fee	booking.created, booking.confirmed, booking.deposit_paid, booking.no_show, booking.fee_charged

On the booking page, a booking exists only once the deposit is paid. Use: Set up bookings · Deposits and no-shows · Embed

Direct Debit collections (UK)

When: a UK business takes regular pounds from bank accounts: memberships, invoices, instalments.

1. ApplyPOST /v1/direct_debit/application
2. Payer sets it uppay page, link or subscription
3. ~3 working daysprocessing → succeeded
4. AgainPOST /v1/payments/charge_saved

Objects	Calls	Events
Application, payment, saved bank account and mandate	POST /v1/direct_debit/application, GET /v1/direct_debit, POST /v1/payments (save_card), /v1/payments/charge_saved	direct_debit_application.approved, payment.processing, payment.succeeded, payment.failed, payment_method.mandate_cancelled

Not on booking deposits, the till or credit top-ups. Use: Direct Debit · Subscriptions by Direct Debit

Not sure which fits?

Ask the docs assistant. Describe what you’re building and it answers from these docs and, if you’re signed in, your account.