@paypercut/checkout-js 1.0.10 → 1.0.12

package/README.md

@@ -54,12 +54,12 @@ pnpm add @paypercut/checkout-js
 
 ```html
 <!-- jsDelivr (recommended with SRI) -->
-<script src="https://cdn.jsdelivr.net/npm/@paypercut/checkout-js@1.0.10/dist/paypercut-checkout.iife.min.js"
+<script src="https://cdn.jsdelivr.net/npm/@paypercut/checkout-js@1.0.12/dist/paypercut-checkout.iife.min.js"
         integrity="sha384-..."
         crossorigin="anonymous"></script>
 
 <!-- or UNPKG -->
-<script src="https://unpkg.com/@paypercut/checkout-js@1.0.10/dist/paypercut-checkout.iife.min.js"></script>
+<script src="https://unpkg.com/@paypercut/checkout-js@1.0.12/dist/paypercut-checkout.iife.min.js"></script>
 ```
 
 ---
@@ -118,12 +118,18 @@ Creates a new checkout instance.
 
 #### Options
 
-| Option | Type | Required | Description |
-|--------|------|----------|-------------|
-| `id` | `string` | Yes      | Checkout session identifier |
-| `containerId` | `string \| HTMLElement` | Yes      | CSS selector or element where iframe mounts. |
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `id` | `string` | Yes | — | Checkout session identifier (e.g., `CHK_12345`) |
+| `containerId` | `string \| HTMLElement` | Yes | — | CSS selector or element where iframe mounts |
+| `locale` | `string` | No | `'auto'` | Locale for checkout UI. Options: `'auto'`, `'en'`, `'en-GB'`, `'bg'`, `'bg-BG'` |
+| `ui_mode` | `'hosted' \| 'embedded'` | No | `'embedded'` | UI mode for checkout display |
+| `wallet_options` | `string[]` | No | `['apple_pay', 'google_pay']` | Digital wallet options. Pass `[]` to disable all wallets |
+| `form_only` | `boolean` | No | `false` | Show only payment form (no Pay Now button - use external button with `submit()`) |
 
-#### Example
+#### Examples
+
+**Basic initialization:**
 
 ```typescript
 const checkout = PaypercutCheckout({
@@ -132,6 +138,54 @@ const checkout = PaypercutCheckout({
 });
 ```
 
+**With all options:**
+
+```typescript
+const checkout = PaypercutCheckout({
+  id: 'CHK_12345',
+  containerId: '#checkout-container',
+  locale: 'en',                              // 'auto' | 'en' | 'en-GB' | 'bg' | 'bg-BG'
+  ui_mode: 'embedded',                       // 'hosted' | 'embedded'
+  wallet_options: ['apple_pay', 'google_pay'], // Can be empty array [] or contain one/both options
+  form_only: false                           // Set true to hide Pay Now button (use external button)
+});
+```
+
+**Disable wallet payments:**
+
+```typescript
+const checkout = PaypercutCheckout({
+  id: 'CHK_12345',
+  containerId: '#checkout-container',
+  wallet_options: []  // No Apple Pay or Google Pay buttons
+});
+```
+
+**Only Apple Pay:**
+
+```typescript
+const checkout = PaypercutCheckout({
+  id: 'CHK_12345',
+  containerId: '#checkout-container',
+  wallet_options: ['apple_pay']  // Only Apple Pay, no Google Pay
+});
+```
+
+**Form-only mode (external submit button):**
+
+```typescript
+const checkout = PaypercutCheckout({
+  id: 'CHK_12345',
+  containerId: '#checkout-container',
+  form_only: true  // No Pay Now button inside checkout
+});
+
+// Use your own button to trigger payment
+document.getElementById('my-pay-button').addEventListener('click', () => {
+  checkout.submit();
+});
+```
+
 ### Instance Methods
 
 #### `render()`
@@ -197,97 +251,50 @@ if (checkout.isMounted()) {
 
 ## Events
 
-Subscribe to events using the `on()` method:
-
-| Event | Description | Payload |
-|-------|-------------|---------|
-| `loaded` | Checkout iframe has finished loading | `void` |
-| `success` | Payment completed successfully | `PaymentSuccessPayload` |
-| `error` | Terminal failure (tokenize, confirm, or 3DS) | `ApiErrorPayload` (see details below) |
-| `expired` | Checkout session expired | `void` |
-| `threeds_started` | 3DS challenge flow started; SDK modal opened | `object` (flow context) |
-| `threeds_complete` | 3DS challenge completed | `object` (auth result context) |
-| `threeds_canceled` | 3DS challenge canceled by user | `object` (flow context) |
-| `threeds_error` | 3DS challenge error | `ApiErrorPayload` (if provided) or `object` |
-
-
-#### Success payload example
-
-```ts
-checkout.on('success', (payload) => {
-  // payload: PaymentSuccessPayload
-  // Example:
-  // {
-  //   payment_method: {
-  //     brand: 'visa',
-  //     last4: '4242',
-  //     exp_month: 12,
-  //     exp_year: 2030,
-  //   }
-  // }
-  console.log('PM last4', payload.payment_method.last4);
-});
-```
+Subscribe to events using the `on()` method. You can use string event names or the `SdkEvent` enum.
 
-#### Error payloads overview
+### Event Reference
 
-```ts
-checkout.on('error', (err) => {
-  switch (err.code) {
-    case 'card_validation_error':
-      // err.errors[] has field-level issues. Messages are localized.
-      break;
-    case 'card_declined':
-      // Optional err.decline_code and user-friendly err.message
-      break;
-    case 'threeds_error':
-    case 'threeds_authentication_failed':
-    case 'threeds_canceled':
-      // 3DS issue. Some servers use status_code 424 with a detailed message.
-      break;
-    default:
-      // Other terminal errors (e.g., authentication_failed, session_expired)
-      break;
-  }
-});
-```
+| Event | Enum | Description | Payload |
+|-------|------|-------------|---------|
+| `loaded` | `SdkEvent.Loaded` | Checkout iframe has finished loading | `void` |
+| `success` | `SdkEvent.Success` | Payment completed successfully | `PaymentSuccessPayload` |
+| `error` | `SdkEvent.Error` | Terminal failure (tokenize, confirm, or 3DS) | `ApiErrorPayload` |
+| `expired` | `SdkEvent.Expired` | Checkout session expired | `void` |
+| `threeds_started` | `SdkEvent.ThreeDSStarted` | 3DS challenge flow started | `object` |
+| `threeds_complete` | `SdkEvent.ThreeDSComplete` | 3DS challenge completed | `object` |
+| `threeds_canceled` | `SdkEvent.ThreeDSCanceled` | 3DS challenge canceled by user | `object` |
+| `threeds_error` | `SdkEvent.ThreeDSError` | 3DS challenge error | `ApiErrorPayload` or `object` |
 
-### 3DS Events (enum usage recommended)
+### Usage Examples
 
-You can subscribe using string event names or the SdkEvent enum:
+**Using string event names:**
 
 ```ts
-import { PaypercutCheckout, SdkEvent } from '@paypercut/checkout-js';
-
 const checkout = PaypercutCheckout({ id: 'CHK_12345', containerId: '#checkout' });
 
-checkout.on(SdkEvent.ThreeDSStarted, (ctx) => {
-  // e.g., show your own UI indicator or log ctx
+checkout.on('loaded', () => {
+  console.log('Checkout loaded');
 });
 
-checkout.on(SdkEvent.ThreeDSComplete, (payload) => {
-  // 3DS completed successfully; Hosted Checkout will continue the flow
+checkout.on('success', (payload) => {
+  // PaymentSuccessPayload
+  console.log('Payment successful');
+  console.log('Card brand:', payload.payment_method.brand);
+  console.log('Last 4:', payload.payment_method.last4);
+  console.log('Expiry:', payload.payment_method.exp_month + '/' + payload.payment_method.exp_year);
 });
 
-checkout.on(SdkEvent.ThreeDSCanceled, (payload) => {
-  // User canceled the 3DS challenge
+checkout.on('error', (err) => {
+  console.error('Payment error:', err.code, err.message);
 });
 
-checkout.on(SdkEvent.ThreeDSError, (err) => {
-  // Normalized ApiErrorPayload when available; fallback may be a raw object
-  console.error('3DS error:', err);
+checkout.on('expired', () => {
+  console.warn('Checkout session expired');
 });
 ```
 
-Payload notes:
-- `error`: the SDK forwards a normalized `ApiErrorPayload` when provided by Hosted Checkout.
-- `threeds_error`: forwards `payload.error` when available; otherwise the raw message data.
-- `threeds_*` non-error events: payload is forwarded as-is from Hosted Checkout (shape may evolve).
-
-
-### Core events (loaded, success, error, expired)
-
-Using enums:
+**Using SdkEvent enum (recommended for TypeScript):**
 
 ```ts
 import { PaypercutCheckout, SdkEvent } from '@paypercut/checkout-js';
@@ -303,48 +310,98 @@ checkout.on(SdkEvent.Success, (payload) => {
 });
 
 checkout.on(SdkEvent.Error, (err) => {
-  // err: ApiErrorPayload
   console.error('Payment error:', err.code, err.message);
 });
 
 checkout.on(SdkEvent.Expired, () => {
   console.warn('Checkout session expired');
 });
-```
-
-Or with string event names:
 
-```ts
-checkout.on('loaded', () => {});
-checkout.on('success', (payload) => {
-  console.log('Payment successful', payload.payment_method);
+// 3DS events
+checkout.on(SdkEvent.ThreeDSStarted, (ctx) => {
+  console.log('3DS challenge started');
 });
-checkout.on('error', (err) => {
-  console.error('Payment error', err);
+
+checkout.on(SdkEvent.ThreeDSComplete, (payload) => {
+  console.log('3DS completed');
 });
-checkout.on('expired', () => {});
-```
 
+checkout.on(SdkEvent.ThreeDSCanceled, (payload) => {
+  console.log('3DS canceled by user');
+});
 
-## Types
+checkout.on(SdkEvent.ThreeDSError, (err) => {
+  console.error('3DS error:', err);
+});
+```
 
-### Payload types
+### Success Payload
 
-#### PaymentSuccessPayload
+The `success` event returns a `PaymentSuccessPayload` with the payment method details:
 
 ```ts
-// Payload for `checkout.on('success', (payload))`
 type PaymentSuccessPayload = {
   payment_method: {
-    brand: string;   // e.g., 'visa', 'mastercard'
-    last4: string;
-    exp_month: number;
-    exp_year: number;
+    brand: string;      // e.g., 'visa', 'mastercard', 'amex'
+    last4: string;      // Last 4 digits of card number
+    exp_month: number;  // Expiration month (1-12)
+    exp_year: number;   // Expiration year (e.g., 2030)
   };
 };
 ```
 
-#### ApiErrorPayload (common shapes)
+**Example:**
+
+```ts
+checkout.on('success', (payload) => {
+  // payload:
+  // {
+  //   payment_method: {
+  //     brand: 'visa',
+  //     last4: '4242',
+  //     exp_month: 12,
+  //     exp_year: 2030
+  //   }
+  // }
+
+  console.log(`Paid with ${payload.payment_method.brand} ending in ${payload.payment_method.last4}`);
+  // Output: "Paid with visa ending in 4242"
+});
+```
+
+### Error Handling
+
+```ts
+checkout.on('error', (err) => {
+  switch (err.code) {
+    case 'card_validation_error':
+      // err.errors[] has field-level issues. Messages are localized.
+      break;
+    case 'card_declined':
+      // Optional err.decline_code and user-friendly err.message
+      break;
+    case 'threeds_error':
+    case 'threeds_authentication_failed':
+    case 'threeds_canceled':
+      // 3DS issue. Some servers use status_code 424 with a detailed message.
+      break;
+    default:
+      // Other terminal errors (e.g., authentication_failed, session_expired)
+      break;
+  }
+});
+```
+
+### Notes
+
+- `error`: the SDK forwards a normalized `ApiErrorPayload` when provided by Hosted Checkout.
+- `threeds_error`: forwards `payload.error` when available; otherwise the raw message data.
+- `threeds_*` non-error events: payload is forwarded as-is from Hosted Checkout (shape may evolve).
+
+
+## Types
+
+### ApiErrorPayload
 
 The SDK forwards the error payload provided by Hosted Checkout. Common shapes include:
 
@@ -505,15 +562,19 @@ Tip: Prefer subscribing with the SdkEvent enum for stronger typing.
 <body>
   <div id="checkout"></div>
 
-  <script src="https://cdn.jsdelivr.net/npm/@paypercut/checkout-js@1.0.10/dist/paypercut-checkout.iife.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/@paypercut/checkout-js@1.0.12/dist/paypercut-checkout.iife.min.js"></script>
   <script>
     const checkout = PaypercutCheckout({
       id: 'CHK_12345',
-      containerId: '#checkout'
+      containerId: '#checkout',
+      locale: 'en',
+      ui_mode: 'embedded',
+      wallet_options: ['apple_pay', 'google_pay']
     });
 
-    checkout.on('success', function() {
-      alert('Payment successful!');
+    checkout.on('success', function(payload) {
+      // payload.payment_method: { brand, last4, exp_month, exp_year }
+      alert('Payment successful with ' + payload.payment_method.brand + ' ending in ' + payload.payment_method.last4);
     });
 
     checkout.on('error', function(error) {
@@ -533,11 +594,17 @@ import { PaypercutCheckout } from '@paypercut/checkout-js';
 
 const checkout = PaypercutCheckout({
   id: 'CHK_12345',
-  containerId: '#checkout'
+  containerId: '#checkout',
+  locale: 'auto',
+  ui_mode: 'embedded',
+  wallet_options: ['apple_pay', 'google_pay'],
+  form_only: false
 });
 
-checkout.on('success', () => {
+checkout.on('success', (payload) => {
+  // payload.payment_method: { brand, last4, exp_month, exp_year }
   console.log('Payment successful');
+  console.log(`Paid with ${payload.payment_method.brand} **** ${payload.payment_method.last4}`);
   // Redirect to success page
   window.location.href = '/success';
 });
@@ -557,17 +624,29 @@ checkout.render();
 import { useEffect, useRef, useState } from 'react';
 import { PaypercutCheckout, CheckoutInstance } from '@paypercut/checkout-js';
 
+interface PaymentMethod {
+  brand: string;
+  last4: string;
+  exp_month: number;
+  exp_year: number;
+}
+
 export function CheckoutComponent({ checkoutId }: { checkoutId: string }) {
   const containerRef = useRef<HTMLDivElement>(null);
   const checkoutRef = useRef<CheckoutInstance | null>(null);
   const [status, setStatus] = useState<'idle' | 'loading' | 'success' | 'error'>('idle');
+  const [paymentMethod, setPaymentMethod] = useState<PaymentMethod | null>(null);
 
   useEffect(() => {
     if (!containerRef.current) return;
 
     const checkout = PaypercutCheckout({
       id: checkoutId,
-      containerId: containerRef.current
+      containerId: containerRef.current,
+      locale: 'auto',
+      ui_mode: 'embedded',
+      wallet_options: ['apple_pay', 'google_pay'],
+      form_only: false
     });
 
     checkout.on('loaded', () => {
@@ -575,9 +654,10 @@ export function CheckoutComponent({ checkoutId }: { checkoutId: string }) {
       console.log('Checkout loaded');
     });
 
-    checkout.on('success', () => {
+    checkout.on('success', (payload) => {
       setStatus('success');
-      console.log('Payment successful');
+      setPaymentMethod(payload.payment_method);
+      console.log('Payment successful:', payload.payment_method);
     });
 
     checkout.on('error', (error) => {
@@ -597,7 +677,9 @@ export function CheckoutComponent({ checkoutId }: { checkoutId: string }) {
     <div>
       <div ref={containerRef} style={{ width: '100%', height: '600px' }} />
       {status === 'loading' && <p>Processing payment...</p>}
-      {status === 'success' && <p>✅ Payment successful!</p>}
+      {status === 'success' && paymentMethod && (
+        <p>✅ Payment successful with {paymentMethod.brand} ending in {paymentMethod.last4}!</p>
+      )}
       {status === 'error' && <p>❌ Payment failed. Please try again.</p>}
     </div>
   );
@@ -701,6 +783,56 @@ export function ModalCheckout({ checkoutId, onClose }: { checkoutId: string; onC
 }
 ```
 
+## Container Styling
+
+The SDK automatically resizes the iframe to match the checkout content height. To ensure proper display, style your container with `max-width` and `max-height` constraints rather than fixed dimensions.
+
+### Recommended Container Styles
+
+```css
+.checkout-container {
+  /* Use max-width/max-height to constrain the container */
+  max-width: 450px;
+  max-height: 600px;
+  overflow: hidden;
+  overflow-y: auto;
+  scroll-behavior: smooth;
+}
+
+/* The mount point should be full width with no fixed height */
+#checkout-mount {
+  width: 100%;
+  /* Height is set dynamically by SDK via resize messages */
+  overflow: hidden;
+  position: relative;
+}
+```
+
+### Key Points
+
+1. **Avoid fixed `height` or `min-height`** on the container - the SDK will resize the iframe to fit the checkout content
+2. **Use `max-height`** if you want to limit the container size and enable scrolling for longer content
+3. **Use `max-width`** to constrain the container width (recommended: 375px–450px for optimal checkout display)
+4. **Set `overflow-y: auto`** on the container if using `max-height` to enable scrolling
+
+### Example HTML
+
+```html
+<div class="checkout-container">
+  <div id="checkout-mount"></div>
+</div>
+```
+
+```javascript
+const checkout = PaypercutCheckout({
+  id: 'CHK_12345',
+  containerId: '#checkout-mount'
+});
+checkout.render();
+```
+
+---
+
 ## Security
 
 ### Origin Validation

package/dist/index.cjs

@@ -84,7 +84,7 @@ class Emitter {
  * Production configuration (for merchants)
  */
 const productionConfig = {
-    version: "1.0.10",
+    version: "1.0.12",
     defaultCheckoutOrigin: 'https://buy.paypercut.io',
     allowedOrigins: [
         'https://buy.paypercut.io',
@@ -274,6 +274,7 @@ exports.SdkEvent = void 0;
     SdkEvent["Success"] = "success";
     SdkEvent["Error"] = "error";
     SdkEvent["Expired"] = "expired";
+    SdkEvent["Resize"] = "resize";
     SdkEvent["ThreeDSComplete"] = "threeds_complete";
     SdkEvent["ThreeDSError"] = "threeds_error";
     SdkEvent["ThreeDSCanceled"] = "threeds_canceled";
@@ -323,11 +324,18 @@ class CheckoutImpl {
             });
         }
         // Add wallet_options parameters (repeated for each wallet)
-        if (this.options.wallet_options && this.options.wallet_options.length > 0) {
-            const validatedWallets = validateWalletOptions(this.options.wallet_options);
-            validatedWallets.forEach((wallet) => {
-                url.searchParams.append('wallet_options', wallet);
-            });
+        // If wallet_options is explicitly set (even as empty array), we need to pass it
+        if (this.options.wallet_options !== undefined) {
+            if (this.options.wallet_options.length === 0) {
+                // Explicit empty array means "no wallets" - pass null (coerced to "null" string)
+                url.searchParams.set('wallet_options', null);
+            }
+            else {
+                const validatedWallets = validateWalletOptions(this.options.wallet_options);
+                validatedWallets.forEach((wallet) => {
+                    url.searchParams.append('wallet_options', wallet);
+                });
+            }
         }
         if (this.options.appearance?.preset) {
             url.searchParams.set('preset', this.options.appearance.preset);
@@ -383,6 +391,10 @@ class CheckoutImpl {
             case 'CHECKOUT_EXPIRED':
                 this.emitter.emit(exports.SdkEvent.Expired);
                 break;
+            case 'CHECKOUT_RESIZE':
+                this.emitter.emit(exports.SdkEvent.Resize, data.height);
+                this.handleResize(data.height);
+                break;
             case 'THREEDS_START_FLOW':
                 this.show3DSModal(data);
                 this.emitter.emit(exports.SdkEvent.ThreeDSStarted);
@@ -475,6 +487,16 @@ class CheckoutImpl {
         const checkoutOrigin = getCheckoutOrigin(this.options.hostedCheckoutUrl);
         this.iframe.contentWindow.postMessage(message, checkoutOrigin);
     }
+    /**
+     * Handle CHECKOUT_RESIZE message - resize iframe to match content height
+     */
+    handleResize(height) {
+        if (!this.iframe || typeof height !== 'number' || height <= 0) {
+            return;
+        }
+        // Set iframe height to match content
+        this.iframe.style.height = `${height}px`;
+    }
     /**
      * Show 3DS modal with challenge/decoupled flow
      */