# Paid orders and human approval

A saved card, a human-set budget and an exact recipient policy for each agent application.

Stage: sandbox beta. Live purchasing requires explicit activation.

## Activation and verified quotes

Live purchasing is implemented behind activation controls. Your live application still needs approved entitlements, supported payment collection and a certified production route. Check /v1/capabilities and /v1/purchasing-policy. Sandbox keys continue to simulate every order.

The initial paid path imports a signed quote from paperboy's existing human upload and quote workflow. POST /v1/quotes/import with quote_token and an idempotency key. The quote must belong to the project creator and pass current file, production, pricing, expiry and route checks. Metadata-only sandbox quotes never authorize a live charge. Autonomous live uploads and product quoting remain separate work.

## Human setup

The project creator opens Agent purchasing in the developer console, chooses an application and sets its currency, per-order, daily and monthly limits. Periods use UTC. All keys for one application share its budget; use a separate application for each agent with independent authority.

Approve named people and their saved address-book destinations. Approval pins the person's contact details and destination. Editing those saved details requires reapproval. A valid API key provides access to the application; the human policy provides authority to buy.

The human explicitly consents to saved-card purchases and completes the payment provider's card setup. Card numbers stay with the provider. API keys cannot change budgets, cards, recipients or approval decisions. No prepaid balance or unsecured monthly credit is created.

## Place an order

POST /v1/orders with an imported quote_id. For an activated live application, a 202 response returns a stable order ID and purchase authorization. Read status, approval_reasons and approval_url. Your host should show that URL to the human when action is needed.

An order within the approved budget and recipient policy reserves its amount before the saved card is charged. Reserved and paid orders both count toward daily and monthly usage, including concurrent submissions. Production begins through the canonical paid-order flow after payment confirmation.

## Exceptions and bank authentication

A new recipient or an exceeded limit produces a pending approval. The human reviews the document, destination, amount, currency, quote identity and expiry in their console, then approves that exact purchase once or declines it. Approval can permit the listed budget exception; its amount still counts against future spending. It does not grant an agent a larger standing budget. Platform country, product, currency and exposure restrictions still apply.

After approval, submit the SAME order with POST /v1/orders/{id}/submit and a stable idempotency key. The live MCP tools are create_print_order and submit_print_order. Sandbox tools are not exposed to live keys.

A bank authentication requirement returns action_required. The human completes payment authentication in the console. The API response never contains a card number or payment client secret. An expired quote or changed purchasing policy requires a fresh quote/approval.

## Failures and recovery

Preserve the order ID and idempotency key. Repeating a create request recovers the same purchase. Read the current order after a replay. A transport failure retains its spending reservation while the payment outcome is uncertain; it never authorizes a second charge identity.

The human can cancel an unpaid purchase. A submitted payment releases its reservation only after confirmed provider cancellation. A successful charge stays counted, including after a refund, to prevent a refund/reorder loop from expanding purchasing authority. Existing paid-order cancellation and refund operations remain in the canonical customer/support flows.

Consume order.payment_confirmed events or poll the order for settlement. Payment requests and usage records have stable identities across webhook recovery. A monthly spending limit is a cap on purchases; it does not enable monthly invoicing.