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.

Create a secret API key

Use the dashboard API keys page. Keep the sk_ key on your backend only.

Mint a checkout session

Your backend calls the checkout session endpoint with amount, currency, and optional cart reference.

Mount PaymentEmbed

Your storefront renders the iframe through @usethrottle/checkout-react and handles UI callbacks.

Process webhooks

Your backend uses signed webhook events as the durable source of truth.

1. Create an API key

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.

2. Create a checkout session

From your backend, mint a session with the amount in minor units. The response includes checkoutSessionId, hosted_url, and embed_url.

Backend route

const res = await fetch(`${process.env.THROTTLE_API_URL}/api/v1/checkout-sessions/embed-token`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.THROTTLE_API_KEY!,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    amount: 2599,
    currency: 'USD',
    country: 'US',
    externalCartId: 'cart_123',
  }),
});

if (!res.ok) throw new Error('Could not create checkout session');
const { data } = await res.json();

return {
  sessionId: data.checkoutSessionId,
  hostedUrl: data.hosted_url,
  embedUrl: data.embed_url,
};

3. Render the React embed

Install @usethrottle/checkout-react and mount PaymentEmbed in your checkout page.

Install

npm install @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="#08786f"
      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);
      }}
    />
  );
}

4. 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",
    "enabled_events": ["order.created", "payment.captured", "payment.failed"]
  }'

Next step

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