Architecture

How products, checkouts, sessions, webhooks, and settlements fit together in Bags.

Bags is a Merchant of Record API. Your backend creates catalog objects and checkout sessions; customers pay on hosted pages or through your custom UI; Bags notifies you via webhooks and holds funds until you request a settlement.

Primary integration path (v0)

Your backend                    Bags                           Customer
    |                             |                                |
    |-- POST /api/v1/products --->|                                |
    |<-- productId --------------|                                |
    |                             |                                |
    |-- POST /api/v1/checkouts -->|                                |
    |<-- session id, url ---------|                                |
    |-- redirect customer ---------------------------------------->|
    |                             |<-- USDC on-chain -------------|
    |<-- webhook checkout.completed|                               |

Object	Scope	Created by
Product	Reusable catalog item (name, price, network)	`POST /api/v1/products`
Checkout session	One buyer attempt (30 min expiry)	`POST /api/v1/checkouts`
Payment link	Optional reusable `/pay/{id}` URL	`POST /api/payment-links`
Transaction	On-chain payment record	Bags after customer pays
Webhook	Server notification	Bags when lifecycle events fire
Settlement	Bulk USDC withdrawal	Merchant request → manual approval

Checkout surfaces

Surface	Who calls	Use when
`POST /api/v1/checkouts`	Merchant (API key)	Default: one API call → hosted URL per purchase
`POST /api/payment-links`	Merchant	Shareable product URL for many customers
`POST /api/checkout/session`	Buyer-facing app	Custom/embedded checkout after tax quote

Do not mix merchant catalog calls with buyer session calls. See Choose Your Integration.

Tax and compliance

Tax quotes route to regional providers based on the customer's country (EU VAT, UK VAT, India GST, US sales tax where nexus is active, zero-tax elsewhere). Bags is the legal seller and remits tax as MoR.

Settlements

Withdrawals follow manual approval: applied → approved → processing → completed. See Payouts and Settlements & Payouts.

Coming soon

Subscriptions, card payments, TypeScript SDK, customer portal, and discounts are on the roadmap. Docs pages mark each as coming soon with waitlist links.