@zippypay/checkout 1.2.0 → 1.2.2

package/README.md

@@ -108,7 +108,7 @@ Load from a public npm CDN:
 </script>
 ```
 
-Pin the version in production (e.g. `@1.1.0` instead of `@1`).
+Pin the version in production (e.g. `@1.2.0` instead of `@1`).
 
 ---
 
@@ -134,9 +134,12 @@ type ZippyPayConfig = {
   mode?: 'inline' | 'modal';
   container?: HTMLElement | string; // required for inline
   theme?: ZippyTheme;
-  /** Restrict checkout methods. Omit for full chooser (QR + manual). */
+  /** Restrict web checkout methods. Omit for full chooser (QR + manual). */
   checkoutPolicy?: 'QR' | 'MANUAL';
-  /** Phone-only app handoff. Ignored on desktop. */
+  /**
+   * Phone-only app handoff. Ignored on desktop.
+   * Default policy: `enforce` (SDK 1.2.0+). Pass `{ policy: 'off' }` for web-only on phone.
+   */
   mobileApp?: { policy?: 'off' | 'option' | 'enforce' };
   redirectOnComplete?: boolean;
   redirectOnFailure?: boolean;
@@ -165,17 +168,52 @@ Control which payment methods customers can use:
 
 ### Mobile app (phone)
 
+On **phone**, customers can pay in the Zippy app via **Pay with Zippy**. On **desktop**, mobile app settings are ignored — customers use QR and/or manual per `checkoutPolicy`.
+
 | `mobileApp.policy` | Phone behavior |
 |---|---|
-| `off` *(default)* | Web checkout only (QR / manual per policy) |
-| `option` | “Pay with Zippy” on the chooser; opens the app on tap |
-| `enforce` | Auto-starts app handoff; QR/manual hidden unless handoff fails |
+| `enforce` *(default)* | Auto-starts Pay with Zippy; QR/manual hidden until app handoff fails |
+| `option` | Full chooser plus a “Pay with Zippy” button |
+| `off` | Web checkout only (QR / manual per `checkoutPolicy`) |
+
+Omitting `mobileApp` (or `policy`) is the same as `enforce` (SDK **1.2.0+**). To keep web-only checkout on phone (behavior before 1.2.0):
+
+```typescript
+mobileApp: { policy: 'off' }
+```
+
+#### Pay with Zippy flow
+
+1. Customer taps **Pay with Zippy** (or checkout auto-starts it when `enforce`).
+2. The button becomes disabled and shows **Opening Zippy…** for up to **8 seconds**.
+3. The SDK opens the app from that tap — checkout **stays on your page**:
+   - **iOS:** `https://zippypay.io/app/merchant-payment/{sessionId}`
+   - **Android:** intent URL for the same HTTPS link targeting `com.zippy.pay`
+4. If the app opens → *Complete your payment in the Zippy app.*
+5. If the app does not open → failed handoff UI:
+   - **Try again**
+   - **Or pay another way** (QR and/or manual per `checkoutPolicy`)
+   - **Install Zippy** (bottom) — opens the native store; **not** opened automatically
 
-On **Pay with Zippy** (iPhone and Android), checkout shows “Opening Zippy…”, tries the app in a hidden iframe so the browser stays on checkout, and waits 5 seconds. If Safari, Chrome, or any other browser is still in front, it opens the App Store (`itms-apps://`) or the Play Store listing (`https://play.google.com/store/apps/details?id=com.zippy.pay`).
+**Install Zippy store links** (fixed by Zippy, not merchant-configurable):
 
-On **desktop**, the app option is never shown — customers use QR or manual as allowed by `checkoutPolicy`.
+| Platform | Web / QR | Install button (native) |
+|---|---|---|
+| iOS | [App Store](https://apps.apple.com/in/app/zippypay/id6806799311) | `itms-apps://apps.apple.com/in/app/zippypay/id6806799311` |
+| Android | [Google Play](https://play.google.com/store/apps/details?id=com.zippy.pay) | `market://details?id=com.zippy.pay` |
+
+Deep links and QR payloads use **`sessionId` only** — never include `clientToken`.
+
+#### Switching from mobile app to QR or manual
+
+If checkout started as **MOBILE_APP** and the customer has **not** yet claimed payment in the app, they may switch from the **failed handoff** screen:
+
+| Customer picks | SDK behavior |
+|---|---|
+| **QR code** | Starts QR checkout (pay timer is not reset) |
+| **Zippy account (manual)** | Opens manual entry; backend switches to `MANUAL` when the payer is verified and attached |
 
-Web component attributes: `checkout-policy="QR"`, `mobile-app-policy="enforce"`.
+After payment is claimed in the app or a payer is attached on manual, method switching is no longer available.
 
 ### Theming
 
@@ -206,13 +244,14 @@ The SDK guides customers through payment and keeps your page updated until the s
 |---|---|
 | **QR** | Scan a QR code in the Zippy app, then confirm payment in the app |
 | **Manual** | Enter a Zippy ID, verify identity, then confirm payment in the app |
-| **Mobile app** | Open the Zippy app on this phone; fallback to QR/manual if the app cannot open |
+| **Mobile app (phone)** | Tap **Pay with Zippy** → pay in the app; fallback to QR/manual if the app cannot open |
 
-After a method is chosen, the customer generally cannot switch to another method.
+After QR or manual checkout is committed, customers generally cannot switch methods. **Exception:** **MOBILE_APP → QR/MANUAL** is allowed **before claim**, via the failed handoff fallbacks.
 
 ### Timers and amount
 
-- A **pay timer** appears once checkout is in progress.
+- A **bottom pay progress bar** shows during the pay window (including idle **Pay with Zippy**).
+- The **inline countdown timer** is hidden on idle and **Opening Zippy…**; it appears after the app opens, on failed handoff, and while awaiting payment.
 - Display the **amount from the session** passed to your callbacks (`onReady`, `onSessionUpdate`, `onComplete`) — do not rely on amount props from your own page markup alone.
 - Sessions also have idle and absolute expiry boundaries handled by the SDK UI.
 
@@ -228,7 +267,7 @@ After a method is chosen, the customer generally cannot switch to another method
 | `session-id` | Session UUID |
 | `mode` | `inline`, `modal` |
 | `checkout-policy` | `QR`, `MANUAL` |
-| `mobile-app-policy` | `option`, `enforce` |
+| `mobile-app-policy` | `off`, `option`, `enforce` *(default: enforce when omitted)* |
 | `theme-*` | See theming table above |
 
 Set `clientToken` via the **property** (not an HTML attribute).