Payment Methods

Pizza x402 supports two payment branches at confirm time:

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

The live Go deploy is merchant-configurable, so storefronts should read:

• paymentRails from merchant bootstrap
• availablePaymentMethods from the quote

Card checkout should only render when the merchant’s configured card rail is actually available.

Canonical references:

• AGENTS guide
• OpenAPI spec
• Wallet setup guide

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 the x402 payment using paymentRequirements (dev mock: paymentRequestId is still accepted as the proof).
4. Retry POST /v1/orders/confirm with either the legacy PAYMENT-SIGNATURE header or the JSON paymentSignature field.
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 and the public wallet setup guide (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 from paymentRequirements, then retry confirm with a proof payload
PAYMENT_INVALID	Signature/proof invalid or expired	Inspect details.reason and use the cause-specific branch below
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

For PAYMENT_INVALID, the current recovery rules are:

• invalid_signature: rebuild the proof payload instead of replaying the same invalid proof.
• expired: create a fresh quote before retrying.
• wrong_network: switch the wallet back to Base (eip155:8453).
• insufficient_funds: top up the wallet; details.requiredAtomic carries the exact minimum needed.

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.