@paypercut/checkout-js 1.0.11 → 1.0.13

package/README.md

@@ -17,6 +17,8 @@ A lightweight, framework-agnostic JavaScript SDK for embedding Paypercut Checkou
 - [Quick Start](#quick-start)
 - [API Reference](#api-reference)
 - [Events](#events)
+- [Form Validation for Wallet Payments](#form-validation-for-wallet-payments)
+- [Types](#types)
 - [Usage Examples](#usage-examples)
   - [Vanilla JavaScript](#vanilla-javascript-cdn)
   - [TypeScript / ESM](#typescript--esm)
@@ -54,12 +56,12 @@ pnpm add @paypercut/checkout-js
 
 ```html
 <!-- jsDelivr (recommended with SRI) -->
-<script src="https://cdn.jsdelivr.net/npm/@paypercut/checkout-js@1.0.11/dist/paypercut-checkout.iife.min.js"
+<script src="https://cdn.jsdelivr.net/npm/@paypercut/checkout-js@1.0.13/dist/paypercut-checkout.iife.min.js"
         integrity="sha384-..."
         crossorigin="anonymous"></script>
 
 <!-- or UNPKG -->
-<script src="https://unpkg.com/@paypercut/checkout-js@1.0.11/dist/paypercut-checkout.iife.min.js"></script>
+<script src="https://unpkg.com/@paypercut/checkout-js@1.0.13/dist/paypercut-checkout.iife.min.js"></script>
 ```
 
 ---
@@ -118,12 +120,19 @@ 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'` |
+| `lang`           | `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 +141,55 @@ 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'
+  lang: '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,39 +255,125 @@ if (checkout.isMounted()) {
 
 ## Events
 
-Subscribe to events using the `on()` method:
+Subscribe to events using the `on()` method. You can use string event names or the `SdkEvent` enum.
+
+### Event Reference
+
+| 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` |
+
+### Usage Examples
+
+**Using string event names:**
+
+```ts
+const checkout = PaypercutCheckout({ id: 'CHK_12345', containerId: '#checkout' });
+
+checkout.on('loaded', () => {
+  console.log('Checkout loaded');
+});
+
+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('error', (err) => {
+  console.error('Payment error:', err.code, err.message);
+});
+
+checkout.on('expired', () => {
+  console.warn('Checkout session expired');
+});
+```
+
+**Using SdkEvent enum (recommended for TypeScript):**
+
+```ts
+import { PaypercutCheckout, SdkEvent } from '@paypercut/checkout-js';
+
+const checkout = PaypercutCheckout({ id: 'CHK_12345', containerId: '#checkout' });
+
+checkout.on(SdkEvent.Loaded, () => {
+  console.log('Checkout loaded');
+});
+
+checkout.on(SdkEvent.Success, (payload) => {
+  console.log('Payment successful', payload.payment_method);
+});
+
+checkout.on(SdkEvent.Error, (err) => {
+  console.error('Payment error:', err.code, err.message);
+});
+
+checkout.on(SdkEvent.Expired, () => {
+  console.warn('Checkout session expired');
+});
+
+// 3DS events
+checkout.on(SdkEvent.ThreeDSStarted, (ctx) => {
+  console.log('3DS challenge started');
+});
 
-| 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` |
+checkout.on(SdkEvent.ThreeDSComplete, (payload) => {
+  console.log('3DS completed');
+});
 
+checkout.on(SdkEvent.ThreeDSCanceled, (payload) => {
+  console.log('3DS canceled by user');
+});
+
+checkout.on(SdkEvent.ThreeDSError, (err) => {
+  console.error('3DS error:', err);
+});
+```
 
-#### Success payload example
+### Success Payload
+
+The `success` event returns a `PaymentSuccessPayload` with the payment method details:
+
+```ts
+type PaymentSuccessPayload = {
+  payment_method: {
+    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)
+  };
+};
+```
+
+**Example:**
 
 ```ts
 checkout.on('success', (payload) => {
-  // payload: PaymentSuccessPayload
-  // Example:
+  // payload:
   // {
   //   payment_method: {
   //     brand: 'visa',
   //     last4: '4242',
   //     exp_month: 12,
-  //     exp_year: 2030,
+  //     exp_year: 2030
   //   }
   // }
-  console.log('PM last4', payload.payment_method.last4);
+
+  console.log(`Paid with ${payload.payment_method.brand} ending in ${payload.payment_method.last4}`);
+  // Output: "Paid with visa ending in 4242"
 });
 ```
 
-#### Error payloads overview
+### Error Handling
 
 ```ts
 checkout.on('error', (err) => {
@@ -252,99 +396,185 @@ checkout.on('error', (err) => {
 });
 ```
 
-### 3DS Events (enum usage recommended)
+### Notes
 
-You can subscribe using string event names or the SdkEvent enum:
+- `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).
 
-```ts
-import { PaypercutCheckout, SdkEvent } from '@paypercut/checkout-js';
+---
 
-const checkout = PaypercutCheckout({ id: 'CHK_12345', containerId: '#checkout' });
+## Form Validation for Wallet Payments
 
-checkout.on(SdkEvent.ThreeDSStarted, (ctx) => {
-  // e.g., show your own UI indicator or log ctx
-});
+When using Apple Pay or Google Pay, you may need to validate your own form fields (e.g., email, shipping address) before the wallet payment sheet opens. The SDK provides a `form_validation` event and methods to control this flow.
 
-checkout.on(SdkEvent.ThreeDSComplete, (payload) => {
-  // 3DS completed successfully; Hosted Checkout will continue the flow
-});
+### How It Works
 
-checkout.on(SdkEvent.ThreeDSCanceled, (payload) => {
-  // User canceled the 3DS challenge
-});
+1. User clicks Apple Pay or Google Pay button in the checkout
+2. SDK emits `form_validation` event to your code
+3. You validate your form and call either:
+   - `completeFormValidation(wallet)` - allows wallet to proceed
+   - `failFormValidation(wallet, errors)` - blocks wallet, you show your own errors
+4. If validation passes, the wallet payment sheet opens
 
-checkout.on(SdkEvent.ThreeDSError, (err) => {
-  // Normalized ApiErrorPayload when available; fallback may be a raw object
-  console.error('3DS error:', err);
-});
-```
+### Event: `form_validation`
 
-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).
+| Property | Type | Description |
+|----------|------|-------------|
+| `checkoutId` | `string` | The checkout session ID |
+| `wallet` | `'apple_pay' \| 'google_pay'` | Which wallet button was clicked |
 
+### Methods
 
-### Core events (loaded, success, error, expired)
+#### `completeFormValidation(wallet)`
 
-Using enums:
+Call this when your form is valid. The wallet payment sheet will open.
 
-```ts
-import { PaypercutCheckout, SdkEvent } from '@paypercut/checkout-js';
+```typescript
+checkout.completeFormValidation('google_pay');
+```
 
-const checkout = PaypercutCheckout({ id: 'CHK_12345', containerId: '#checkout' });
+#### `failFormValidation(wallet, errors?)`
 
-checkout.on(SdkEvent.Loaded, () => {
-  console.log('Checkout loaded');
-});
+Call this when your form has errors. The wallet will not open, and you should display your own error messages.
 
-checkout.on(SdkEvent.Success, (payload) => {
-  console.log('Payment successful', payload.payment_method);
-});
+```typescript
+checkout.failFormValidation('apple_pay', [
+  { code: 'invalid_email', message: 'Please enter a valid email address' },
+  { code: 'missing_address', message: 'Shipping address is required' }
+]);
+```
 
-checkout.on(SdkEvent.Error, (err) => {
-  // err: ApiErrorPayload
-  console.error('Payment error:', err.code, err.message);
+### Basic Example
+
+```typescript
+import { PaypercutCheckout, SdkEvent } from '@paypercut/checkout-js';
+
+const checkout = PaypercutCheckout({
+  id: 'CHK_12345',
+  containerId: '#checkout',
+  wallet_options: ['apple_pay', 'google_pay']
 });
 
-checkout.on(SdkEvent.Expired, () => {
-  console.warn('Checkout session expired');
+// Handle form validation for wallet payments
+checkout.on(SdkEvent.FormValidation, ({ wallet, checkoutId }) => {
+  // Validate your own form fields
+  const email = document.getElementById('email').value;
+  const isEmailValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+
+  if (isEmailValid) {
+    // Form is valid - allow wallet to proceed
+    checkout.completeFormValidation(wallet);
+  } else {
+    // Form has errors - block wallet and show your errors
+    document.getElementById('email-error').textContent = 'Please enter a valid email';
+    checkout.failFormValidation(wallet, [
+      { code: 'invalid_email', message: 'Please enter a valid email' }
+    ]);
+  }
 });
+
+checkout.render();
 ```
 
-Or with string event names:
+### React Example
 
-```ts
-checkout.on('loaded', () => {});
-checkout.on('success', (payload) => {
-  console.log('Payment successful', payload.payment_method);
-});
-checkout.on('error', (err) => {
-  console.error('Payment error', err);
-});
-checkout.on('expired', () => {});
+```tsx
+import { useEffect, useRef, useState } from 'react';
+import { PaypercutCheckout, CheckoutInstance, SdkEvent } from '@paypercut/checkout-js';
+
+export function CheckoutWithForm({ checkoutId }: { checkoutId: string }) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const checkoutRef = useRef<CheckoutInstance | null>(null);
+  const [email, setEmail] = useState('');
+  const [emailError, setEmailError] = useState('');
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    const checkout = PaypercutCheckout({
+      id: checkoutId,
+      containerId: containerRef.current,
+      wallet_options: ['apple_pay', 'google_pay']
+    });
+
+    // Handle wallet form validation
+    checkout.on(SdkEvent.FormValidation, ({ wallet }) => {
+      const isValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+
+      if (isValid) {
+        setEmailError('');
+        checkout.completeFormValidation(wallet);
+      } else {
+        setEmailError('Please enter a valid email address');
+        checkout.failFormValidation(wallet, [
+          { code: 'invalid_email', message: 'Invalid email' }
+        ]);
+      }
+    });
+
+    checkout.on('success', (payload) => {
+      console.log('Payment successful:', payload.payment_method);
+    });
+
+    checkout.render();
+    checkoutRef.current = checkout;
+
+    return () => checkout.destroy();
+  }, [checkoutId, email]);
+
+  return (
+    <div>
+      {/* Your custom form fields */}
+      <div>
+        <label htmlFor="email">Email</label>
+        <input
+          id="email"
+          type="email"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          placeholder="your@email.com"
+        />
+        {emailError && <span style={{ color: 'red' }}>{emailError}</span>}
+      </div>
+
+      {/* Checkout iframe */}
+      <div ref={containerRef} />
+    </div>
+  );
+}
 ```
 
+### Timeout Behavior
 
-## Types
+If you don't respond to the `form_validation` event within 10 seconds, the SDK will:
+1. Emit an `error` event with code `form_validation_timeout`
+2. Block the wallet payment from starting
 
-### Payload types
+This ensures the checkout doesn't hang indefinitely if the handler is not implemented.
 
-#### PaymentSuccessPayload
+### When to Use
 
-```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;
-  };
-};
+Use form validation when you have:
+- Custom email/phone fields outside the checkout iframe
+- Shipping address forms that must be filled before payment
+- Terms & conditions checkboxes that must be accepted
+- Any other merchant-side validation requirements
+
+If you don't need to validate anything, you can simply auto-approve:
+
+```typescript
+checkout.on('form_validation', ({ wallet }) => {
+  // No validation needed - always allow wallet to proceed
+  checkout.completeFormValidation(wallet);
+});
 ```
 
-#### ApiErrorPayload (common shapes)
+---
+
+## Types
+
+### ApiErrorPayload
 
 The SDK forwards the error payload provided by Hosted Checkout. Common shapes include:
 
@@ -505,15 +735,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.11/dist/paypercut-checkout.iife.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/@paypercut/checkout-js@1.0.13/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 +767,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 +797,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 +827,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 +850,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>
   );