> ## Documentation Index > Fetch the complete documentation index at: https://paperplane-justin-winter-s-projects.vercel.app/docs/llms.txt > Use this file to discover all available pages before exploring further. # Payments > How orders get paid — paperplane payment links and prepaid credit codes, and what the confirmation flow requires. ## Two ways to pay Every order is an individual transaction. There's no wallet, no balance, no subscription. Two ways an order is paid: a paperplane payment link returns action_required and waits for a person to approve, or a prepaid credit code pays from the balance with no person in the loop. Screening, printing and mailing then follow automatically. Two ways an order is paid: a paperplane payment link returns action_required and waits for a person to approve, or a prepaid credit code pays from the balance with no person in the loop. Screening, printing and mailing then follow automatically. ### 1. Payment link (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 the paperplane payment page. After it settles, screening, printing, and mailing are automatic. ```json theme={null} { "status": "action_required", "checkout_ui_mode": "hosted", "payment_url": "https://checkout.stripe.com/...", "reason": "The sender must authorize payment before we print.", "next": ["Open payment_url to pay..."] } ``` Pass `checkout_ui_mode: "embedded"` (what paperplane's own `/embed` widget uses, since the hosted payment page refuses to render inside an iframe) and it returns a `payment_client_secret` to mount in place with Stripe.js's `initEmbeddedCheckout` instead: ```json theme={null} { "status": "action_required", "checkout_ui_mode": "embedded", "payment_client_secret": "cs_test_..._secret_...", "reason": "The sender must authorize payment before we print.", "next": ["Mount payment_client_secret with Stripe.js initEmbeddedCheckout()..."] } ``` The response is a discriminated union keyed on `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](/docs/guides/credits). ## Mail class pricing | Class | Base (1 pg) | Use for | | - | - | - | | `first_class` | \$0.99 | Routine mail | | `certified` | \$12.99 | Proof of mailing + tracking | | `certified_err` | \$14.99 | A signed USPS delivery record (e-Return Receipt) | | `priority` | \$24.99 | Flat-rate, urgent | Extra pages +$0.25, color +$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](/docs/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 A `refused` or `failed` order releases the payment — for credit-code orders the balance is restored; for card payments the card hold is released. A card refund shows within 5–10 business days. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.