paymob-widget-alpha 1.0.15 → 1.0.16

package/README.md

@@ -1,9 +1,8 @@
 # `paymob-widget-alpha`
-Paymob Installments Widget that can be embedded in any web page to display **0% interest plans** and (optionally) let the user select a plan.
+Paymob Installments Widget that can be embedded in any web page to display installment plans and (optionally) let the user select a plan.
 
 ## Installing
 
-
 ### CDN
 
 Using jsDelivr:
@@ -26,12 +25,30 @@ Then instantiate the widget:
 new PaymobWidget({
   publicKey: 'egy_pk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
   elementId: 'paymob-widget',
-  amount: 1000, // amount in cents
+  amount: 100000, // required — order total in cents (1000 EGP)
   currency: 'EGP',
-  integrationId: 123, // optional
+  integrationId: 123 || [123456, 2233], // optional — single number or array
 });
 ```
 
+If `amount` is missing, invalid, or not a positive finite number, the widget **will not initialize** and an error is logged to the console.
+
+### When the widget is shown or hidden
+
+The widget is **only rendered** when all of the following are true:
+
+- `amount` is valid (positive finite number in **cents**)
+- The installment-plans request returns a **2xx** status
+- At least one installment plan is available after processing the response
+
+The widget is **not shown** when:
+
+- `amount` is missing, `≤ 0`, or not a finite number → constructor stops and logs `console.error`
+- The API request **fails** (any non-2xx status, e.g. `400`) → widget hidden; `console.error` includes the status code
+- The API **succeeds** but returns **no plans** (e.g. invalid integration, amount below minimum, no bank installment configured) → widget hidden; `console.error` is logged
+
+**End users do not see error messages** on the page or in the modal. Errors are for developers in the **browser console** only (`[PaymobWidget] ...`).
+
 ### Selectable mode example
 
 To let the user select an installment plan and handle the selection in your app, enable `customerCanSelect` and pass an `onSubmit` callback.
@@ -40,46 +57,53 @@ To let the user select an installment plan and handle the selection in your app,
 new PaymobWidget({
   publicKey: 'egy_pk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
   elementId: 'paymob-widget',
-  amount: 1000, // amount in cents
+  amount: 100000, // required — order total in cents (1000 EGP)
   currency: 'EGP',
-  integrationId: 123, // optional
+  integrationId: 123 || [123456, 2233], // optional — single number or array
   theme: 'primary',
-  customerCanSelect: true, // Enable the customer to select a plan.
+  customerCanSelect: true,
   onSubmit: (plan) => {
-    // `onSubmit` is called when the user clicks **Buy now**.
-    // In selectable mode (`customerCanSelect: true`), `plan` will be provided after the user selects a plan.
-    // plan = { id: 123, tenure: 12, amount: 250 }
-    // In non-selectable mode (`customerCanSelect: false`), `onSubmit` is called with no payload.
+    // Called when the user clicks **Buy now**.
+    // With customerCanSelect: true, plan is provided after the user selects a plan.
+    // plan = { id: 123, tenure: 12, amount: 25000 } // amount = monthly installment in cents
+    // With customerCanSelect: false, onSubmit is called with no payload.
   },
 });
 ```
 
 ## Properties
 
-The full list of properties is as follows:
-
 | Property | Type | Required | Definition |
 | --- | --- | --- | --- |
 | publicKey | String | Yes | Your public key (used to resolve API base URL and authenticate requests). |
 | elementId | String | Yes | ID of the HTML element where the widget will be rendered. |
 | theme | `"primary" \| "light" \| "dark"` | No | Widget theme. Default: `"primary"`. |
-| amount | Number | Yes | Order total in **cents** (positive finite number). Required — the widget will not initialize without it. |
+| amount | Number | Yes | Order total in **cents** (positive finite number). **Required** — no default. The widget will not initialize without it. |
 | currency | String | No | Currency code. Default: `"EGP"`. |
-| integrationId | Number | No | Paymob integration ID. If provided, it will be sent when fetching installment plans. |
-| customerCanSelect | Boolean | No | If `true`, the widget allows selecting a plan and will show **Buy now** actions. Default: `false`. |
-| onSubmit | Function | No | Called when the user clicks **Buy now**. In selectable mode (`customerCanSelect: true`), it receives `{ id, tenure, amount }`. In non-selectable mode (`customerCanSelect: false`), it is called with no payload. |
+| integrationId | Number \| Number[] | No | Paymob integration ID(s). If provided, sent when fetching installment plans. |
+| customerCanSelect | Boolean | No | If `true`, the user can select a plan and **Buy now** is enabled. Default: `false`. |
+| onSubmit | Function | No | Called when the user clicks **Buy now**. With `customerCanSelect: true`, receives `{ id, tenure, amount }`. With `false`, called with no payload. |
+
+### `customerCanSelect` and Learn more
+
+| Value | Behavior |
+| --- | --- |
+| `true` | User can **select** a plan. Learn more includes the **Select Installment Plan** step. |
+| `false` | Plans are **read-only**. Learn more omits the selection step and uses different copy on the final payment step. |
 
 ### `onSubmit` payload
 
+When `customerCanSelect` is `true`:
+
 ```js
 {
   id: string | number,   // installment plan id
   tenure: number,        // number of months
-  amount: number         // monthly amount
+  amount: number         // monthly installment amount in cents
 }
 ```
 
-### Full HTML example
+## Full HTML example
 
 ```html
 <!DOCTYPE html>
@@ -91,12 +115,12 @@ The full list of properties is as follows:
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <style>
       #paymob-widget {
-      width: 100%;
-      margin: 10% auto 0;
-    }
+        width: 100%;
+        margin: 10% auto 0;
+      }
       body {
-      margin: 0;
-    }
+        margin: 0;
+      }
     </style>
   </head>
 
@@ -110,16 +134,13 @@ The full list of properties is as follows:
         new PaymobWidget({
           publicKey: 'egy_pk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
           elementId: 'paymob-widget',
-          amount: 1000,
+          amount: 100000, // required — order total in cents (1000 EGP)
           currency: 'EGP',
-          integrationId: 123, // optional
-          theme: 'primary', // "primary" | "light" | "dark"
-          customerCanSelect: true, // Enable the customer to select a plan.
+          integrationId: 123,
+          theme: 'primary',
+          customerCanSelect: true,
           onSubmit: (plan) => {
-    // `onSubmit` is called when the user clicks **Buy now**.
-    // In selectable mode (`customerCanSelect: true`), `plan` will be provided after the user selects a plan.
-    // plan = { id: 123, tenure: 12, amount: 250 }
-    // In non-selectable mode (`customerCanSelect: false`), `onSubmit` is called with no payload.
+            console.log('Selected plan', plan);
           },
         });
       };
@@ -130,8 +151,5 @@ The full list of properties is as follows:
 
 ## Notes
 
-- **Rendering**: The widget renders a Installment Widget into your `elementId` container.
+- **Rendering**: The widget renders into your `elementId` container only when eligible plans are available (see [When the widget is shown or hidden](#when-the-widget-is-shown-or-hidden)).
 - **Isolation**: UI is rendered inside a Shadow DOM wrapper to reduce CSS conflicts with the host page.
-
-
-