Checkout flow and screens

The SDK loads the payment session and guides the customer through checkout. On phone (SDK 1.2.0+), checkout auto-starts Pay with Zippy unless you opt out. On desktop, customers use QR and/or manual entry per checkoutPolicy.

On phone, the SDK can open the Zippy Pay app so customers complete payment there. Configure with mobileApp.policy in ZippyPay.create() or mobile-app-policy on <zippy-pay-checkout>. Requires SDK 1.1.0+ for mobile app features; 1.2.0+ for the new default.

On desktop, mobile app settings are ignored. Customers always use QR and/or manual entry per checkoutPolicy.

Default behavior (1.2.0+)

If you omit mobileApp, or omit policy inside it, the SDK uses enforce on phone:

ZippyPay.create({ environment, sessionId, clientToken });
ZippyPay.create({ environment, sessionId, clientToken, mobileApp: {} });
ZippyPay.create({ environment, sessionId, clientToken, mobileApp: { policy: 'enforce' } });

ZippyPay.create({
  environment,
  sessionId,
  clientToken,
  mobileApp: { policy: 'off' },
});

Migration from 1.1.x

• Want Pay with Zippy by default? Upgrade to 1.2.1 (or 1.2.0+) — no config change.
• Want web-only on phone? Add mobileApp: { policy: 'off' }.
• Already set enforce or option? No change needed.

FAQ

Customer flow

1. Customer sees Pay with Zippy (enforce) or taps it from the chooser (option).
2. Button shows Opening Zippy… (disabled, with spinner) while the SDK attempts to open the app.
3. SDK opens the Zippy Pay app when the customer taps (iOS and Android). Checkout stays on your page.
4. If the app opens: Complete your payment in the Zippy app. (no Try again).
5. If the app does not open: failed handoff screen (below). The App Store / Play Store is not opened automatically.

Failed app handoff

If the app does not open, the customer sees:

• We couldn't open the Zippy app on this device.
• Try again — retries opening the app (same as Pay with Zippy).
• Or pay another way — QR and/or manual cards per checkoutPolicy.
• Install Zippy (bottom) — opens the native store when tapped. iOS: App Store. Android: Play Store.

The header on all active screens shows the business name and formatted amount from the session. A pay progress bar appears when the pay window is active (phase === 'PAYING' with valid paymentExpiryAt).

Payment QR codes and mobile app handoff use your sessionId only — never the client token. Desktop customers scan the QR; phone customers may open the app via Pay with Zippy.

• Rendered as a branded QR with centred Zippy logo (desktop).
• Pay with Zippy opens the installed Zippy Pay app on phone.
• Error correction level: H (high) for QR.
• Never include clientToken in QR payloads or share links.

Personal Zippy handles (payment IDs) are validated before verify and attach:

Valid: abc, user123, john.doe12. Invalid: ab (too short), a..b (double dot), .john.

The SDK polls session status while the checkout is in a non-terminal state.

Polling also stops on unrecoverable errors (401, bootstrap failure) or when destroy() is called.

Errors are RFC 7807 application/problem+json, surfaced as ZippyPayError:

• Supported browsers: current Chrome, Firefox, Safari, Edge (evergreen).
• Serve the host application over HTTPS in production.
• Node.js ≥ 18 for local development and bundlers.