Quickstart

Accept Your First Payment

This flow uses a server-created checkout session and the React payment embed. It is the fastest native Throttle integration path.

Configure your application

In the dashboard, copy your Application ID from App Settings → General and add your storefront origin (e.g. http://localhost:3000) to Allowed origins. The embed refuses to render until both are set.

Create an API key

On the API keys page, create a secret (sk_) key. The raw key is shown once — copy it and keep it on your backend only.

Create a checkout session

Your backend uses @usethrottle/checkout-sdk/server to mint a session with amount, currency, and an optional cart reference.

Render the React embed

Your storefront mounts PaymentEmbed from @usethrottle/checkout-react and handles the UI callbacks.

Subscribe to webhooks

Your backend treats signed webhook events as the durable source of truth for fulfillment and order state.

1. Configure your application

Before any SDK call works, you need two values from the dashboard: the Application ID and at least one allowed origin. Both ship empty on a fresh signup, which is why following the snippets below verbatim returns applicationId is required or renders Embed not authorized.

Sign in to the dashboard. A default application is created for your workspace on first login. If you have more than one, switch between them with the app switcher in the top bar.
Open App Settings → General and copy the Application ID (the field has a Copy button; it also appears on the API keys page). Stash it as THROTTLE_APPLICATION_ID.
Still in App Settings, add your storefront origin to Allowed origins (e.g. http://localhost:3000 in dev, https://shop.example.com in prod). Origins are scheme + host + optional port — no paths, no trailing slash, no wildcards. http://localhost and http://127.0.0.1 are accepted in every environment for local development.

Prefer the command line?

Install the CLI with npm install -g @usethrottle/cli and set your allowlist without opening the dashboard: throttle embed-config set --origins http://localhost:3000. It reads your secret key from $THROTTLE_API_KEY (or prompts for it); throttle embed-config show prints the current config. See the packages & SDKs page for everything the CLI and libraries expose.

Why this comes first

The embed enforces an origin allowlist server-side, and the cart/checkout endpoints reject requests without a valid applicationId. Both checks happen before any SDK error path — you'll see the failure as a 400 or an unauthorized embed instead of a hint that you need to set these.

Your sandbox payment provider is already connected

Every new application is automatically wired to a dedicated sandbox sub-account during signup, so PaymentEmbed renders (with the Card Simulator method) the first time you mint a checkout session in a non-production environment — no provider setup required. To accept real cards in production you still have to subscribe and add Throttle's production payment connection from Connectors; details on Workspace environments.

2. Create an API key

In the dashboard, open API keys (under Developers in the left nav), click Create key, and choose a secret (sk_) key with the scopes you need. The raw key is shown once — copy it immediately; only the prefix is stored afterward.

Keys are minted to one workspace environment, so the prefix carries it — e.g. sk_test_* or sk_live_*. Switch environments with the selector in the top bar before creating a key.
Use a pk_ publishable key for browser-side shipping/tax quotes only; everything else uses the secret key from your backend.

Keep secret keys server-side

Never put an sk_ key in browser code, mobile apps, or public repositories. The browser should only receive a checkout session id or hosted URL from your backend.

3. Create a checkout session

From your backend, mint a session with the amount in minor units. The checkout SDK keeps your secret key server-side and normalizes the API response into checkoutSessionId, hostedUrl, and embedUrl.

Backend route

// app/api/checkout/session/route.ts
import { createCheckoutClient } from '@usethrottle/checkout-sdk/server';

const checkout = createCheckoutClient({
  apiKey: process.env.THROTTLE_API_KEY!,
});

export async function POST() {
  const session = await checkout.createEmbedToken({
    amount: 2599,
    currency: 'USD',
    country: 'US',
    externalCartId: 'cart_123',
  });

  return Response.json({
    sessionId: session.checkoutSessionId,
    hostedUrl: session.hostedUrl,
    embedUrl: session.embedUrl,
  });
}

4. Render the React embed

Install the checkout SDK for your backend route and the React embed for your checkout page, then mount PaymentEmbed.

Install

npm install @usethrottle/checkout-sdk @usethrottle/checkout-react

Payment step

import { PaymentEmbed } from '@usethrottle/checkout-react';

export function PaymentStep({ sessionId }: { sessionId: string }) {
  return (
    <PaymentEmbed
      sessionId={sessionId}
      parentOrigin="https://shop.example.com"
      baseUrl="https://checkout.usethrottle.dev"
      primary="#1D56E8"
      onReady={() => console.log('ready')}
      onProcessing={() => console.log('processing')}
      onSucceeded={({ orderId, paymentId }) => {
        window.location.href = `/thank-you?order=${orderId}&payment=${paymentId}`;
      }}
      onFailed={({ code, message }) => {
        console.error(code, message);
      }}
    />
  );
}

5. Subscribe to webhooks

Browser callbacks are immediate UI signals. Webhooks are your durable source of truth for fulfillment, receipts, and order state.

Create endpoint

curl -X POST https://api.usethrottle.dev/api/v1/webhook-endpoints \
  -H "x-api-key: $THROTTLE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "url": "https://shop.example.com/api/throttle/webhook",
    "enabledEvents": ["order.created", "payment.captured", "payment.failed"]
  }'

Next step

Read the webhooks guide to verify signatures and handle retries idempotently.