Hosted checkout

If you don’t want to build the payment screen, use the hosted checkout: your application creates a session via API and redirects the buyer to a Bob-hosted page. When they pay, you receive the webhook and the buyer returns to your successUrl.

Today the hosted checkout works with PIX and crypto. Credit card is coming soon — the references to credit_card below apply once card payments launch.

When to use each mode

	Hosted checkout	Embeddable SDK	Direct API
Payment screen	Ready, hosted by Bob	Built into your site by the Bob SDK	You build it
Card	Bob handles tokenization and 3DS	The SDK handles tokenization and 3DS	You handle tokenization and 3DS
Integration effort	One call + redirect	`sessionToken` + DOM component/element	Higher
Confirmation	Per-session webhook + `successUrl`	Callback + webhook	Project webhook

The full flow

Create the session

POST /api/v1/checkout-sessions/ with the amount and (optionally) accepted methods, items, buyer data, and webhookUrl:

curl -X POST https://api.payments.bob.company/api/v1/checkout-sessions/ \
  -H "Authorization: Bearer $BOB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 25000,
    "items": [{ "name": "Guitar Course", "quantity": 1, "unitAmountCents": 25000 }],
    "paymentMethods": ["pix"],
    "successUrl": "https://store.example.com/thank-you",
    "webhookUrl": "https://store.example.com/webhooks/bob",
    "webhookVersion": "v2"
  }'

The response returns checkoutUrl, checkoutToken and — if you sent webhookUrl — the webhookSecret used to verify the signatures. The secret appears only in this response; store it.

Redirect the buyer

Send the buyer to the checkoutUrl. They complete the payment using the available method (PIX or crypto).

Receive the confirmation

On payment, your webhookUrl receives transaction.paid (signed — always verify it) and the buyer is taken to the successUrl.

(Optional) Poll for status

Without a webhook, query GET /api/v1/checkout-sessions/{token}/status — public, with per-IP rate limiting. Use it as a complement, not a replacement for the webhook.

Good to know

items is display metadata — the catalog is yours; Bob only renders the order summary. The amount charged is always the session’s amountCents.
expiresAt belongs to the link, not the PIX — the session lasts 24h by default; the PIX generated within it follows the expiration configured on the project.
paymentMethods controls the displayed options — use ["pix"] (the default) or ["crypto"] for crypto payments; combine them in a single session to offer both. Support for ["credit_card"] arrives once card payments launch.
Method not available — session creation reports when a requested method is not enabled on the project.
Crypto — pass crypto in paymentMethods. The buyer is taken to the hosted crypto page via the same checkoutUrl; confirmation arrives via transaction.paid just like the other methods.
Credit card (coming soon) — once it launches, you’ll pass credit_card in paymentMethods. See Credit card.
Want to keep the buyer on your site? Use the Checkout SDK. It embeds Bob’s checkout without exposing raw card data to your application.
Sandbox works the same way — create the session with sk_test_ and the flow runs end to end in the test environment. See Sandbox.
With the SDK: bob.checkoutSessions.create(...) already sends webhookVersion: "v2" by default. See Node.js SDK.

Getting Started

Core concepts

Integration methods

Webhooks

Using Bob

API fundamentals

When to use each mode

The full flow

Good to know

Next steps

Create a checkout session

Checkout SDK

​When to use each mode

​The full flow

​Good to know

​Next steps

Create a checkout session

Checkout SDK

When to use each mode

The full flow

Good to know

Next steps