Core Concepts

Bags has a small set of objects. Understanding how they relate makes everything else click.

Products

A product is a catalog item (name, price, network) you create once via POST /api/v1/products or the dashboard. Products back the primary checkout path: each purchase calls POST /api/v1/checkouts with a productId.

Checkouts (V1 hosted sessions)

A checkout session is a single buyer attempt created server-side. It returns:

• id — use as sessionId in webhooks and for polling
• url — hosted page at https://www.getbags.app/pay/...?session=...

Sessions expire 30 minutes after creation if unpaid. This is the recommended integration path for new merchants.

Payment links

A payment link is a reusable product or price point with a stable URL:

https://www.getbags.app/pay/{paymentLinkId}

Create links via POST /api/payment-links when you want one URL shared with many customers (email campaigns, embeds, dashboard-first workflows). Payment links are an optional path — not required if you use V1 checkouts.

One payment link can have many checkout sessions and transactions.

Checkout sessions (custom flow)

For custom checkout, a checkout session tracks one payment attempt from tax quote through on-chain confirmation. You create it with POST /api/checkout/session (buyer-facing, after a tax quote) — different from merchant POST /api/v1/checkouts.

Custom sessions also expire after 30 minutes.

Transactions

A transaction is a record of an on-chain payment. Statuses include broadcasted, confirming, completed, failed, and refunded. Each transaction ties to a payment link and optionally a checkout session.

Webhooks

Webhooks notify your server when something happens. Webhooks are the source of truth — don't fulfill orders on client-side confirmation alone.

Live today (checkout.* and refunds)

Legacy aliases payment.completed and payment.failed mirror the checkout events — process one event type, not both.

Coming soon

See Handle Webhooks Securely and Webhook Events.

How they fit together

Product (catalog)
  └── Checkout session (one per purchase via POST /api/v1/checkouts)
        └── Transaction (on-chain record)
              └── Webhook (server notification)

Optional branch:

Payment Link (reusable URL)
  └── Checkout Session(s) / Transactions
        └── Webhooks

Typical V1 flow:

1. You create a product for your $29.99 Pro Plan.
2. For each purchase, you call POST /api/v1/checkouts and redirect to data.url.
3. The customer pays with USDC. Bags records the transaction.
4. Bags sends checkout.completed to your server.
5. Your server fulfills the order.

Settlements

After payments accumulate, request a settlement to withdraw USDC. Settlements require manual approval (applied → approved → processing → completed). See Payouts.

What's next