Stripe + Crypto Payments

Offer card and on-chain checkout with one PayDirect integration. Both rails share the same payments lifecycle, outbound webhooks, and /api/v1/verify endpoint.

Try it in the Playground API reference

Choose a payment rail

Set paymentMethod on POST /api/v1/payments

Rail	paymentMethod	tokenSymbol	Payer experience
Crypto (default)	`crypto`	USDC, ETH, ADAO	Send to `receivingAddress` or open `paymentUrl`
Stripe Checkout	`stripe`	USD only	Live: `checkoutUrl` · Sandbox: auto-completes

Merchant integration (4 steps)

1. Register your outbound webhook

POST /api/v1/webhooks
{ "url": "https://your-app.com/hooks", "events": ["payment.forwarded"] }

2. Create payment at checkout

// Stripe
POST /api/v1/payments
{ "paymentMethod": "stripe", "tokenSymbol": "USD", "amount": "25.00",
  "metadata": { "orderId": "ORD_1" } }

// Crypto
POST /api/v1/payments
{ "paymentMethod": "crypto", "tokenSymbol": "USDC", "amount": "25.00",
  "merchantWallet": "0x...", "metadata": { "orderId": "ORD_1" } }

3. Redirect the payer

Stripe live → checkoutUrl
Either rail → paymentUrl (hosted /pay/:id page)

4. Fulfill when settled

Listen for payment.forwarded on your webhook, or poll POST /api/v1/verify with the paymentId.

Sandbox vs live

pd_test_

Sandbox Stripe payments auto-complete (pending → forwarded). No real card charge. Run pnpm test:stripe locally.

pd_live_

Live returns a real checkoutUrl. Fulfillment happens when Stripe hits POST /api/webhooks/stripe (configured by PayDirect ops, not merchants).

Idempotency

Use different keys per rail

Idempotency-Key: order-123-stripe   // card checkout
Idempotency-Key: order-123-crypto   // USDC checkout

Who configures Stripe?

Merchants only use the PayDirect API — no Stripe Dashboard access required.

PayDirect platform configures Stripe keys and the inbound webhook at /api/webhooks/stripe (API version 2026-05-27.dahlia, Snapshot payload).

See Stripe inbound webhooks for ops details.