Payment Methods

Pizza x402 supports two payment branches at confirm time:

• Card payments (EUR, Stripe-backed)
• Crypto payments (USDC on Base via x402)

Canonical references:

• AGENTS.md#get_wallet_setup
• openapi.yaml

Payment branch behavior

Card branch

1. Create a quote with POST /v1/orders/quote.
2. Confirm with POST /v1/orders/confirm and paymentMethod: "card".
3. Confirm response is 200 with paymentIntentId and clientSecret.
4. Complete payment on frontend using Stripe Elements/Checkout.
5. Order is created by webhook after successful payment.

Crypto branch

1. Create a quote with POST /v1/orders/quote.
2. First POST /v1/orders/confirm with paymentMethod: "crypto" returns 402 PAYMENT_REQUIRED.
3. Execute x402 payment (dev mock: PAYMENT-SIGNATURE = paymentRequestId).
4. Retry POST /v1/orders/confirm with PAYMENT-SIGNATURE.
5. Response 200 returns orderId and paid status.

Wallet readiness checklist

Before choosing crypto payment, confirm all of the following:

• Customer has a wallet that supports Base.
• Wallet holds enough USDC on Base (not Ethereum mainnet).
• Customer can sign/submit the payment proof before quote expiry.
• Network is eip155:8453 and asset is Base USDC.

If readiness is missing, use wallet setup guidance before retrying payment.

Wallet setup guidance

Use the canonical API endpoint:

curl -sS http://localhost:3000/v1/wallet-setup

The response includes:

• Step-by-step setup instructions.
• Recommended wallet options (Coinbase Wallet for beginners).
• Base network details (chainId, USDC asset address, explorer, RPC).
• Canonical resources (base docs, wallet download, bridge links).

For docs consistency, prefer the endpoint response over ad-hoc setup text:

• GET /v1/wallet-setup (runtime contract)
• AGENTS.md#get_wallet_setup (agent guidance)

Common payment failures and operator actions

Error code	When it appears	Action
PAYMENT_REQUIRED	Crypto first confirm call or payment not yet seen	Complete payment then retry confirm with PAYMENT-SIGNATURE
PAYMENT_INVALID	Signature/proof invalid or expired	Re-run payment step or regenerate quote if expired
QUOTE_NOT_FOUND	Quote expired or unknown	Recreate quote and restart confirm flow
ASSERTION_FAILED_METHOD	Confirm method differs from expected	Reconfirm method with user and retry
ASSERTION_FAILED_CURRENCY	Currency expectation mismatch	Validate card (EUR) vs crypto (USDC) path
ASSERTION_FAILED_EXPIRY	Expected expiry differs or quote stale	Refresh quote and retry with updated assertions

Minimal confirm-time safety pattern

Use assertions on confirm calls to lock expected quote state:

• expectedQuoteHash
• expectedTotalCents / maxTotalCents
• expectedCurrency
• expectedPaymentMethod
• expectedExpiresAt
• expectedMerchantId / expectedMerchantAddress

This reduces silent divergence in agentic and scripted flows.