Embed Throttle Without Owning Payment UI

PaymentEmbed

Use PaymentEmbed when your storefront already owns cart, address, shipping, and order summary UI. Throttle renders the payment form and posts lifecycle events to the parent page. If you show a promotion-code field in that order summary, preview it on your server and apply it to the Throttle cart before creating the session.

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

Both components build their own iframe URL and load the /c page by default. Pass route="s" to load the unified /s page instead — for example to match the route you give buildCheckoutEmbedUrl on your server. The component does not see a URL you built yourself. Card-vault (add-a-card) sessions are only served by /c.

CheckoutEmbed

Use CheckoutEmbed when you want a fuller hosted checkout flow inside your page. It supports the same terminal events plus checkout step changes.

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

Raw iframe

If you are not using React, render the hosted checkout iframe directly and validate the postMessage envelope before trusting events.

<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>

Origin allowlist

Embedded checkout refuses to render unless the parent origin is allowlisted. Configure production and staging origins before mounting the iframe.

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"

Preview origins

Preview deployments get a new hostname per branch, so they cannot be listed one by one. In a non-production environment, an entry may use one wildcard as its leftmost label:

• https://*.preview.example.com matches https://pr-42.preview.example.com and any deeper subdomain. It does not match https://preview.example.com itself; list that separately if you need it.
• The wildcard must sit under a domain you own. One over a shared or public suffix ( https://*.vercel.app, https://*.pages.dev, https://*.co.uk) is refused with 400 invalid_origin, because anyone can obtain a hostname there and could then host your checkout. Point a subdomain of your own at the preview host instead.
• Production takes exact origins only. A wildcard sent to the production environment is refused, and creating an application never accepts one, since that seeds every environment at once. For a domain cutover, list the old and the new origin side by side and remove the old one afterwards.

A wildcard entry applies to embedded checkout, cart sessions, storefront sign-in and the script manifest. One exception: the sandbox that runs extension scripts only ever lets exact origins frame it, so sandboxed scripts do not run on a preview origin matched by a wildcard. A wildcard is also never used to build a link. If your allowlist holds only wildcards, set storefrontBaseUrl so buyer emails and relative image paths have a real host to point at.

Choosing the right surface

The hosted checkout app exposes two route shapes. Both honour the same origin allowlist and emit the same postMessage events; they differ in who owns the buyer-data form (Throttle vs. the payment provider) and which payment methods can co-exist.

Session lifecycle

Every embedded checkout follows the same four-step rhythm. Sessions are server-side state; embed tokens are short-lived JWTs that the iframe re-mints on demand.

// 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.

Sequence: postMessage handshake

Visualises the full conversation between your storefront page, the embedded iframe, and the Throttle API. Use it to sanity-check listener ordering — your parent page must register the message listener before the iframe emits throttle.ready.

sequenceDiagram
  participant S as Storefront
  participant F as Throttle Iframe
  participant API as Throttle API
  S->>F: src=/s/{sessionId}?embed=1&parentOrigin=...
  F->>API: GET /payment-methods
  API-->>F: eligible methods
  F->>S: postMessage throttle.ready
  Note over F,S: buyer fills cart / address / billing
  F->>S: throttle.step.changed: address
  F->>S: throttle.step.changed: billing
  F->>S: throttle.step.changed: payment
  S->>F: buyer clicks Pay
  F->>S: throttle.processing
  F->>API: POST /checkout-sessions/{id}/complete
  API-->>F: { orderId, paymentId }
  F->>S: throttle.completed { orderId, paymentId }
  S->>S: redirect to thank-you page

Query parameter reference

Both /c and /s accept the same iframe-mode parameters. The React SDK sets these for you; documented here for raw integrations.

postMessage event reference

Every iframe-to-parent message wraps an event in a versioned envelope. Verify the envelope before trusting the payload — the same window may host multiple third-party iframes.

// 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"
}

Complete-session payloads

The buyer-side POST /api/v1/checkout-sessions/:id/complete accepts three payload shapes, discriminated by paymentMethod. All three return the same shape: { orderId, paymentId, subscriptionId, subscriptionIds, redirectUrl? }. The two subscription keys appear only on a checkout with subscriptions: subscriptionIds lists every subscription it created, in line order (empty if creation failed), and subscriptionId is set only when there is exactly one, null otherwise. A one-off checkout carries neither. Key order can differ between a first response and an idempotent replay, so compare fields, not bytes.

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

{
  "paymentMethod": "embedded",
  "processorTransactionId": "<transaction id the payment embed emits when the buyer pays>",
  "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": "embedded",
  "processorTransactionId": "<transaction id the payment embed emits when the buyer pays>"
}

// Used by the legacy /c proxy mode where the embed 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.

Completion errors

/complete checks the money before it creates an order. The embed authorises the card (intent: authorize, recurring checkouts included) and Throttle captures only after it has confirmed that the transaction belongs to this checkout and that the authorised amount is the amount the cart charges now. Except for payment_processing, a refusal leaves the session open and creates no paid order and no subscription. The hosted page and the iframe handle each one for the buyer; a server-side caller should follow the last column.

// 409 — the total changed after the card was authorised (nothing was captured)
{
  "error": {
    "code": "checkout_total_changed",
    "message": "The total changed after your card was authorised. Review the new total and pay again.",
    "details": {
      "authorizedAmount": 1100,
      "currentAmount": 1000,
      "currency": "USD",
      "cartId": "…",
      "voided": true
    }
  }
}

// 409 — the embed had already captured another amount: it is refunded
"details": { "authorizedAmount": 1100, "capturedAmount": 1100, "currentAmount": 1000,
             "currency": "USD", "cartId": "…", "voided": false, "refunded": true }

// 409 — an order from an earlier attempt already has a payment at another total
"details": { "orderTotal": 3248, "currentAmount": 3500, "currency": "USD",
             "cartId": "…", "voided": true }

// 409 — retry /complete with the same transaction
{ "error": { "code": "payment_unverified",
  "message": "We could not confirm your payment yet. Please try again.",
  "details": { "transactionId": "…", "retryable": true } } }

// 409 — never retry this transaction; pay again
{ "error": { "code": "transaction_not_for_session",
  "message": "This payment does not belong to this checkout. Please pay again.",
  "details": { "transactionId": "…", "retryable": false } } }

// 409 — pay again
{ "error": { "code": "transaction_already_used",
  "message": "This payment has already been used for this checkout. Please pay again.",
  "details": { "transactionId": "…" } } }

• Captures never exceed the authorisation. The payment provider refuses a capture above the authorised amount (400 bad_request, "Cannot capture more than the authorized amount"), and Throttle never completes a checkout at an amount other than the cart's. The payment's capturedAmount is the amount the provider reports as captured.
• $0 checkouts. A one-off checkout whose total is $0 (for example a 100% code) completes without a charge: the order is paid at $0 with a captured $0 payment. The card form is still shown. On the server-authorize and saved-card rails no processor call is made at all, so no card is saved and the invoice shows no card. A recurring $0 checkout (a trial) still authorises $0 to verify and save the card.
• Payment-only and proxy completions follow the same rules: the transaction must belong to the Gr4vy checkout session the embed token minted for this session (otherwise transaction_not_for_session); an amount other than the session's is voided or refunded and answered checkout_total_changed; a transaction another payment already holds answers transaction_already_used unless it is the same request replayed for this session. A $0 recurring proxy session (a trial) completes at $0 with no charge.
• Native tax follows the cart to the payment form. With native tax (taxMode: "calculated"), each embed-token mint ( GET /api/v1/checkout-sessions/:id/embed-token) first checks the cart's tax against its address, lines, shipping and customer. If any of them changed since the tax was last calculated, the tax is recalculated and the token is minted for the new total; if nothing changed, nothing is recalculated. When the cart has no address yet, the address the session was created with (the one completion puts on the order) is used. The completion charges what the card form authorised, so after you change a cart that a payment form is already showing, re-render the form (or mint a new token) to show the buyer the new total. A recalculation that fails answers 409 tax_calculation_failed and mints no token. A quote's checkout keeps its accepted total; provider (Avalara) tax and provider carts are unchanged.
• Add-card sessions (the add-only card embed) never capture and create no order or payment. The $1 verification is voided once the card is saved, and /complete answers { status: "card_saved", orderId: null, paymentId: null, transactionId, paymentMethodId, paymentMethod }. If the card cannot be saved, the $1 is still released and the answer is 422 card_not_vaulted; the session stays open, so the buyer can try again.

Payment-method filtering

allowedMethods on a checkout session filters Throttle's method selection: the GET /api/v1/checkout-sessions/{id}/payment-methods catalog and, in the full hosted checkout, which payment tiles the buyer sees.

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 ..."
//     }
//   }
// }