@zippypay/checkout 1.0.0 → 1.1.11

package/README.md

@@ -1,5 +1,8 @@
 # @zippypay/checkout
 
+[![npm version](https://img.shields.io/npm/v/@zippypay/checkout.svg)](https://www.npmjs.com/package/@zippypay/checkout)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
 Browser checkout SDK for **Zippy Pay** merchants. Embed payment UI inline on a checkout page or open it in a modal. Works with vanilla JavaScript, React, Vue, Angular, and any stack that runs modern JavaScript.
 
 Styles are scoped inside Shadow DOM — no extra CSS import is required.
@@ -16,6 +19,10 @@ npm install @zippypay/checkout
 yarn add @zippypay/checkout
 ```
 
+```bash
+pnpm add @zippypay/checkout
+```
+
 ---
 
 ## Before the SDK runs
@@ -24,10 +31,10 @@ Your **server** creates a payment session and passes credentials to the checkout
 
 | Field | Description |
 |---|---|
-| `sessionId` | UUID v4 from `POST /payment-sessions` — safe in URLs |
-| `clientToken` | `zps_…` from the create-session response — **server → browser only** |
+| `sessionId` | Payment session identifier — safe in URLs |
+| `clientToken` | Short-lived token from your server — **browser only, never public** |
 
-Never expose `X-Api-Key` or Clerk JWT from browser code. Never put `clientToken` in QR codes, query strings, logs, or analytics.
+Never expose merchant API credentials in browser code. Never put `clientToken` in QR codes, query strings, logs, or analytics.
 
 ---
 
@@ -86,7 +93,7 @@ ZippyPay.create({
 
 ### Script tag (UMD)
 
-Serve or bundle is not required — load from a public npm CDN:
+Load from a public npm CDN:
 
 ```html
 <script src="https://unpkg.com/@zippypay/checkout@1/dist/index.min.js"></script>
@@ -101,23 +108,19 @@ Serve or bundle is not required — load from a public npm CDN:
 </script>
 ```
 
-Pin the version in production (`@1.0.0` instead of `@1`).
+Pin the version in production (e.g. `@1.1.0` instead of `@1`).
 
 ---
 
 ## Environments
 
-Pass `environment` — the SDK resolves the API base URL:
-
-| Environment | API origin |
+| Environment | Use when |
 |---|---|
-| `production` | `https://api.zippypay.io` |
-| `staging` | `https://staging.api.zippypay.io` |
-| `development` | Same-origin (empty base — for local proxies) |
+| `production` | Live merchant checkout |
+| `staging` | Pre-production testing |
+| `development` | Local development with a proxy |
 
-All requests use the prefix `/api/v1` (e.g. `GET https://api.zippypay.io/api/v1/payment-sessions/:id`).
-
-Use the environment where your merchant backend created the session.
+Use the same environment where your server created the payment session.
 
 ---
 
@@ -131,6 +134,10 @@ type ZippyPayConfig = {
   mode?: 'inline' | 'modal';
   container?: HTMLElement | string; // required for inline
   theme?: ZippyTheme;
+  /** Restrict checkout methods. Omit for full chooser (QR + manual). */
+  checkoutPolicy?: 'QR' | 'MANUAL';
+  /** Phone-only app handoff. Ignored on desktop. */
+  mobileApp?: { policy?: 'off' | 'option' | 'enforce' };
   redirectOnComplete?: boolean;
   redirectOnFailure?: boolean;
   closeOnBackdropClick?: boolean;
@@ -146,6 +153,30 @@ type ZippyPayConfig = {
 
 **Instance methods:** `open()`, `close()` (modal), `destroy()`
 
+### Checkout policy
+
+Control which payment methods customers can use:
+
+| Config | Customer sees |
+|---|---|
+| *(omit `checkoutPolicy`)* | Full chooser — QR + manual |
+| `checkoutPolicy: 'QR'` | QR only |
+| `checkoutPolicy: 'MANUAL'` | Manual Zippy ID only |
+
+### Mobile app (phone)
+
+| `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 |
+
+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`).
+
+On **desktop**, the app option is never shown — customers use QR or manual as allowed by `checkoutPolicy`.
+
+Web component attributes: `checkout-policy="QR"`, `mobile-app-policy="enforce"`.
+
 ### Theming
 
 | Token | CSS variable | Default |
@@ -165,27 +196,52 @@ Web component: use `theme-primary`, `theme-mode`, etc.
 
 ---
 
-## Checkout flow
+## Checkout experience
 
-1. **Choose method** — QR scan or manual Zippy ID (one-way; cannot switch)
-2. **QR** — `POST …/checkout/start { method: "QR" }` → show QR + pay timer → poll until paid
-3. **Manual** — verify ID → attach payer → pay timer → poll until paid
+The SDK guides customers through payment and keeps your page updated until the session reaches a final state.
 
-Display the **amount from the GET session response**, not from your page props.
+### Payment methods
 
-Three time boundaries: `expiresAt` (idle), `paymentExpiryAt` (pay window), `absoluteExpiresAt` (hard max).
+| Method | Customer experience |
+|---|---|
+| **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 |
+
+After a method is chosen, the customer generally cannot switch to another method.
+
+### Timers and amount
+
+- A **pay timer** appears once checkout is in progress.
+- 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.
 
 ---
 
-## Web component events
+## Web component
+
+### Attributes
+
+| Attribute | Values |
+|---|---|
+| `environment` | `production`, `staging`, `development` |
+| `session-id` | Session UUID |
+| `mode` | `inline`, `modal` |
+| `checkout-policy` | `QR`, `MANUAL` |
+| `mobile-app-policy` | `option`, `enforce` |
+| `theme-*` | See theming table above |
+
+Set `clientToken` via the **property** (not an HTML attribute).
+
+### Events
 
 | Event | When |
 |---|---|
-| `zippy-ready` | Session loaded |
-| `zippy-session-update` | Poll update |
+| `zippy-ready` | Checkout loaded and ready |
+| `zippy-session-update` | Session status updated |
 | `zippy-complete` | Payment succeeded |
 | `zippy-expired` | Session expired |
-| `zippy-error` | Terminal / API error |
+| `zippy-error` | Checkout error |
 | `zippy-close` | Modal closed |
 
 ---
@@ -235,26 +291,18 @@ Import the package, use `CUSTOM_ELEMENTS_SCHEMA`, set `nativeElement.clientToken
 
 ---
 
-## API authentication (SDK)
+## Error handling
 
-| Header | Value |
-|---|---|
-| `X-Payment-Session-Token` | `zps_…` (preferred) |
-| `Authorization` | `Bearer zps_…` (fallback) |
-
-Errors are RFC 7807 `application/problem+json`, surfaced as `ZippyPayError` with `code`, `status`, and `detail`.
-
-On **401**: treat the token as invalid; create a new session — do not retry blindly.
+Use `onError` to receive a `ZippyPayError` with `code`, `status`, and `detail`. If checkout cannot continue (for example, an invalid or expired token), show your own recovery flow — typically creating a new session on your server and re-initializing the SDK.
 
 ---
 
 ## Security checklist
 
-1. Never bundle `X-Api-Key` in browser code.
+1. Never bundle merchant API credentials in browser code.
 2. Keep `clientToken` in memory only.
-3. Encode only `sessionId` in QR / deep links — never the client token.
-4. Display amount from GET session, not merchant page props.
-5. Ensure your Zippy API environment allows your site origin in CORS for browser calls.
+3. Put only `sessionId` in QR codes and app deep links — never the client token.
+4. Use the session amount from SDK callbacks, not from unchecked page props.
 
 ---
 
@@ -265,6 +313,14 @@ On **401**: treat the token as invalid; create a new session — do not retry bl
 
 ---
 
+## More documentation
+
+Full integration guide and framework examples:
+
+**[github.com/IMAGINE-INNOVATION-LIMITED/zippy-pay-web-sdk](https://github.com/IMAGINE-INNOVATION-LIMITED/zippy-pay-web-sdk)**
+
+---
+
 ## License
 
 MIT © Imagine Innovation Limited