Two ways to pay
Every order is an individual transaction. There’s no wallet, no balance, no subscription.1. Stripe checkout (cards + Apple Pay)
POST /v1/orders in live mode comes back action_required with a payment step to complete — which shape depends on the checkout_ui_mode you sent (default "hosted"; the response echoes back whichever mode produced it).
By default, it returns a payment_url. Give it to the human — they approve the card payment on Stripe’s hosted page. After it settles, screening, printing, and mailing are automatic.
checkout_ui_mode: "embedded" (what paperplane’s own /embed widget uses, since Stripe’s hosted page refuses to render inside an iframe) and it returns a payment_client_secret to mount in place with Stripe.js’s initEmbeddedCheckout instead:
checkout_ui_mode: exactly one of payment_url / payment_client_secret ever appears, never both, and checkout_ui_mode says unambiguously which — a caller never has to guess the mode from which optional field happened to show up.
Either way, this matches the confirmation step assistant platforms require before a purchase — the human, not the agent, approves the charge. It’s the same pattern on the MCP surface (checkout_ui_mode itself is REST/embed-only: an MCP agent has no frame to mount anything in, so it always gets payment_url).
2. Prepaid credit code
Buy a block of credit once, then pay per-letter by code — no card at checkout every time. See Credits.Mail class pricing
Extra pages +0.50/page, tracking +$0.99 on first-class. The
/v1/quotes endpoint returns the exact all-in total before you commit — always price first.
Confirmation tokens and credit_code orders
- On the agent surface, every send requires a
confirmation_token(see Core concepts). - On the web/REST surface, payment is the gate — sandbox orders skip payment entirely.
A
credit_code order redeems from the prepaid balance instead of a new card charge. If the code is invalid or has insufficient balance, the order is refused (402) before anything prints.Refunds
Arefused or failed order releases the payment — for credit-code orders the balance is restored; for card payments the Stripe hold is released. A card refund shows within 5–10 business days.