Bags DocsChoose Your Integration
Pick the right Bags integration path — hosted checkout, payment links, custom sessions, or x402 agents.
Bags offers several ways to accept USDC. Pick the path that matches how much control you need over checkout UI and flow.
Checkout endpoints (don't mix these up)
Bags exposes three different "checkout" surfaces. They look similar in name but serve different actors:
| Endpoint | Who calls it | What it creates |
|---|---|---|
POST /api/v1/checkouts | Merchant (API key) | A hosted checkout session for one buyer attempt — returns id, url, and webhook sessionId. Primary server-side path. |
POST /api/payment-links | Merchant (API key or dashboard) | A reusable payment link (/pay/{linkId}) you can share with many customers. Not a per-buyer session. |
POST /api/checkout/session | Buyer-facing app (often unauthenticated) | Locks a single payment attempt for custom/embedded checkout after a tax quote. Requires linkId, quoteToken, walletAddress, network, and walletType from your UI — not an API-key catalog call. |
Use V1 Checkouts or Payment Links when integrating from your backend. Use Checkout Sessions only when you control the payer's wallet UI and already have a linkId + signed tax quote.
Integration paths
| Path | Best for | Frontend work | API surface |
|---|---|---|---|
| V1 Checkouts | Fastest launch, Polar-like flow, agents | None — redirect to hosted page | POST /api/v1/checkouts |
| Payment Links | Reusable products, shareable URLs, dashboard-first | None — share a link | POST /api/payment-links |
| Custom Checkout | Embedded wallet UX, your own checkout page | Full — you build the UI | Checkout Sessions API |
| x402 Agentic | Pay-per-call APIs, AI agents | Minimal — HTTP 402 paywall | /api/agent/{id} |
Decision guide
Start with V1 Checkouts (POST /api/v1/checkouts) if you want one API call → one hosted URL with session binding → webhooks when paid. This is the Polar-like primary path.
Use Payment Links when you sell fixed products or plans from the dashboard and want stable, shareable URLs (/pay/{id}) you can email or embed. Set syncProduct: true on one-liner agent requests to auto-create catalog entries.
Use Custom Checkout when customers never leave your site and you control wallet connection, tax quote display, and transaction submission.
Use x402 when monetizing API endpoints per request — agents and automation pay before accessing your upstream resource.
What's live in v0
| Feature | Status |
|---|---|
| Payment links & hosted checkout | Live |
V1 Checkouts (POST /api/v1/checkouts) | Live |
V1 Checkout alias (POST /api/v1/checkout, deprecated) | Live |
| Custom checkout sessions | Live |
| Tax quotes (regional providers) | Live |
| Webhooks & events | Live |
| KYB & USDC payouts | Live |
| x402 agentic paywalls | Live |
| Agents & MCP (preview + tax quote) | Live |
REST API (fetch / cURL / any HTTP client) | Live |
Coming soon
| Feature | Docs |
|---|---|
| TypeScript SDK | SDKs |
| Card payments | Payment Methods |
| Subscriptions | Subscriptions |
| Discounts / promo codes | Discounts |
| Customer portal | Customer Portal |
| Ethereum mainnet | Environments |
| Fiat bank payouts (Q2) | Payouts |
| Self-serve refunds (dashboard) | Refunds |
| Usage-based / metered billing | Usage-Based Billing |
Each coming-soon page includes a waitlist link. The dashboard marks Subscriptions and Discounts with a SOON badge today.
Migrating from POST /api/v1/checkout
The deprecated one-liner (POST /api/v1/checkout) creates a reusable payment
link and returns the link id. The primary path is session-based:
- Create a catalog product once (
POST /api/v1/productsor dashboard). - For each purchase, call
POST /api/v1/checkoutswithproductId, optionalexternalCustomerIdandmetadata. - Redirect to
data.url(includes?session=binding). - Poll
GET /api/v1/checkouts/{id}or listen forcheckout.completed.
Webhook checkout.completed now includes productId, externalCustomerId,
customerId, and metadata when supplied at session creation. The deprecated
alias still works but will not receive new fields on the link object itself —
migrate to checkouts for reconciliation.
Recommended learning path
Quickstart
Create your first test checkout and receive a webhook in under 10 minutes.
Sample Integration
Copy-paste a full Node.js example with checkout + webhook verification.
Handle Webhooks
Make webhooks your source of truth for payment status.
Go Live
Complete KYB, switch to live keys, and accept real USDC.