Mount Card Fields On Your Own Page

How it works

Four steps, and the only server-to-server call is the mint. Everything after that is either a mount inside the buyer's browser or the same public completion route the Embed and hosted checkout already use.

Mint the session

Call this from your backend, with your sk_* secret key. Never call it from the browser — there is no publishable-key variant.

// Your backend — mint a Secure Fields card session for an existing checkout session
const res = await fetch(
  `https://api.usethrottle.dev/api/v1/checkout-sessions/${checkoutSessionId}/card-session`,
  {
    method: 'POST',
    headers: { 'X-API-Key': process.env.THROTTLE_SECRET_KEY! },
  },
);
const { data: session } = await res.json();
// session: { sessionId, providerId, environment }
// Hand this object to <SecureCardProvider session={session} /> unchanged.

{
  "data": {
    "sessionId": "a33b3ff6-1f2a-4f81-99d5-299d22083a9a",
    "providerId": "your-provider-instance",
    "environment": "sandbox"
  },
  "meta": { "requestId": "..." }
}

Content Security Policy

The card inputs are iframes served from Throttle's payment provider, not from your own domain. If your checkout sends a Content-Security-Policy header, the fields render as blank boxes until you allow that origin — usually with no error in the page, only a CSP violation in the browser console.

Content-Security-Policy:
  frame-src   https://*.gr4vy.app;
  connect-src https://*.gr4vy.app https://api.usethrottle.dev;

frame-src lets the iframes mount; connect-src covers the calls they make. If you also send frame-ancestors elsewhere, it does not apply here — that directive governs who may frame you, not whom you may frame.

React example

@usethrottle/checkout-react ships a headless provider, a hook, and four unstyled field primitives. Style everything yourself — the whole point of choosing Secure Fields is that you own the pixels around the fields.

import {
  SecureCardProvider,
  useSecureCard,
  CardNumberField,
  ExpiryField,
  SecurityCodeField,
  PostalCodeField,
  type SecureCardSession,
} from '@usethrottle/checkout-react';

// `session` is the Task 2 mint response, fetched server-side and passed down.
// `checkoutSessionId` is YOUR Throttle checkout session id — the ":id" you
// minted against, NOT session.sessionId (that one is the payment provider's). See below.
export function CardCheckout({
  session,
  checkoutSessionId,
}: {
  session: SecureCardSession;
  checkoutSessionId: string;
}) {
  return (
    <SecureCardProvider
      session={session}
      checkoutSessionId={checkoutSessionId}
      apiBaseUrl="https://api.usethrottle.dev"
      onSuccess={(result) => {
        window.location.href = `/thank-you?order=${result.orderId}`;
      }}
    >
      <PayForm />
    </SecureCardProvider>
  );
}

function PayForm() {
  const { ready, status, error, pay, registerThreeDSecure } = useSecureCard();
  const busy = status === 'vaulting' || status === 'authorizing' || status === 'challenging';

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        pay();
      }}
    >
      <CardNumberField className="my-input" />
      <ExpiryField className="my-input" />
      <SecurityCodeField className="my-input" />
      <PostalCodeField className="my-input" />

      {/* Mount point for the payment provider's own 3-D Secure challenge iframe. Register it
          once — it only actually mounts if a payment comes back requires_action. */}
      <div ref={(el) => { if (el) registerThreeDSecure(el); }} />

      <button disabled={!ready || busy}>
        {status === 'challenging' ? 'Confirming with your bank…' : busy ? 'Paying…' : 'Pay'}
      </button>
      {error && <p role="alert">{error.message}</p>}
    </form>
  );
}

Status

useSecureCard() exposes an explicit state machine. Render any of it — there is no need to infer state from side effects.

3-D Secure

A payment that needs step-up authentication does not fail — complete() resolves with status: 'requires_action' instead of an order. pay() handles this for you.

{
  "status": "requires_action",
  "paymentStatus": "requires_action"
}
// No orderId / paymentId yet — this is not a completion. useSecureCard()
// handles this response for you; you will only ever see it if you call
// complete() yourself instead of pay().

When that happens, the hook moves to challenging and drives the payment provider's own 3DS iframe (mounted at the element you passed to registerThreeDSecure) to a result, then re-calls /complete for the authoritative outcome. Register the mount element alongside your card fields — it only actually mounts a challenge when one is needed, so it costs nothing to always include it.

• If the buyer never resolves the challenge, challengeTimeoutMs (5 minutes by default, overridable via the same-named <SecureCardProvider> prop) settles complete() to error.code: 'three_ds_timeout' on its own.
• Calling cancelChallenge() (also from useSecureCard()) abandons an in-progress challenge with error.code: 'three_ds_abandoned'.
• If the challenge resolves but the payment still needs authentication, or if the buyer keeps retrying without ever clearing it, Throttle caps re-entry at 5 attempts and returns 409 three_ds_unresolved. Treat this as terminal: tell the buyer to start a new checkout rather than retrying the same session again.

Saved cards

Whether a card gets saved is decided entirely by the checkout session you minted the card session against — nothing the browser sends can change it.

• If that Throttle checkout session carries a customerId (set directly, or inherited from its cart), Throttle pins the the payment provider buyer at mint time. A successful payment vaults the card against that customer, and it appears in their saved payment methods on the next read.
• A session with no resolvable customer mints and charges as a guest. The payment still completes normally; nothing is saved, and that is correct behaviour, not a degraded path.

Testing failures

The success path is the easy half. These are the failures worth driving before you go live, and how to cause each one on purpose.

Declines

Sandbox card simulators generally approve everything, so you cannot get a decline by picking a “bad” card number. Cause one with a decline rule instead — the same mechanism you would use in production to refuse high-risk traffic. Conditions can match amount, currency, country, card scheme, card type or metadata.

# Decline every card charge over $99 on this application.
# Routing -> Decline rules in the dashboard does the same thing.
curl -X PUT https://api.usethrottle.dev/api/v1/card-decline \
  -H "X-API-Key: $THROTTLE_SECRET_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"rules":[{"conditions":[{"type":"amount","op":"gt","currency":"USD","min":99}],"errorCode":"flow_high_value"}]}'

# Remove it again when you are done.
curl -X PUT https://api.usethrottle.dev/api/v1/card-decline \
  -H "X-API-Key: $THROTTLE_SECRET_KEY" \
  -H 'Content-Type: application/json' -d '{"rules":[]}'

A charge matching the rule comes back card_declined, and the message carries your own errorCode so you can tell your rules apart from a real issuer decline.

A declined session stays usable. The claim is released, the pending order is reused rather than duplicated, and the buyer can submit again with another card. Retrying a declined session three times creates exactly one order.

3-D Secure

A challenge does not happen because of the card number alone. It needs the card session to carry the amount (it always does), 3-D Secure enabled on the payment service, and a 3DS scenario matching the card or amount. Scenarios are sandbox-only. Without one configured, every card behaves as if no challenge were required — including the PANs other processors treat as 3DS test cards.

Once configured, drive: the challenge completing (complete), the buyer abandoning it (cancelChallenge() → three_ds_abandoned), and the buyer walking away (three_ds_timeout after challengeTimeoutMs).

The rest

• Double submit — call pay() twice quickly. The second is rejected vault_in_progress; the first is never orphaned.
• Session already paid — complete twice. The second is already_completed.
• Saved card that is not theirs — pass another customer's paymentMethodId. Refused payment_method_not_found.
• Saved card on a guest checkout — payment_method_requires_customer.
• Empty or unpriced cart — minting the card session fails amount_unavailable rather than producing a session that silently cannot do 3DS.
• Strict CSP — the fields render as blank boxes. See Content Security Policy above.

Error reference

Errors surface as { code, message } — from a rejected vault()/complete()/pay() promise, or as useSecureCard().error after the state machine moves to error.

Minting (your server, calling /card-session)

Field mounting and vaulting (the hook, in the browser)

3-D Secure (the hook)

Completion (surfaced from /complete)

Fallback codes