DEVELOPER GUIDE

Handle the Payment Lifecycle

React to the events the Flow widget emits as it drives the PayTo workflow.

After it mounts, the widget advances the PayTo workflow on its own. It emits lifecycle events as it enters each step. Subscribe to these events to update your page. For example, show a spinner, redirect on success, or offer a retry on failure.

Subscribe to events

subscribe() registers a listener and returns an unsubscribe function:

const unsubscribe = widget.subscribe((event) => {
  switch (event.type) {
    case 'zepto:payto:ready':
      break;
    case 'zepto:payto:payment-created':
      showPending();
      break;
    case 'zepto:payto:payment-settled':
      window.location.assign('/checkout/success');
      break;
    case 'zepto:payto:payment-failed':
      showRetry(event.payload.errors);
      break;
    case 'zepto:payto:error':
      showError(event.payload);
      break;
  }
});

The events

Event	When it fires	Payload
`zepto:payto:ready`	The widget mounted and rendered.	None
`zepto:payto:payment-created`	The widget created the payment. Settlement is pending.	None
`zepto:payto:payment-settled`	Terminal success.	None
`zepto:payto:payment-failed`	Terminal failure.	`{ errors }`
`zepto:payto:error`	The API returned a result that is not a valid workflow result, or the network failed.	`{ code, message }`

Each error in a zepto:payto:payment-failed payload is { title, detail, code }, where code is a Zepto error code such as ZPPAY01.

What the payer moves through

Behind those events, the widget walks the payer through the PayTo workflow:

Collect details. The widget renders a form for the payer's PayID or BSB and account. It then creates the PayTo agreement. zepto:payto:ready fires on mount.
Authorise the agreement. The payer approves the PayTo agreement in their banking app. The widget waits.
Payment created. The widget creates the payment and emits zepto:payto:payment-created. It then waits for settlement.
Terminal. On success, the widget emits zepto:payto:payment-settled. On the failure branch, it emits zepto:payto:payment-failed with the errors.

Recoverable input problems stay inside the widget

If the payer mistypes an alias, or the widget cannot resolve their bank account, the widget shows the problem in its own UI. The payer can then correct it. These problems do not emit zepto:payto:error. Use your zepto:payto:error handling only for true integration or transport faults.

Advanced: listen on the DOM

subscribe() is a convenience over a single DOM CustomEvent named zepto:event. The widget dispatches it on the widget element with bubbles: true and composed: true. To capture events at the page level for analytics, listen directly:

widget.element.addEventListener('zepto:event', (e) => {
  // analytics.track(e.detail.type);
});

Next steps

Test both outcomes in the sandbox before you go live.