switchflow.js renders the card form on your checkout page, tokenizes card data directly from the browser to the PCI-certified vault, submits the payment, and holds a single loading state while routing and failover run. Raw card numbers never touch your servers — or SwitchFlow’s API.

​
1. Create a session server-side

The widget needs a payment session created by your backend with your secret key — see Create a payment session. Pass the response’s sessionId, clientSecret, and vault block to your page.

​
2. Mount the widget

<script src="https://js.switchflows.net/v1/switchflow.js"></script>
<div id="switchflow-checkout"></div>
<script>
  SwitchFlow.mount({
    container: '#switchflow-checkout',
    apiBase: 'https://api.switchflows.net',
    sessionId: session.sessionId,
    clientSecret: session.clientSecret,
    vault: session.vault,
    onSuccess: (result) => {
      // Payment captured — result.capturedVia, result.failoverUsed
      window.location.href = '/order/complete?ref=' + orderRef;
    },
    onDeclined: (result) => {
      // Terminal decline — result.declineCode
      showRetryMessage(result.declineCode);
    },
    alternativeMethodLabel: 'Pay with PayPal'
  });
</script>
All options, callbacks, and result shapes: Widget reference.

​
What the customer experiences

  1. The widget renders card number, expiry, and CVC fields.
  2. On submit, the card is tokenized straight to the vault; the widget shows a loading state.
  3. SwitchFlow attempts capture on your priority-1 gateway and — if needed — fails over to the next priority, all within the same loading state.
  4. The widget resolves to exactly one of three outcomes:
    • Success → your onSuccess callback (failover, if any, was invisible)
    • Decline → your onDeclined callback with the normalized decline code
    • Degradation (all gateways down) → the widget itself swaps the card form for your alternative payment method button, labeled with alternativeMethodLabel — the customer sees a fallback, not an error

​
PCI boundary

Card data flows browser → vault over TLS, and the vault detokenizes inline to the gateway at capture time. Your page, your servers, and SwitchFlow’s API only ever see an opaque token. This is what keeps your PCI scope at SAQ-A level.