DEVELOPER GUIDE

Flow SDK Reference

The complete client API for the Zepto Flow widget.

The Flow SDK is one self-contained browser bundle (flow.js). It exposes one global, ZeptoFlow. Its one entry point is ZeptoFlow.mount(). This entry point renders the PayTo workflow into your page. It returns a handle. Use the handle to update, subscribe to, and destroy the widget.

Load the SDK

<!-- Sandbox -->
<script src="https://go.sandbox.zeptopayments.com/flow/assets/flow.js"></script>

<!-- Live -->
<script src="https://go.zeptopayments.com/flow/assets/flow.js"></script>

The bundle is an IIFE that assigns window.ZeptoFlow. It includes its own runtime, so there is nothing to install and there are no peer dependencies. It renders into a shadow root. Its styles never leak into your page and never inherit from it. The bundle has one fixed Zepto environment. Load the URL that matches the environment your token was created for.

window.ZeptoFlow = {
  mount,       // (target, options) => MountHandle
  version,     // string, e.g. "0.0.1"
  ZEPTO_EVENT, // "zepto:event": the underlying DOM event name
};

`ZeptoFlow.mount(target, options)`

function mount(target: string | Element, options: MountOptions): MountHandle;

Renders the widget into target and starts the workflow from options.action.

target: a CSS selector string (resolved with document.querySelector) or an Element. It throws if a selector matches nothing. It also throws if the value is neither a string nor an Element.
options: see below. The SDK validates options synchronously. Invalid required fields throw a [zepto-flow] … error instead of rendering.
Returns a MountHandle.

`MountOptions`

interface MountOptions {
  token: string;                 // opaque workflow token from your Payment Intent. Required.
  action: Action;                // first action from your Payment Intent. Required.
  theme?: ThemeOverride | null;  // visual overrides. Optional.
  dev?: { debug?: boolean };     // dev-only flow debugger sidecar. Optional.
}

interface Action {
  name: string;                  // e.g. "collect-debtor-details"
  path: string | null;           // next operation path; null at a terminal action
}

token and action.name must be non-empty. Both come straight from your create-payment-intent response. Pass them through unchanged.

The mount handle

interface MountHandle {
  readonly element: HTMLElement;
  update(options: Partial<MountOptions>): void;
  subscribe(listener: (event: ZeptoEnvelope) => void): () => void;
  destroy(): void;
}

Member	Behaviour
`element`	The wrapper element the widget rendered into. The shadow root itself is not exposed.
`update(partial)`	Patch the mounted options. It uses `'key' in partial` semantics, so `update({ theme: null })` clears the theme. A change to `token` or `action` starts a fresh workflow on the same host. After `destroy()` it does nothing and logs a warning.
`subscribe(listener)`	Register a lifecycle-event listener. It returns an unsubscribe function. You can subscribe more than once.
`destroy()`	Unmount the widget, remove its element, and abort any in-flight request. Idempotent.

Events

The SDK delivers every event as an envelope. Void-payload events carry only { type }. The two events that carry data add a payload.

type ZeptoEnvelope =
  | { type: 'zepto:payto:ready' }
  | { type: 'zepto:payto:payment-created' }
  | { type: 'zepto:payto:payment-settled' }
  | { type: 'zepto:payto:payment-failed'; payload: { errors: ResultError[] } }
  | { type: 'zepto:payto:error'; payload: { code: string; message: string } };

interface ResultError {
  title: string;   // short human-readable summary
  detail: string;  // longer description
  code: string;    // Zepto error code, e.g. "ZPPAY01"
}

See Handle the payment lifecycle for what each event means and when it fires.

Events are namespaced by rail. Every Flow event uses the zepto:payto: prefix. This leaves room for future rails, such as PayID (zepto:payid:).

subscribe() is a convenience over one DOM CustomEvent named zepto:event (the exported ZEPTO_EVENT). The SDK dispatches this event on handle.element with bubbles: true, composed: true and the envelope in event.detail.

Theme the widget

interface ThemeOverride {
  colors?: {
    surface?:  { base?; sunken?; overlay?; inverse? };
    border?:   { default? };
    content?:  { default?; strong?; subtle?; inverse? };
    brand?:    { default?; onBrand? };
    feedback?: {
      successSurface?; successContent?;
      errorSurface?;   errorContent?;
      infoSurface?;    infoContent?;
    };
  };
  radius?: number | string;              // number → px; or a CSS length ("8px", "0.5rem")
  fontFamily?: { sans?: string; mono?: string };
}

See Theming the widget for token meanings and examples.

Errors thrown by `mount()`

These are integration mistakes. The SDK throws them synchronously. They are not events:

Mount target not found for a selector, or a target that is neither a selector nor an Element.
Missing or empty token, or missing or empty action.name.

All carry a [zepto-flow] … message. Runtime workflow problems are different. They arrive as zepto:payto:payment-failed or zepto:payto:error events.