Embed Throttle Without Owning Payment UI

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);
      }}
    />
  );
}

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

<CheckoutEmbed
  sessionId={sessionId}
  parentOrigin="https://shop.example.com"
  baseUrl="https://checkout.usethrottle.dev"
  logo="https://shop.example.com/logo.png"
  onStepChanged={({ step }) => analytics.track('checkout_step', { step })}
  onSucceeded={({ orderId }) => router.push(`/orders/${orderId}`)}
/>;

<iframe
  src="https://checkout.usethrottle.dev/c/SESSION_ID?embed=1&mode=payment-only&parentOrigin=https%3A%2F%2Fshop.example.com"
  style="width:100%;height:520px;border:0"
  allow="payment *"
></iframe>

<script>
  window.addEventListener('message', (event) => {
    if (event.origin !== 'https://checkout.usethrottle.dev') return;
    if (event.data?.source !== 'throttle' || event.data?.version !== 1) return;

    if (event.data.type === 'throttle.completed') {
      window.location.href = '/thank-you?order=' + event.data.orderId;
    }
  });
</script>

npm install -g @usethrottle/cli

throttle embed set \
  --origins https://shop.example.com,https://staging.shop.example.com \
  --primary "#1D56E8" \
  --logo https://shop.example.com/logo.png \
  --merchant-name "Example Shop"

// 1. Server-side: merchant mints an embed-mode session.
import { createCheckoutClient } from '@usethrottle/checkout-sdk/server';

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

const session = await checkout.createEmbedToken({
  amount: 12000,
  currency: 'USD',
  country: 'US',
  externalCartId: 'cart_abc',
  // NOTE: the payment-only embed cannot restrict methods — the payment widget
  // renders whatever your payment connection exposes. Passing allowedMethods here
  // is rejected (400 allowed_methods_unsupported). To limit methods, configure
  // the connection, or use the full hosted checkout (createSession).
});
// session.checkoutSessionId, session.embedToken (~30min TTL),
// session.hostedUrl (full /c URL), session.embedUrl (/c?embed=1).

// 2. Client-side: parent renders the iframe (or React embed).
//    Throttle's iframe re-mints the JWT on every render via
//    GET /api/v1/checkout-sessions/:id/embed-token, so the buyer can land
//    minutes after creation without breaking the embed.

// 3. Buyer submits → iframe POSTs /api/v1/checkout-sessions/:id/complete
//    with one of the three payload shapes (see the Complete reference below).

// 4. Iframe posts `throttle.completed` with { orderId, paymentId } to the parent.
//    Parent navigates to its own thank-you page.

// Every event Throttle posts to the parent uses this envelope.
// Verify event.origin === <checkout host>, source === 'throttle', version === 1.
{
  "source": "throttle",
  "version": 1,
  "type": "throttle.completed",
  "orderId": "ord_xxx",
  "paymentId": "pay_xxx"
}

POST /api/v1/checkout-sessions/sess_xxx/complete

{
  "paymentMethod": "card",
  "paymentToken": "<provider paymentMethodId from the embed>",
  "email": "[email protected]",
  "shippingAddress": {
    "firstName": "Ada",
    "lastName": "Lovelace",
    "addressLine1": "1 Infinite Loop",
    "city": "Cupertino",
    "stateProvince": "CA",
    "postalCode": "95014",
    "countryCode": "US",
    "phone": "+14155551234"
  }
}

// Response: { orderId, paymentId, redirectUrl? }

POST /api/v1/checkout-sessions/sess_xxx/complete

{
  "paymentMethod": "gr4vy",
  "processorTransactionId": "<txn id emitted by the provider embed onTransactionCreated>"
}

// Used by the legacy /c proxy mode where the provider collects the email + address
// inside its own iframe. Response: { orderId, paymentId }.

POST /api/v1/checkout-sessions/sess_xxx/complete

{
  "paymentMethod": "net30",
  "email": "[email protected]",
  "shippingAddress": { /* same shape as card */ },
  "net30Acceptance": {
    "termsHash": "<sha256 of the terms snapshot the buyer accepted>",
    "acceptedAt": "2026-05-02T18:30:00Z",
    "companyName": "Acme Corp",
    "billingEmail": "[email protected]"
  }
}

// Response: { orderId, paymentId, redirectUrl? }
// The order ships in 'deferred' payment status; an invoice is issued and the
// AR cron handles dunning + aging until it is marked paid.

GET /api/v1/checkout-sessions/sess_xxx/payment-methods

{
  "data": {
    "methods": [
      {
        "method": "card",
        "displayName": "Card",
        "connectorId": "gr4vy",
        "acceptedCurrencies": ["USD"]
      },
      {
        "method": "net30",
        "displayName": "Net 30 Invoice",
        "connectorId": "net30",
        "acceptedCurrencies": ["USD"]
      }
    ]
  }
}

// The server runs each connector's listEligible() against the merchant + amount
// + currency, then intersects with the session's `allowedMethods`. Empty
// methods array → iframe renders the "no payment methods available" tile.
// The client never re-filters; trust the response.
//
// When methods is empty because a provider IS connected but can't render yet
// (e.g. not configured for the current environment), the response also carries
// an actionable reason — show reason.message instead of a generic empty state:
//
// {
//   "data": {
//     "methods": [],
//     "unavailableReason": {
//       "code": "payment_provider_not_renderable",
//       "message": "Card payments aren't available for this checkout yet ..."
//     }
//   }
// }