AforoCheckoutFlow

What it renders#

A multi-step embedded checkout widget that owns the entire customer billing flow — from cart creation through payment confirmation — inside your page. No redirects, no popups. Two cart types:

• SUBSCRIBE — start a new subscription to an offering
• INVOICE_PAYMENT — pay an existing outstanding invoice

Phase machine#

The widget walks the customer through a 4-phase state machine. Each phase emits an aforo.checkout.step_changed event so your analytics can track funnel drop-off.

<div data-aforo-widget="checkout-flow"
     data-aforo-tenant-slug="your-tenant"
     data-aforo-embed-key="ek_live_replace_me"
     data-aforo-bridge-token="bridge.replace.me"
     data-aforo-cart-type="SUBSCRIBE"
     data-aforo-target-id="off_pro"></div>

<script src="https://cdn.aforo.ai/embed/loader.js" async></script>

import { AforoCheckoutFlow } from '@aforoai/storefront-widgets';

export function Pricing() {
  return (
    <AforoCheckoutFlow
      tenantSlug="your-tenant"
      embedKey="ek_live_replace_me"
  bridgeToken="bridge.replace.me"
  cartType="SUBSCRIBE"
  targetId="off_pro"
    />
  );
}

Mount examples#

import { AforoCheckoutFlow } from '@aforoai/storefront-widgets';

export default async function SubscribePage() {
  const session = await getSession();
  const bridgeToken = await mintBridgeToken({
    externalId: session.customerId,
    email: session.email,
  });

  return (
    <AforoCheckoutFlow
      tenantSlug="acme"
      embedKey="embk_live_…"
      bridgeToken={bridgeToken}
      cartType="SUBSCRIBE"
      targetId="off_pro"
      onCompleted={(payload) => {
        console.log('Subscription created:', payload.subscriptionId);
        router.push('/welcome');
      }}
      onCancelled={() => {
        router.push('/pricing');
      }}
    />
  );
}

Props reference#

Payment providers#

The widget supports three payment providers — selected by your tenant's configured primary gateway in Aforo (Storefront → Payment Providers):

• Stripe — Payment Element via js.stripe.com/v3 iframe. Supports Cards, Apple Pay, Google Pay, ACH, SEPA. 3DS challenges flow through Stripe's hosted challenge page in a new tab.
• Razorpay — Drop-in via checkout.razorpay.com. Supports Cards, UPI, NetBanking, Wallets. Primary for INR payments.
• PayPal — Smart Payment Buttons via www.paypal.com. Approval flow runs in a popup; the widget listens for aforo:payment-challenge-completed when the popup returns.

Events#

CheckoutFlow emits a rich event sequence. Notable privacy guarantee: aforo.checkout.customer_details_submitted contains booleans only — never raw address values, never the customer's name or email. The widget verifies this contract in its test suite to prevent regressions.

See the Events reference for the full envelope shape and the SSE-pushed aforo.payment.failed event the widget consumes during the payment phase.

Limitations#

• 3DS / SCA inline modal is Phase 1. v0.1.x falls back to the gateway-hosted 3DS challenge in a new tab. The widget waits for aforo:payment-challenge-completed to resume the flow.
• Coupon code input is Phase 1. The server-side V49 coupon engine ships today; the customer-facing input lands later.
• Tax preview is Phase 1. The widget shows the subscription price excluding tax — tax appears on the resulting invoice. Inline tax preview at cart- create time is filed.
• NET 30 "pay later" flow. Deferred until first B2B customer asks. Today, all carts settle at confirm time.