Get started

Create a server-owned Checkout Session, choose hosted, embedded or custom presentation, then fulfill the order from a signed webhook.

1. Get a secret key

Sign in to the Paybytoken Merchant Portal, then open Developers → API keys.

Use a test key while developing:

PAYBYTOKEN_SECRET_KEY=sk_test_...

The secret key belongs on your server only. Never add it to frontend code, a mobile application or a public environment variable.

2. Install the server SDK

npm install @paybytoken/node

3. Create a Checkout Session

Resolve the order and its prices from your own database:

import Paybytoken from '@paybytoken/node'

const paybytoken = new Paybytoken(process.env.PAYBYTOKEN_SECRET_KEY!)

const session = await paybytoken.checkoutSessions.create({
  currency: 'usd',
  line_items: [
    {
      quantity: 1,
      unit_amount: '50.00',
      product_data: {
        name: 'Starter plan',
        description: 'One-month access',
      },
    },
  ],
  supported_tokens: [
    { chain: 'base', currency: 'USDC' },
    { chain: 'ethereum', currency: 'USDC' },
  ],
  success_url: 'https://shop.example.com/order/success',
  cancel_url: 'https://shop.example.com/cart',
  metadata: { order_id: 'order_1234' },
})

Do not accept a product price, token contract or destination address directly from browser input.

4. Choose the customer experience

Hosted checkout

Hosted is the default mode. Redirect the customer to the returned URL:

window.location.assign(session.url)

Paybytoken hosts the responsive checkout and returns the customer through your configured success or cancel URL.

Embedded checkout

Embedded checkout stays inside your website. Create the session with:

const session = await paybytoken.checkoutSessions.create({
  // The same server-owned order fields as above.
  currency: 'usd',
  line_items: order.items,
  supported_tokens: [{ chain: 'base', currency: 'USDC' }],
  ui_mode: 'embedded',
  allowed_origin: 'https://shop.example.com',
})

Your server returns only session.client_secret and session.url to the matching page. Continue with the embedded checkout quickstart to mount @paybytoken/checkout, or use the React integration.

Custom checkout

Custom checkout uses the same order but lets your application render currency, chain and transfer instructions:

const session = await paybytoken.checkoutSessions.create({
  // The same server-owned order fields as above.
  currency: 'usd',
  line_items: order.items,
  supported_tokens: [
    { chain: 'base', currency: 'USDC' },
    { chain: 'ethereum', currency: 'USDT' },
  ],
  ui_mode: 'custom',
})

Keep session.csrf_token on your server. Return only the session ID, supported tokens and expiry to your page, then confirm the customer's selected token through an authenticated server route. Follow Custom checkout for the complete boundary.

5. Fulfill from a verified event

Create a webhook endpoint and verify X-Webhook-Signature against the exact raw request body. Make fulfillment idempotent and mark the order paid only after payment_intent.succeeded.

Browser redirects and embedded complete events are customer-experience signals, not proof of payment. Follow Fulfill orders with webhooks before going live.

Next steps

• Define safe retries and replacement Sessions in Model orders and payment attempts.
• Follow the complete hosted checkout guide.
• Compare hosted, embedded and custom checkout.
• Build a fully merchant-owned UI with Custom checkout.
• Review the Checkout Sessions API.
• Complete the testing and security checklist.
• Move production configuration deliberately with Go live safely.
• Share a reusable checkout page with Payment Links.
• Provision persistent funds with Customer balances.
• Try the end-to-end experience in the Paybytoken Playground.