Core Concepts

Bag has four main objects. Understanding how they relate makes everything else click.

Payment links

A payment link is a reusable product or price point. It has a name, an amount, and a network. When you create one, Bag gives you a hosted checkout URL:

https://justusebag.xyz/pay/{paymentLinkId}

Payment links are the starting point for every payment. You can create them via the API, the SDK, or the dashboard.

One payment link can have many transactions — think of it like a product page that multiple customers can buy from.

Checkout sessions

A checkout session tracks a single payment attempt. It's created when a customer starts the checkout flow and expires after 30 minutes.

Sessions go through these statuses:

payment_session_created → txn_broadcast → txn_confirming → txn_finalized → complete

If you use Bag's hosted checkout page (the payment link URL), sessions are managed automatically. If you build a custom checkout, you create and manage sessions yourself via the API.

Transactions

A transaction is a record of an on-chain payment. It's created when a customer submits a transaction hash and moves through these statuses:

Each transaction belongs to a payment link and (optionally) a checkout session.

Webhooks

Webhooks are how Bag tells your server that something happened. When a payment completes or fails, Bag sends a POST request to your registered URL.

Webhooks are signed with HMAC-SHA256 so you can verify they came from Bag. See Handle Webhooks Securely for implementation details.

Webhooks are the source of truth for payment status. Don't rely on client-side confirmation — always wait for the webhook before fulfilling an order.

How they fit together

Payment Link (reusable)
  └── Checkout Session (one per payment attempt)
        └── Transaction (on-chain record)
              └── Webhook (server notification)

A typical flow:

1. You create a payment link for your $29.99 Pro Plan.
2. A customer opens the checkout URL. Bag creates a checkout session.
3. The customer pays with USDC. Bag records the transaction.
4. Once confirmed on-chain, Bag sends a payment.completed webhook to your server.
5. Your server fulfills the order.

Settlements

After payments accumulate, you can request a settlement to withdraw funds to your wallet. Settlements are separate from individual transactions — they represent bulk payouts from your Bag balance.

See Request a Payout for details.

What's next