---
updatedAt: 2026-09-02T01:50:27.000Z
agentTools:
  projectIndex: https://docs.zeptopayments.com/llms.txt
---

# Handle the Payment Lifecycle

React to the events that the Flow widget emits while it drives the PayTo workflow to a terminal outcome.

<div class="zepto-docs-hero">
  <div class="zepto-docs-hero__content">
    <span class="zepto-docs-hero__badge">DEVELOPER GUIDE</span>
    <h1>Handle the Payment Lifecycle</h1>
    <p>React to the events the Flow widget emits as it drives the PayTo workflow.</p>
  </div>
  <div class="zepto-docs-hero__visual" aria-hidden="true">
    <div class="zepto-docs-hero__glow"></div>
    <div class="zepto-docs-hero__icon">
      <img class="logo" alt="Zepto Flow" src="https://files.readme.io/dcc5db35e266b31d34fe90b3c87705e876f39854b29984127983f42e647d2187-Integration.png">
    </div>
  </div>
</div>

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:

```js
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:

1. **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.
2. **Authorise the agreement**. The payer approves the PayTo agreement in their banking app. The widget waits.
3. **Payment created**. The widget creates the payment and emits `zepto:payto:payment-created`. It then waits for settlement.
4. **Terminal**. On success, the widget emits `zepto:payto:payment-settled`. On the failure branch, it emits `zepto:payto:payment-failed` with the errors.

<Zepto_Callout type="info" title="Recoverable input problems stay inside the widget" id="recoverable-input-problems">
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.
</Zepto_Callout>

## 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:

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

## Next steps

**[Test both outcomes in the sandbox](https://docs.zeptopayments.com/docs/zepto-flow-sandbox-testing)** before you go live.