@paypercut/checkout-js 1.2.12 → 1.2.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -12,6 +12,9 @@ A lightweight, framework-agnostic JavaScript SDK for embedding Paypercut Checkou
12
12
  ## Table of Contents
13
13
 
14
14
  - [Installation](#installation)
15
+ - [Elements](#elements)
16
+ - [Payment Element](#payment-element)
17
+ - [Express Checkout Element](#express-checkout-element)
15
18
  - [Quick Start — Embedded Checkout](#quick-start)
16
19
  - [API Reference — Embedded Checkout](#api-reference)
17
20
  - [**Customisation**](#customisation)
@@ -67,16 +70,161 @@ pnpm add @paypercut/checkout-js
67
70
 
68
71
  ```html
69
72
  <!-- jsDelivr (recommended with SRI) -->
70
- <script src="https://cdn.jsdelivr.net/npm/@paypercut/checkout-js@1.2.12/dist/paypercut-checkout.iife.min.js"
71
- integrity="sha384-..."
72
- crossorigin="anonymous"></script>
73
+ <script
74
+ src="https://cdn.jsdelivr.net/npm/@paypercut/checkout-js@1.2.19/dist/paypercut-checkout.iife.min.js"
75
+ integrity="sha384-..."
76
+ crossorigin="anonymous"
77
+ ></script>
73
78
 
74
79
  <!-- or UNPKG -->
75
- <script src="https://unpkg.com/@paypercut/checkout-js@1.2.12/dist/paypercut-checkout.iife.min.js"></script>
80
+ <script src="https://unpkg.com/@paypercut/checkout-js@1.2.19/dist/paypercut-checkout.iife.min.js"></script>
76
81
  ```
77
82
 
78
83
  ---
79
84
 
85
+ ## Elements
86
+
87
+ The Elements API is the composable integration surface for merchant-owned payment
88
+ pages. One `elements()` object owns one shared controller and configuration
89
+ session. Every Element created from it is an independently mounted, remotely
90
+ hosted component; merchant and platform code decide where those components are
91
+ placed.
92
+
93
+ ```ts
94
+ import { Paypercut } from '@paypercut/checkout-js';
95
+
96
+ const paypercut = Paypercut({ publishableKey: 'pk_...' });
97
+ const elements = paypercut.elements({
98
+ mode: 'payment',
99
+ amount: 4999,
100
+ currency: 'USD',
101
+ });
102
+ ```
103
+
104
+ Creating the group does not create a Checkout Session or Payment Intent. The
105
+ merchant server remains authoritative for the final amount, currency, order, and
106
+ payment confirmation.
107
+
108
+ ### Payment Element
109
+
110
+ ```ts
111
+ const payment = elements.create('payment');
112
+ payment.mount('#payment-element');
113
+
114
+ const paymentMethod = await payment.submit();
115
+ // Send paymentMethod.id to your server. Do not confirm a payment from browser input.
116
+ ```
117
+
118
+ ### Express Checkout Element
119
+
120
+ The Express Checkout Element is one component. It checks wallet availability and
121
+ renders the available Apple Pay and Google Pay buttons inside its hosted frame.
122
+ It is not one Paypercut iframe per wallet and it is not a WooCommerce-specific
123
+ widget.
124
+
125
+ ```ts
126
+ const expressCheckout = elements.create('expressCheckout', {
127
+ paymentMethods: {
128
+ applePay: 'auto',
129
+ googlePay: 'auto',
130
+ },
131
+ layout: {
132
+ maxColumns: 2,
133
+ maxRows: 1,
134
+ },
135
+ buttonHeight: 48,
136
+ emailRequired: true,
137
+ billingAddressRequired: true,
138
+ });
139
+
140
+ expressCheckout.on('ready', ({ availablePaymentMethods }) => {
141
+ // Hide your placement if every value is false.
142
+ document
143
+ .querySelector('#express-checkout')
144
+ ?.toggleAttribute(
145
+ 'hidden',
146
+ !availablePaymentMethods.applePay && !availablePaymentMethods.googlePay,
147
+ );
148
+ });
149
+
150
+ expressCheckout.on('click', async (event) => {
151
+ // Recalculate the cart presented by your UI before the Element accepts and
152
+ // tokenizes the wallet result. Settle the event promptly (within one second).
153
+ // A provider's native sheet may begin opening on the original user gesture.
154
+ const cart = await readCurrentCart();
155
+ if (!cart.isValid) {
156
+ event.reject();
157
+ return;
158
+ }
159
+ elements.update({ amount: cart.amount });
160
+ event.resolve({
161
+ lineItems: cart.lineItems,
162
+ shippingAddressRequired: cart.needsShipping,
163
+ shippingRates: cart.needsShipping ? cart.shippingRates : undefined,
164
+ });
165
+ });
166
+
167
+ expressCheckout.on('shippingaddresschange', async (event) => {
168
+ try {
169
+ const update = await quoteShipping(event.address);
170
+ event.resolve(update); // { amount, lineItems, shippingRates }
171
+ } catch {
172
+ event.reject();
173
+ }
174
+ });
175
+
176
+ expressCheckout.on('shippingratechange', async (event) => {
177
+ try {
178
+ const update = await selectShippingRate(event.shippingRate.id);
179
+ event.resolve(update); // { amount, lineItems, shippingRates? }
180
+ } catch {
181
+ event.reject();
182
+ }
183
+ });
184
+
185
+ expressCheckout.on('confirm', async (event) => {
186
+ try {
187
+ // Send the opaque Payment Method ID and final provider-neutral contact data
188
+ // to your server. The server remains authoritative for the order and payment.
189
+ await submitPaymentMethodToYourServer({
190
+ wallet: event.wallet,
191
+ payment_method: event.paymentMethod.id,
192
+ billing_details: event.billingDetails,
193
+ shipping_address: event.shippingAddress,
194
+ shipping_rate: event.shippingRate,
195
+ });
196
+ event.complete();
197
+ } catch (error) {
198
+ event.paymentFailed({
199
+ code: 'merchant_checkout_failed',
200
+ message: error instanceof Error ? error.message : 'Payment failed.',
201
+ });
202
+ }
203
+ });
204
+
205
+ expressCheckout.on('error', ({ code, message, recoverable }) => {
206
+ reportPaymentError({ code, message, recoverable });
207
+ });
208
+
209
+ expressCheckout.mount('#express-checkout');
210
+ ```
211
+
212
+ The component owns wallet SDK loading, capability detection, provider button
213
+ rendering, loading states, resizing, tokenization, and the shared provider-verified
214
+ 3DS lifecycle. The merchant adapter owns product/cart placement, shipping quotes,
215
+ provider-neutral address conversion, and server-side order/payment confirmation.
216
+ The native wallet stays pending until the adapter calls `complete()` or
217
+ `paymentFailed()`.
218
+
219
+ Shipping is opt-in. Set `shippingAddressRequired` and provide `shippingRates` only
220
+ for physical fulfillment. When enabled, the Element emits address and rate change
221
+ events and requires each event to be resolved or rejected promptly. The final
222
+ `confirm` event returns the unredacted `shippingAddress` and selected
223
+ `shippingRate`. Integrations without shipping (for example, an EV charging
224
+ payment) should leave those options unset and receive no shipping callbacks.
225
+
226
+ ---
227
+
80
228
  ## Quick Start
81
229
 
82
230
  This returns a checkout session ID like `01KB23M9EC960C50G3AH14FTTT`.
@@ -90,8 +238,8 @@ import { PaypercutCheckout } from '@paypercut/checkout-js';
90
238
 
91
239
  // Initialize the checkout
92
240
  const checkout = PaypercutCheckout({
93
- id: '01KB23M9EC960C50G3AH14FTTT', // Your checkout session ID from step 1
94
- containerId: '#checkout' // CSS selector or HTMLElement
241
+ id: '01KB23M9EC960C50G3AH14FTTT', // Your checkout session ID from step 1
242
+ containerId: '#checkout', // CSS selector or HTMLElement
95
243
  });
96
244
 
97
245
  // Listen for payment events
@@ -118,9 +266,10 @@ That's it! The checkout is now embedded in your page.
118
266
 
119
267
  The SDK supports one display mode:
120
268
 
121
- | Mode | When to Use | Configuration |
122
- |------|-------------|---------------|
269
+ | Mode | When to Use | Configuration |
270
+ | ------------ | ------------------------------------ | --------------------- |
123
271
  | **Embedded** | Checkout is part of your page layout | Provide `containerId` |
272
+
124
273
  ---
125
274
 
126
275
  ## API Reference
@@ -131,18 +280,18 @@ Creates a new checkout instance.
131
280
 
132
281
  #### Options
133
282
 
134
- | Option | Type | Required | Default | Description |
135
- |------------------|------|----------|---------|----------------------------------------------------------------------------------------------------------------------------|
136
- | `id` | `string` | Yes | — | Checkout session identifier (e.g., `01KB23M9EC960C50G3AH14FTTT`) |
137
- | `containerId` | `string \| HTMLElement` | Yes | — | CSS selector or element where iframe mounts |
138
- | `locale` | `string` | No | `'auto'` | Locale for checkout UI. Options: `'auto'`, `'en'`, `'en-GB'`, `'bg'`, `'bg-BG'` |
139
- | `lang` | `string` | No | `'auto'` | Locale for checkout UI. Options: `'auto'`, `'en'`, `'en-GB'`, `'bg'`, `'bg-BG'` |
140
- | `ui_mode` | `'hosted' \| 'embedded'` | No | `'embedded'` | UI mode for checkout display |
141
- | `wallet_options` | `string[]` | No | `['apple_pay', 'google_pay']` | Digital wallet options. Pass `[]` to disable all wallets |
142
- | `form_only` | `boolean` | No | `false` | Show only payment form (no Pay Now button - use external button with `submit()`) |
143
- | `validate_form` | `boolean` | No | `false` | This indicates that Google Pay/Apple Pay flow to proceed you need to confirm form validation. For EMBEDDED checkouts only) |
144
- | `appearance` | `object` | No | `undefined` | Appearance configuration for the checkout UI |
145
- | `appearance.preset` | `'modal' \| 'inline'` | No | `undefined` | Controls checkout layout preset. `'modal'` shows the order summary (TotalCard) and header inside the iframe — use when rendering in a modal/dialog. `'inline'` hides the TotalCard — use when the merchant renders their own order summary outside the checkout. |
283
+ | Option | Type | Required | Default | Description |
284
+ | ------------------- | ------------------------ | -------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
285
+ | `id` | `string` | Yes | — | Checkout session identifier (e.g., `01KB23M9EC960C50G3AH14FTTT`) |
286
+ | `containerId` | `string \| HTMLElement` | Yes | — | CSS selector or element where iframe mounts |
287
+ | `locale` | `string` | No | `'auto'` | Locale for checkout UI. Options: `'auto'`, `'en'`, `'en-GB'`, `'bg'`, `'bg-BG'` |
288
+ | `lang` | `string` | No | `'auto'` | Locale for checkout UI. Options: `'auto'`, `'en'`, `'en-GB'`, `'bg'`, `'bg-BG'` |
289
+ | `ui_mode` | `'hosted' \| 'embedded'` | No | `'embedded'` | UI mode for checkout display |
290
+ | `wallet_options` | `string[]` | No | `['apple_pay', 'google_pay']` | Digital wallet options. Pass `[]` to disable all wallets |
291
+ | `form_only` | `boolean` | No | `false` | Show only payment form (no Pay Now button - use external button with `submit()`) |
292
+ | `validate_form` | `boolean` | No | `false` | This indicates that Google Pay/Apple Pay flow to proceed you need to confirm form validation. For EMBEDDED checkouts only) |
293
+ | `appearance` | `object` | No | `undefined` | Appearance configuration for the checkout UI |
294
+ | `appearance.preset` | `'modal' \| 'inline'` | No | `undefined` | Controls checkout layout preset. `'modal'` shows the order summary (TotalCard) and header inside the iframe — use when rendering in a modal/dialog. `'inline'` hides the TotalCard — use when the merchant renders their own order summary outside the checkout. |
146
295
 
147
296
  #### Examples
148
297
 
@@ -151,7 +300,7 @@ Creates a new checkout instance.
151
300
  ```typescript
152
301
  const checkout = PaypercutCheckout({
153
302
  id: '01KB23M9EC960C50G3AH14FTTT',
154
- containerId: '#checkout-container'
303
+ containerId: '#checkout-container',
155
304
  });
156
305
  ```
157
306
 
@@ -161,14 +310,14 @@ const checkout = PaypercutCheckout({
161
310
  const checkout = PaypercutCheckout({
162
311
  id: '01KB23M9EC960C50G3AH14FTTT',
163
312
  containerId: '#checkout-container',
164
- locale: 'en', // 'auto' | 'en' | 'en-GB' | 'bg' | 'bg-BG'
165
- lang: 'en', // 'auto' | 'en' | 'en-GB' | 'bg' | 'bg-BG'
166
- ui_mode: 'embedded', // 'hosted' | 'embedded'
313
+ locale: 'en', // 'auto' | 'en' | 'en-GB' | 'bg' | 'bg-BG'
314
+ lang: 'en', // 'auto' | 'en' | 'en-GB' | 'bg' | 'bg-BG'
315
+ ui_mode: 'embedded', // 'hosted' | 'embedded'
167
316
  wallet_options: ['apple_pay', 'google_pay'], // Can be empty array [] or contain one/both options
168
- form_only: false, // Set true to hide Pay Now button (use external button),
169
- validate_form: true, // Set true to require form validation before wallet payment
317
+ form_only: false, // Set true to hide Pay Now button (use external button),
318
+ validate_form: true, // Set true to require form validation before wallet payment
170
319
  appearance: {
171
- preset: 'modal', // 'modal' | 'inline' — 'modal' shows TotalCard + header, 'inline' hides them
320
+ preset: 'modal', // 'modal' | 'inline' — 'modal' shows TotalCard + header, 'inline' hides them
172
321
  },
173
322
  });
174
323
  ```
@@ -179,7 +328,7 @@ const checkout = PaypercutCheckout({
179
328
  const checkout = PaypercutCheckout({
180
329
  id: '01KB23M9EC960C50G3AH14FTTT',
181
330
  containerId: '#checkout-container',
182
- wallet_options: [] // No Apple Pay or Google Pay buttons
331
+ wallet_options: [], // No Apple Pay or Google Pay buttons
183
332
  });
184
333
  ```
185
334
 
@@ -189,7 +338,7 @@ const checkout = PaypercutCheckout({
189
338
  const checkout = PaypercutCheckout({
190
339
  id: '01KB23M9EC960C50G3AH14FTTT',
191
340
  containerId: '#checkout-container',
192
- wallet_options: ['apple_pay'] // Only Apple Pay, no Google Pay
341
+ wallet_options: ['apple_pay'], // Only Apple Pay, no Google Pay
193
342
  });
194
343
  ```
195
344
 
@@ -199,7 +348,7 @@ const checkout = PaypercutCheckout({
199
348
  const checkout = PaypercutCheckout({
200
349
  id: '01KB23M9EC960C50G3AH14FTTT',
201
350
  containerId: '#checkout-container',
202
- form_only: true // No Pay Now button inside checkout
351
+ form_only: true, // No Pay Now button inside checkout
203
352
  });
204
353
 
205
354
  // Use your own button to trigger payment
@@ -277,10 +426,10 @@ if (checkout.isMounted()) {
277
426
 
278
427
  Paypercut Checkout supports full visual customisation — you can match your brand colors, typography, corner radius, and even inject your logo. Customisation works in two complementary ways:
279
428
 
280
- | Approach | When it applies | How |
281
- |---|---|---|
282
- | `appearance` init option | At iframe creation (zero flash) | Pass in `PaypercutCheckout({ appearance: { … } })` |
283
- | `checkout.updateAppearance()` | After mount (dynamic, e.g. dark-mode toggle) | Call at any time post-`render()` |
429
+ | Approach | When it applies | How |
430
+ | ----------------------------- | -------------------------------------------- | -------------------------------------------------- |
431
+ | `appearance` init option | At iframe creation (zero flash) | Pass in `PaypercutCheckout({ appearance: { … } })` |
432
+ | `checkout.updateAppearance()` | After mount (dynamic, e.g. dark-mode toggle) | Call at any time post-`render()` |
284
433
 
285
434
  ---
286
435
 
@@ -293,13 +442,13 @@ const checkout = PaypercutCheckout({
293
442
  id: 'CHK_xxx',
294
443
  containerId: '#checkout',
295
444
  appearance: {
296
- theme: 'dark', // 'light' | 'dark'
297
- preset: 'modal', // 'inline' | 'modal'
445
+ theme: 'dark', // 'light' | 'dark'
446
+ preset: 'modal', // 'inline' | 'modal'
298
447
  variables: {
299
- brandColor: '#ff5500', // CTA button background
300
- fontFamily: 'Inter, sans-serif',
448
+ brandColor: '#ff5500', // CTA button background
449
+ fontFamily: 'Inter, sans-serif',
301
450
  borderRadius: '12px',
302
- logoUrl: 'https://cdn.example.com/logo.png',
451
+ logoUrl: 'https://cdn.example.com/logo.png',
303
452
  },
304
453
  },
305
454
  });
@@ -309,10 +458,10 @@ checkout.render();
309
458
 
310
459
  **`preset`**
311
460
 
312
- | Value | Effect |
313
- |---|---|
314
- | `'inline'` | Compact form without the order summary card |
315
- | `'modal'` | Full form with order summary card + logo rendered at the top |
461
+ | Value | Effect |
462
+ | ---------- | ------------------------------------------------------------ |
463
+ | `'inline'` | Compact form without the order summary card |
464
+ | `'modal'` | Full form with order summary card + logo rendered at the top |
316
465
 
317
466
  ---
318
467
 
@@ -348,12 +497,12 @@ Updates are **merged** — you only need to pass the fields you want to change.
348
497
 
349
498
  ### `AppearanceVariables` reference
350
499
 
351
- | Field | Type | Description |
352
- |---|---|---|
353
- | `brandColor` | `` `#${string}` `` | Background color of the primary CTA (Pay Now) button. Must be a hex value, e.g. `'#ff5500'`. |
354
- | `fontFamily` | `string` | CSS font-family value. Applied globally inside the checkout. E.g. `'Inter, sans-serif'`. |
355
- | `borderRadius` | `string` | CSS length value for element corner radii. Accepts `px`, `rem`, or `em`. E.g. `'8px'`. |
356
- | `logoUrl` | `string` (https URL) | Your logo shown above the checkout header when `preset: 'modal'`. Must be `https://`. |
500
+ | Field | Type | Description |
501
+ | -------------- | -------------------- | -------------------------------------------------------------------------------------------- |
502
+ | `brandColor` | `` `#${string}` `` | Background color of the primary CTA (Pay Now) button. Must be a hex value, e.g. `'#ff5500'`. |
503
+ | `fontFamily` | `string` | CSS font-family value. Applied globally inside the checkout. E.g. `'Inter, sans-serif'`. |
504
+ | `borderRadius` | `string` | CSS length value for element corner radii. Accepts `px`, `rem`, or `em`. E.g. `'8px'`. |
505
+ | `logoUrl` | `string` (https URL) | Your logo shown above the checkout header when `preset: 'modal'`. Must be `https://`. |
357
506
 
358
507
  `brandColor` must be a 3- or 6-digit hex value (e.g. `'#fff'` or `'#ffffff'`). Invalid values log a warning and are silently dropped — the existing color is preserved.
359
508
 
@@ -384,17 +533,17 @@ Subscribe to events using the `on()` method. You can use string event names or t
384
533
 
385
534
  ### Event Reference
386
535
 
387
- | Event | Enum | Description | Payload |
388
- |-------|------|-------------|---------|
389
- | `loaded` | `SdkEvent.Loaded` | Checkout iframe has finished loading | `void` |
390
- | `processing` | `SdkEvent.Processing` | Payment processing has started inside the hosted checkout | `{ checkoutId: string }` |
391
- | `success` | `SdkEvent.Success` | Payment completed successfully | `PaymentSuccessPayload` |
392
- | `error` | `SdkEvent.Error` | Terminal failure (tokenize, confirm, or 3DS) | `ApiErrorPayload` |
393
- | `expired` | `SdkEvent.Expired` | Checkout session expired | `void` |
394
- | `threeds_started` | `SdkEvent.ThreeDSStarted` | 3DS challenge flow started | `object` |
395
- | `threeds_complete` | `SdkEvent.ThreeDSComplete` | 3DS challenge completed | `object` |
396
- | `threeds_canceled` | `SdkEvent.ThreeDSCanceled` | 3DS challenge canceled by user | `object` |
397
- | `threeds_error` | `SdkEvent.ThreeDSError` | 3DS challenge error | `ApiErrorPayload` or `object` |
536
+ | Event | Enum | Description | Payload |
537
+ | ------------------ | -------------------------- | --------------------------------------------------------- | ----------------------------- |
538
+ | `loaded` | `SdkEvent.Loaded` | Checkout iframe has finished loading | `void` |
539
+ | `processing` | `SdkEvent.Processing` | Payment processing has started inside the hosted checkout | `{ checkoutId: string }` |
540
+ | `success` | `SdkEvent.Success` | Payment completed successfully | `PaymentSuccessPayload` |
541
+ | `error` | `SdkEvent.Error` | Terminal failure (tokenize, confirm, or 3DS) | `ApiErrorPayload` |
542
+ | `expired` | `SdkEvent.Expired` | Checkout session expired | `void` |
543
+ | `threeds_started` | `SdkEvent.ThreeDSStarted` | 3DS challenge flow started | `object` |
544
+ | `threeds_complete` | `SdkEvent.ThreeDSComplete` | 3DS challenge completed | `object` |
545
+ | `threeds_canceled` | `SdkEvent.ThreeDSCanceled` | 3DS challenge canceled by user | `object` |
546
+ | `threeds_error` | `SdkEvent.ThreeDSError` | 3DS challenge error | `ApiErrorPayload` or `object` |
398
547
 
399
548
  ### Usage Examples
400
549
 
@@ -480,10 +629,10 @@ The `success` event returns a `PaymentSuccessPayload` with the payment method de
480
629
  ```ts
481
630
  type PaymentSuccessPayload = {
482
631
  payment_method: {
483
- brand: string; // e.g., 'visa', 'mastercard', 'amex'
484
- last4: string; // Last 4 digits of card number
485
- exp_month: number; // Expiration month (1-12)
486
- exp_year: number; // Expiration year (e.g., 2030)
632
+ brand: string; // e.g., 'visa', 'mastercard', 'amex'
633
+ last4: string; // Last 4 digits of card number
634
+ exp_month: number; // Expiration month (1-12)
635
+ exp_year: number; // Expiration year (e.g., 2030)
487
636
  };
488
637
  };
489
638
  ```
@@ -502,7 +651,9 @@ checkout.on('success', (payload) => {
502
651
  // }
503
652
  // }
504
653
 
505
- console.log(`Paid with ${payload.payment_method.brand} ending in ${payload.payment_method.last4}`);
654
+ console.log(
655
+ `Paid with ${payload.payment_method.brand} ending in ${payload.payment_method.last4}`,
656
+ );
506
657
  // Output: "Paid with visa ending in 4242"
507
658
  });
508
659
  ```
@@ -541,7 +692,6 @@ checkout.on('error', (err) => {
541
692
 
542
693
  ## Form Validation for Wallet Payments
543
694
 
544
-
545
695
  ### How It Works
546
696
 
547
697
  1. User clicks Apple Pay or Google Pay button in the checkout
@@ -553,10 +703,10 @@ checkout.on('error', (err) => {
553
703
 
554
704
  ### Event: `form_validation`
555
705
 
556
- | Property | Type | Description |
557
- |----------|------|-------------|
558
- | `checkoutId` | `string` | The checkout session ID |
559
- | `wallet` | `'apple_pay' \| 'google_pay'` | Which wallet button was clicked |
706
+ | Property | Type | Description |
707
+ | ------------ | ----------------------------- | ------------------------------- |
708
+ | `checkoutId` | `string` | The checkout session ID |
709
+ | `wallet` | `'apple_pay' \| 'google_pay'` | Which wallet button was clicked |
560
710
 
561
711
  ### Methods
562
712
 
@@ -575,7 +725,7 @@ Call this when your form has errors. The wallet will not open, and you should di
575
725
  ```typescript
576
726
  checkout.failFormValidation('apple_pay', [
577
727
  { code: 'invalid_email', message: 'Please enter a valid email address' },
578
- { code: 'missing_address', message: 'Shipping address is required' }
728
+ { code: 'missing_address', message: 'Shipping address is required' },
579
729
  ]);
580
730
  ```
581
731
 
@@ -587,7 +737,7 @@ import { PaypercutCheckout, SdkEvent } from '@paypercut/checkout-js';
587
737
  const checkout = PaypercutCheckout({
588
738
  id: '01KB23M9EC960C50G3AH14FTTT',
589
739
  containerId: '#checkout',
590
- wallet_options: ['apple_pay', 'google_pay']
740
+ wallet_options: ['apple_pay', 'google_pay'],
591
741
  });
592
742
 
593
743
  // Handle form validation for wallet payments
@@ -603,7 +753,7 @@ checkout.on(SdkEvent.FormValidation, ({ wallet, checkoutId }) => {
603
753
  // Form has errors - block wallet and show your errors
604
754
  document.getElementById('email-error').textContent = 'Please enter a valid email';
605
755
  checkout.failFormValidation(wallet, [
606
- { code: 'invalid_email', message: 'Please enter a valid email' }
756
+ { code: 'invalid_email', message: 'Please enter a valid email' },
607
757
  ]);
608
758
  }
609
759
  });
@@ -631,7 +781,7 @@ export function CheckoutWithForm({ checkoutId }: { checkoutId: string }) {
631
781
  containerId: containerRef.current,
632
782
  ui_mode: 'embedded',
633
783
  wallet_options: ['apple_pay', 'google_pay'],
634
- validate_form: true
784
+ validate_form: true,
635
785
  });
636
786
 
637
787
  // Handle wallet form validation
@@ -643,9 +793,7 @@ export function CheckoutWithForm({ checkoutId }: { checkoutId: string }) {
643
793
  checkout.completeFormValidation(wallet);
644
794
  } else {
645
795
  setEmailError('Please enter a valid email address');
646
- checkout.failFormValidation(wallet, [
647
- { code: 'invalid_email', message: 'Invalid email' }
648
- ]);
796
+ checkout.failFormValidation(wallet, [{ code: 'invalid_email', message: 'Invalid email' }]);
649
797
  }
650
798
  });
651
799
 
@@ -663,13 +811,13 @@ export function CheckoutWithForm({ checkoutId }: { checkoutId: string }) {
663
811
  <div>
664
812
  {/* Your custom form fields */}
665
813
  <div>
666
- <label htmlFor="email">Email</label>
814
+ <label htmlFor='email'>Email</label>
667
815
  <input
668
- id="email"
669
- type="email"
816
+ id='email'
817
+ type='email'
670
818
  value={email}
671
819
  onChange={(e) => setEmail(e.target.value)}
672
- placeholder="your@email.com"
820
+ placeholder='your@email.com'
673
821
  />
674
822
  {emailError && <span style={{ color: 'red' }}>{emailError}</span>}
675
823
  </div>
@@ -684,6 +832,7 @@ export function CheckoutWithForm({ checkoutId }: { checkoutId: string }) {
684
832
  ### Timeout Behavior
685
833
 
686
834
  If you don't respond to the `form_validation` event within 10 seconds, the SDK will:
835
+
687
836
  1. Emit an `error` event with code `form_validation_timeout`
688
837
  2. Block the wallet payment from starting
689
838
 
@@ -692,6 +841,7 @@ This ensures the checkout doesn't hang indefinitely if the handler is not implem
692
841
  ### When to Use
693
842
 
694
843
  Use form validation when you have:
844
+
695
845
  - Custom email/phone fields outside the checkout iframe
696
846
  - Shipping address forms that must be filled before payment
697
847
  - Terms & conditions checkboxes that must be accepted
@@ -708,6 +858,53 @@ checkout.on('form_validation', ({ wallet }) => {
708
858
 
709
859
  ---
710
860
 
861
+ ## Paypercut Elements errors
862
+
863
+ `PaymentElement.submit()` and the Element's `error` event expose a stable
864
+ machine-readable `code` and a `recoverable` flag.
865
+ The accompanying `message` is diagnostic English text. Customer-facing copy
866
+ should be owned and localized by the merchant integration by mapping `code` to
867
+ its own translated message.
868
+
869
+ ```ts
870
+ try {
871
+ const paymentMethod = await paymentElement.submit();
872
+ await sendPaymentMethodToYourServer(paymentMethod);
873
+ } catch (error) {
874
+ const elementsError = error as PaymentElementSubmitError;
875
+ showLocalizedPaymentError(elementsError.code);
876
+
877
+ if (!elementsError.recoverable) {
878
+ disableThisPaymentMethod();
879
+ }
880
+ }
881
+ ```
882
+
883
+ The public `PaymentElementErrorCode` type contains the known codes below and an
884
+ open string member. This lets a newer hosted component introduce a safe code
885
+ without forcing the merchant to upgrade Paypercut.js first. Integrations must
886
+ always keep a generic translated fallback.
887
+
888
+ | Family | Codes | Meaning and integration response |
889
+ | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
890
+ | Payment details | `elements_payment_details_incomplete` | Required secure fields are empty or incomplete. Keep the form visible, focus or highlight its fields, and ask the customer to complete it. |
891
+ | Payment details | `elements_payment_details_invalid` | One or more completed fields are invalid. Keep the form visible and ask the customer to correct the highlighted fields. |
892
+ | Payment Method creation | `elements_payment_method_creation_failed` | The secure component could not create the server-consumable Payment Method. Keep the form mounted; offer a retry or another payment method according to `recoverable`. |
893
+ | Element lifecycle | `elements_destroyed`, `elements_not_mounted`, `elements_not_ready`, `elements_reinitialized` | The caller submitted against an unavailable or replaced Element instance. Wait for `ready`, remount, or recreate the Element as appropriate. |
894
+ | Controller/component initialization | `elements_initialization_invalid`, `elements_locale_invalid`, `elements_controller_failed`, `elements_component_configuration_invalid`, `elements_component_connect_failed`, `elements_component_attach_failed`, `elements_component_not_ready`, `elements_provider_initialization_failed` | The secure Elements surface could not initialize. Do not expose internal diagnostics; show a translated unavailable message and offer another payment method. |
895
+ | Elements session | `elements_session_expired`, `elements_session_binding_mismatch`, `elements_session_verification_failed` | The form's authoritative configuration is expired or cannot be verified. Recreate or reload the Elements group instead of blindly resubmitting. |
896
+ | Submission concurrency | `elements_submission_in_progress`, `elements_submit_in_progress`, `elements_test_preset_in_progress` | Another operation already owns the Element. Keep the form visible and wait for that operation to settle. |
897
+ | Submission result | `elements_submission_failed`, `elements_submit_failed` | Submission failed with no more specific safe classification. Use the generic translated fallback and `recoverable`. |
898
+ | Ambiguous submission | `elements_submit_indeterminate`, `elements_submit_invalid_response`, `elements_submit_timeout` | The caller cannot safely infer whether the operation completed. Reconcile server state or refresh before another financial attempt. |
899
+ | Action shell | `elements_action_canceled`, `elements_action_channel_unavailable`, `elements_action_shell_timeout` | The detached action was canceled or its trusted channel could not be established. Keep the payment form available and give translated retry/alternative guidance. |
900
+ | 3DS verification | `elements_action_challenge_failed`, `elements_three_ds_authentication_failed`, `elements_three_ds_challenge_failed`, `elements_three_ds_challenge_invalid`, `elements_three_ds_decoupled_not_supported`, `elements_three_ds_provider_session_failed`, `elements_three_ds_scope_mismatch` | Verification did not complete with trusted evidence. Never treat the payment as authenticated; allow a safe retry or another payment method according to server state. |
901
+
902
+ These codes describe client collection and action handling. Once a concrete
903
+ PaymentIntent or Checkout confirmation is attempted, server-owned Paycore
904
+ fields such as `code`, `message_code`, `advice_code`, and `decline_code` remain
905
+ the authority for payment-attempt failures. They are a separate taxonomy and
906
+ should likewise be mapped to localized integration copy.
907
+
711
908
  ## Types
712
909
 
713
910
  ### ApiErrorPayload
@@ -719,9 +916,12 @@ The SDK forwards the error payload provided by Hosted Checkout. Common shapes in
719
916
  type CardField = 'card_number' | 'expiration_date' | 'cvc' | 'cardholder_name';
720
917
 
721
918
  type CardValidationErrorCode =
722
- | 'invalid_number' | 'incomplete_number'
723
- | 'invalid_expiry' | 'incomplete_expiry'
724
- | 'invalid_cvc' | 'incomplete_cvc'
919
+ | 'invalid_number'
920
+ | 'incomplete_number'
921
+ | 'invalid_expiry'
922
+ | 'incomplete_expiry'
923
+ | 'invalid_cvc'
924
+ | 'incomplete_cvc'
725
925
  | 'required';
726
926
 
727
927
  type VendorValidationType = 'invalid' | 'incomplete' | 'required';
@@ -754,7 +954,7 @@ type ApiErrorPayload =
754
954
  type?: 'card_error' | string;
755
955
  message?: string;
756
956
  status_code?: number; // some sources use `status`
757
- status?: number; // compatibility with some payloads
957
+ status?: number; // compatibility with some payloads
758
958
  decline_code?: string; // Optional decline reason
759
959
  trace_id?: string;
760
960
  timestamp?: string; // ISO8601
@@ -772,8 +972,18 @@ type ApiErrorPayload =
772
972
  "status_code": 400,
773
973
  "timestamp": "2025-01-01T12:00:00.000Z",
774
974
  "errors": [
775
- { "field": "card_number", "code": "invalid_number", "message": "Card number is invalid", "vendor_type": "invalid" },
776
- { "field": "expiration_date", "code": "incomplete_expiry", "message": "Incomplete date", "vendor_type": "incomplete" }
975
+ {
976
+ "field": "card_number",
977
+ "code": "invalid_number",
978
+ "message": "Card number is invalid",
979
+ "vendor_type": "invalid"
980
+ },
981
+ {
982
+ "field": "expiration_date",
983
+ "code": "incomplete_expiry",
984
+ "message": "Incomplete date",
985
+ "vendor_type": "incomplete"
986
+ }
777
987
  ]
778
988
  }
779
989
  ```
@@ -815,8 +1025,8 @@ type ApiErrorPayload =
815
1025
  - session_expired — Checkout session is no longer valid; create a new session.
816
1026
  - permission_denied — Server responded with permission error (e.g., session not allowed). Not enumerated above; SDK forwards unknown codes unchanged.
817
1027
 
818
-
819
1028
  Notes:
1029
+
820
1030
  - For 3DS issues, you may receive `threeds_error` with `status_code` 424 and a server-provided message.
821
1031
  - For declines, expect `code: 'card_declined'`, optional `decline_code`, and a user-friendly `message`.
822
1032
  - The validation error `message` fields are already localized based on the checkout’s locale.
@@ -857,7 +1067,6 @@ The SDK forwards whatever Hosted Checkout sends for 3DS events. Shapes may evolv
857
1067
 
858
1068
  Tip: Prefer subscribing with the SdkEvent enum for stronger typing.
859
1069
 
860
-
861
1070
  ## Usage Examples
862
1071
 
863
1072
  ### Vanilla JavaScript (CDN)
@@ -865,34 +1074,39 @@ Tip: Prefer subscribing with the SdkEvent enum for stronger typing.
865
1074
  ```html
866
1075
  <!DOCTYPE html>
867
1076
  <html>
868
- <head>
869
- <title>Paypercut Checkout</title>
870
- </head>
871
- <body>
872
- <div id="checkout"></div>
873
-
874
- <script src="https://cdn.jsdelivr.net/npm/@paypercut/checkout-js@1.2.12/dist/paypercut-checkout.iife.min.js"></script>
875
- <script>
876
- const checkout = PaypercutCheckout({
877
- id: '01KB23M9EC960C50G3AH14FTTT',
878
- containerId: '#checkout',
879
- locale: 'en',
880
- ui_mode: 'embedded',
881
- wallet_options: ['apple_pay', 'google_pay']
882
- });
1077
+ <head>
1078
+ <title>Paypercut Checkout</title>
1079
+ </head>
1080
+ <body>
1081
+ <div id="checkout"></div>
1082
+
1083
+ <script src="https://cdn.jsdelivr.net/npm/@paypercut/checkout-js@1.2.19/dist/paypercut-checkout.iife.min.js"></script>
1084
+ <script>
1085
+ const checkout = PaypercutCheckout({
1086
+ id: '01KB23M9EC960C50G3AH14FTTT',
1087
+ containerId: '#checkout',
1088
+ locale: 'en',
1089
+ ui_mode: 'embedded',
1090
+ wallet_options: ['apple_pay', 'google_pay'],
1091
+ });
883
1092
 
884
- checkout.on('success', function(payload) {
885
- // payload.payment_method: { brand, last4, exp_month, exp_year }
886
- alert('Payment successful with ' + payload.payment_method.brand + ' ending in ' + payload.payment_method.last4);
887
- });
1093
+ checkout.on('success', function (payload) {
1094
+ // payload.payment_method: { brand, last4, exp_month, exp_year }
1095
+ alert(
1096
+ 'Payment successful with ' +
1097
+ payload.payment_method.brand +
1098
+ ' ending in ' +
1099
+ payload.payment_method.last4,
1100
+ );
1101
+ });
888
1102
 
889
- checkout.on('error', function(error) {
890
- alert('Payment failed: ' + error.message);
891
- });
1103
+ checkout.on('error', function (error) {
1104
+ alert('Payment failed: ' + error.message);
1105
+ });
892
1106
 
893
- checkout.render();
894
- </script>
895
- </body>
1107
+ checkout.render();
1108
+ </script>
1109
+ </body>
896
1110
  </html>
897
1111
  ```
898
1112
 
@@ -907,7 +1121,7 @@ const checkout = PaypercutCheckout({
907
1121
  locale: 'auto',
908
1122
  ui_mode: 'embedded',
909
1123
  wallet_options: ['apple_pay', 'google_pay'],
910
- form_only: false
1124
+ form_only: false,
911
1125
  });
912
1126
 
913
1127
  checkout.on('success', (payload) => {
@@ -955,7 +1169,7 @@ export function CheckoutComponent({ checkoutId }: { checkoutId: string }) {
955
1169
  locale: 'auto',
956
1170
  ui_mode: 'embedded',
957
1171
  wallet_options: ['apple_pay', 'google_pay'],
958
- form_only: false
1172
+ form_only: false,
959
1173
  });
960
1174
 
961
1175
  checkout.on('loaded', () => {
@@ -987,7 +1201,9 @@ export function CheckoutComponent({ checkoutId }: { checkoutId: string }) {
987
1201
  <div ref={containerRef} style={{ width: '100%', height: '600px' }} />
988
1202
  {status === 'loading' && <p>Processing payment...</p>}
989
1203
  {status === 'success' && paymentMethod && (
990
- <p>✅ Payment successful with {paymentMethod.brand} ending in {paymentMethod.last4}!</p>
1204
+ <p>
1205
+ ✅ Payment successful with {paymentMethod.brand} ending in {paymentMethod.last4}!
1206
+ </p>
991
1207
  )}
992
1208
  {status === 'error' && <p>❌ Payment failed. Please try again.</p>}
993
1209
  </div>
@@ -1003,7 +1219,13 @@ If you want to create a modal-like experience, you can use the `loaded` event to
1003
1219
  import { useEffect, useRef, useState } from 'react';
1004
1220
  import { PaypercutCheckout, CheckoutInstance } from '@paypercut/checkout-js';
1005
1221
 
1006
- export function ModalCheckout({ checkoutId, onClose }: { checkoutId: string; onClose: () => void }) {
1222
+ export function ModalCheckout({
1223
+ checkoutId,
1224
+ onClose,
1225
+ }: {
1226
+ checkoutId: string;
1227
+ onClose: () => void;
1228
+ }) {
1007
1229
  const containerRef = useRef<HTMLDivElement>(null);
1008
1230
  const [isLoading, setIsLoading] = useState(true);
1009
1231
 
@@ -1012,7 +1234,7 @@ export function ModalCheckout({ checkoutId, onClose }: { checkoutId: string; onC
1012
1234
 
1013
1235
  const checkout = PaypercutCheckout({
1014
1236
  id: checkoutId,
1015
- containerId: containerRef.current
1237
+ containerId: containerRef.current,
1016
1238
  });
1017
1239
 
1018
1240
  checkout.on('loaded', () => {
@@ -1036,41 +1258,47 @@ export function ModalCheckout({ checkoutId, onClose }: { checkoutId: string; onC
1036
1258
  }, [checkoutId, onClose]);
1037
1259
 
1038
1260
  return (
1039
- <div style={{
1040
- position: 'fixed',
1041
- top: 0,
1042
- left: 0,
1043
- right: 0,
1044
- bottom: 0,
1045
- backgroundColor: 'rgba(0, 0, 0, 0.5)',
1046
- display: 'flex',
1047
- alignItems: 'center',
1048
- justifyContent: 'center',
1049
- zIndex: 9999
1050
- }}>
1051
- <div style={{
1052
- position: 'relative',
1053
- width: '90%',
1054
- maxWidth: '500px',
1055
- height: '90%',
1056
- maxHeight: '700px',
1057
- backgroundColor: '#fff',
1058
- borderRadius: '12px',
1059
- overflow: 'hidden'
1060
- }}>
1261
+ <div
1262
+ style={{
1263
+ position: 'fixed',
1264
+ top: 0,
1265
+ left: 0,
1266
+ right: 0,
1267
+ bottom: 0,
1268
+ backgroundColor: 'rgba(0, 0, 0, 0.5)',
1269
+ display: 'flex',
1270
+ alignItems: 'center',
1271
+ justifyContent: 'center',
1272
+ zIndex: 9999,
1273
+ }}
1274
+ >
1275
+ <div
1276
+ style={{
1277
+ position: 'relative',
1278
+ width: '90%',
1279
+ maxWidth: '500px',
1280
+ height: '90%',
1281
+ maxHeight: '700px',
1282
+ backgroundColor: '#fff',
1283
+ borderRadius: '12px',
1284
+ overflow: 'hidden',
1285
+ }}
1286
+ >
1061
1287
  {isLoading && (
1062
- <div style={{
1063
- position: 'absolute',
1064
- top: 0,
1065
- left: 0,
1066
- right: 0,
1067
- bottom: 0,
1068
- display: 'flex',
1069
- alignItems: 'center',
1070
- justifyContent: 'center',
1071
- backgroundColor: '#fff',
1072
- zIndex: 1
1073
- }}>
1288
+ <div
1289
+ style={{
1290
+ position: 'absolute',
1291
+ top: 0,
1292
+ left: 0,
1293
+ right: 0,
1294
+ bottom: 0,
1295
+ display: 'flex',
1296
+ alignItems: 'center',
1297
+ justifyContent: 'center',
1298
+ backgroundColor: '#fff',
1299
+ zIndex: 1,
1300
+ }}
1301
+ >
1074
1302
  <p>Loading checkout...</p>
1075
1303
  </div>
1076
1304
  )}
@@ -1081,7 +1309,7 @@ export function ModalCheckout({ checkoutId, onClose }: { checkoutId: string; onC
1081
1309
  position: 'absolute',
1082
1310
  top: '10px',
1083
1311
  right: '10px',
1084
- zIndex: 2
1312
+ zIndex: 2,
1085
1313
  }}
1086
1314
  >
1087
1315
  ✕
@@ -1135,7 +1363,7 @@ The SDK automatically resizes the iframe to match the checkout content height. T
1135
1363
  ```javascript
1136
1364
  const checkout = PaypercutCheckout({
1137
1365
  id: '01KB23M9EC960C50G3AH14FTTT',
1138
- containerId: '#checkout-mount'
1366
+ containerId: '#checkout-mount',
1139
1367
  });
1140
1368
  checkout.render();
1141
1369
  ```
@@ -1170,6 +1398,7 @@ Always use HTTPS in production. The SDK is designed for secure communication ove
1170
1398
  **Problem:** The iframe doesn't appear after calling `render()`.
1171
1399
 
1172
1400
  **Solutions:**
1401
+
1173
1402
  - Ensure the container element exists in the DOM before calling `render()`
1174
1403
  - Check that the `id` is a valid checkout session ID
1175
1404
  - Verify there are no CSP errors in the browser console
@@ -1180,6 +1409,7 @@ Always use HTTPS in production. The SDK is designed for secure communication ove
1180
1409
  **Problem:** Event handlers are not being called.
1181
1410
 
1182
1411
  **Solutions:**
1412
+
1183
1413
  - Ensure you subscribe to events before calling `render()`
1184
1414
  - Check that the checkout session is active and not expired
1185
1415
  - Enable debug mode to see message logs
@@ -1189,6 +1419,7 @@ Always use HTTPS in production. The SDK is designed for secure communication ove
1189
1419
  **Problem:** TypeScript shows type errors when using the SDK.
1190
1420
 
1191
1421
  **Solutions:**
1422
+
1192
1423
  - Ensure you're importing types: `import { PaypercutCheckout, CheckoutInstance } from '@paypercut/checkout-js'`
1193
1424
  - Update to the latest version of the SDK
1194
1425
  - Check that your `tsconfig.json` includes the SDK's type definitions
@@ -1200,8 +1431,8 @@ Always use HTTPS in production. The SDK is designed for secure communication ove
1200
1431
  Add DNS prefetch and preconnect hints to your HTML for faster loading:
1201
1432
 
1202
1433
  ```html
1203
- <link rel="preconnect" href="https://buy.paypercut.io ">
1204
- <link rel="dns-prefetch" href="https://buy.paypercut.io ">
1434
+ <link rel="preconnect" href="https://buy.paypercut.io " />
1435
+ <link rel="dns-prefetch" href="https://buy.paypercut.io " />
1205
1436
  ```
1206
1437
 
1207
1438
  ### Lazy Loading
@@ -1308,16 +1539,15 @@ The following shows the **exact call/receive sequence** for a complete Express C
1308
1539
 
1309
1540
  const express = PaypercutExpressCheckout({
1310
1541
  publishableKey: 'pk_test_...',
1311
- amount: 2500, // €25.00 — the initial total (before shipping is chosen)
1542
+ amount: 2500, // €25.00 — the initial total (before shipping is chosen)
1312
1543
  currency: 'EUR',
1313
1544
  countryCode: 'DE',
1314
1545
  shippingOptions: [
1315
1546
  { id: 'standard', label: 'Standard Shipping', detail: '3–5 days', amount: 499 },
1316
- { id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
1547
+ { id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
1317
1548
  ],
1318
1549
  });
1319
1550
 
1320
-
1321
1551
  // ─── Step 2: Subscribe to events (before mount) ───────────────────────────────
1322
1552
  // Always subscribe before calling mount().
1323
1553
 
@@ -1331,7 +1561,6 @@ express.on('click', () => {
1331
1561
  console.log('Wallet sheet opening...');
1332
1562
  });
1333
1563
 
1334
-
1335
1564
  // ─── Step 3: Wallet sheet opens — provide initial shipping options ─────────────
1336
1565
  // You RECEIVE: 'session_start' when the wallet sheet opens, BEFORE any address
1337
1566
  // or option is shown. The wallet sheet is PAUSED — you must call updateWith()
@@ -1348,20 +1577,20 @@ express.on('session_start', async ({ wallet, updateWith }) => {
1348
1577
 
1349
1578
  // You CALL: updateWith() — this unblocks the wallet sheet with initial options
1350
1579
  updateWith({
1351
- amount: 2500 + 499, // subtotal + default shipping cost
1580
+ amount: 2500 + 499, // subtotal + default shipping cost
1352
1581
  shippingOptions: [
1353
1582
  { id: 'standard', label: 'Standard Shipping', detail: '3–5 days', amount: 499 },
1354
- { id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
1583
+ { id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
1355
1584
  ],
1356
- lineItems: [ // Apple Pay only — line item breakdown
1357
- { label: 'Subtotal', amount: 2500 },
1585
+ lineItems: [
1586
+ // Apple Pay only — line item breakdown
1587
+ { label: 'Subtotal', amount: 2500 },
1358
1588
  { label: 'Standard Shipping', amount: 499 },
1359
1589
  ],
1360
1590
  });
1361
1591
  // → Wallet sheet now renders with these options
1362
1592
  });
1363
1593
 
1364
-
1365
1594
  // ─── Step 4: User changes shipping address ────────────────────────────────────
1366
1595
  // You RECEIVE: 'shipping_address_change' with a partial address
1367
1596
  // (country, state, city, postalCode — no street at this stage)
@@ -1377,13 +1606,15 @@ express.on('shipping_address_change', ({ address, updateWith }) => {
1377
1606
 
1378
1607
  // You CALL: updateWith() — this unblocks the wallet sheet and updates the displayed total
1379
1608
  updateWith({
1380
- amount: newTotal, // new total including shipping
1381
- shippingOptions: [ // updated options for this region
1609
+ amount: newTotal, // new total including shipping
1610
+ shippingOptions: [
1611
+ // updated options for this region
1382
1612
  { id: 'standard', label: 'Standard Shipping', amount: shippingCost },
1383
- { id: 'express', label: 'Express Shipping', amount: shippingCost + 500 },
1613
+ { id: 'express', label: 'Express Shipping', amount: shippingCost + 500 },
1384
1614
  ],
1385
- lineItems: [ // Apple Pay only — line item breakdown
1386
- { label: 'Subtotal', amount: 2500 },
1615
+ lineItems: [
1616
+ // Apple Pay only — line item breakdown
1617
+ { label: 'Subtotal', amount: 2500 },
1387
1618
  { label: 'Standard Shipping', amount: shippingCost },
1388
1619
  ],
1389
1620
  // To reject an unsupported address instead:
@@ -1392,7 +1623,6 @@ express.on('shipping_address_change', ({ address, updateWith }) => {
1392
1623
  // → Wallet sheet now shows the updated total and shipping options
1393
1624
  });
1394
1625
 
1395
-
1396
1626
  // ─── Step 5: User selects a shipping option ───────────────────────────────────
1397
1627
  // You RECEIVE: 'shipping_option_change' when the user switches e.g. Standard → Express
1398
1628
  // The wallet sheet is PAUSED again — you must call updateWith() again.
@@ -1406,40 +1636,48 @@ express.on('shipping_option_change', ({ shippingOption, updateWith }) => {
1406
1636
  // You CALL: updateWith() — unblocks the sheet with the new total
1407
1637
  updateWith({
1408
1638
  amount: newTotal,
1409
- lineItems: [ // Apple Pay only
1410
- { label: 'Subtotal', amount: 2500 },
1411
- { label: shippingOption.label, amount: shippingOption.amount },
1639
+ lineItems: [
1640
+ // Apple Pay only
1641
+ { label: 'Subtotal', amount: 2500 },
1642
+ { label: shippingOption.label, amount: shippingOption.amount },
1412
1643
  ],
1413
1644
  });
1414
1645
  // → Wallet sheet updates to show the new total
1415
1646
  });
1416
1647
 
1417
-
1418
1648
  // ─── Step 6: User confirms payment ───────────────────────────────────────────
1419
1649
  // User taps "Pay" in the wallet sheet.
1420
1650
  // SDK tokenizes the card via Basis Theory, creates a Paypercut payment method,
1421
1651
  // and auto-closes the wallet sheet. No action needed from you to close the sheet.
1422
1652
 
1423
1653
  // You RECEIVE: 'payment_method_created' with the payment method ID
1424
- express.on('payment_method_created', async ({ paymentMethodId, idempotencyKey, billingDetails, shippingDetails, selectedShippingOption }) => {
1425
- console.log('Payment method created:', paymentMethodId);
1426
- // paymentMethodId = 'pm_01J...'
1427
- // billingDetails = { name: 'John Doe', address: { line1: '...', country: 'DE', ... } }
1428
- // shippingDetails = { name: 'John Doe', address: { line1: '48 Example St', ... } }
1429
- // selectedShippingOption = { id: 'express', label: 'Express Shipping', amount: 999 }
1430
-
1431
- // You CALL: your backend to create and confirm the payment intent
1432
- const res = await fetch('/api/confirm-payment', {
1433
- method: 'POST',
1434
- headers: { 'Content-Type': 'application/json' },
1435
- body: JSON.stringify({ paymentMethodId, idempotencyKey }),
1436
- });
1437
-
1438
- if (res.ok) {
1439
- window.location.href = '/success';
1440
- }
1441
- });
1654
+ express.on(
1655
+ 'payment_method_created',
1656
+ async ({
1657
+ paymentMethodId,
1658
+ idempotencyKey,
1659
+ billingDetails,
1660
+ shippingDetails,
1661
+ selectedShippingOption,
1662
+ }) => {
1663
+ console.log('Payment method created:', paymentMethodId);
1664
+ // paymentMethodId = 'pm_01J...'
1665
+ // billingDetails = { name: 'John Doe', address: { line1: '...', country: 'DE', ... } }
1666
+ // shippingDetails = { name: 'John Doe', address: { line1: '48 Example St', ... } }
1667
+ // selectedShippingOption = { id: 'express', label: 'Express Shipping', amount: 999 }
1668
+
1669
+ // You CALL: your backend to create and confirm the payment intent
1670
+ const res = await fetch('/api/confirm-payment', {
1671
+ method: 'POST',
1672
+ headers: { 'Content-Type': 'application/json' },
1673
+ body: JSON.stringify({ paymentMethodId, idempotencyKey }),
1674
+ });
1442
1675
 
1676
+ if (res.ok) {
1677
+ window.location.href = '/success';
1678
+ }
1679
+ },
1680
+ );
1443
1681
 
1444
1682
  // ─── Step 7: Handle failure or cancellation ───────────────────────────────────
1445
1683
  // You RECEIVE: 'payment_method_failed' if tokenization or PM creation fails
@@ -1453,13 +1691,11 @@ express.on('cancel', () => {
1453
1691
  console.log('User closed the wallet sheet');
1454
1692
  });
1455
1693
 
1456
-
1457
1694
  // ─── Step 8: Mount ────────────────────────────────────────────────────────────
1458
1695
  // You CALL: mount() — renders the wallet buttons into the container
1459
1696
  express.mount('#express-checkout');
1460
1697
  // → 'ready' fires once buttons are visible
1461
1698
 
1462
-
1463
1699
  // ─── Step 9: Cleanup ─────────────────────────────────────────────────────────
1464
1700
  // You CALL: destroy() when the component unmounts to prevent memory leaks
1465
1701
  // express.destroy();
@@ -1474,12 +1710,12 @@ import { PaypercutExpressCheckout, ExpressSdkEvent } from '@paypercut/checkout-j
1474
1710
 
1475
1711
  const express = PaypercutExpressCheckout({
1476
1712
  publishableKey: 'pk_test_...',
1477
- amount: 2999, // in minor units (€29.99)
1713
+ amount: 2999, // in minor units (€29.99)
1478
1714
  currency: 'EUR',
1479
1715
  countryCode: 'DE',
1480
1716
  shippingOptions: [
1481
1717
  { id: 'standard', label: 'Standard Shipping', detail: '3–5 business days', amount: 499 },
1482
- { id: 'express', label: 'Express Shipping', detail: '1–2 business days', amount: 999 },
1718
+ { id: 'express', label: 'Express Shipping', detail: '1–2 business days', amount: 999 },
1483
1719
  ],
1484
1720
  });
1485
1721
 
@@ -1490,18 +1726,18 @@ express.mount('#express-checkout');
1490
1726
 
1491
1727
  ### Express Checkout Options
1492
1728
 
1493
- | Option | Type | Required | Description |
1494
- |--------|------|----------|-------------|
1495
- | `publishableKey` | `string` | Yes | Your Paypercut publishable API key (`pk_test_…` or `pk_live_…`) |
1496
- | `amount` | `number` | Yes | Total amount in **minor units** (e.g. `1200` = €12.00) |
1497
- | `currency` | `string` | Yes | ISO 4217 currency code (e.g. `'EUR'`, `'USD'`) |
1498
- | `countryCode` | `string` | Yes | ISO 3166-1 alpha-2 merchant country code (e.g. `'DE'`). Required for Google Pay in production. |
1499
- | `shippingOptions` | `ExpressCheckoutShippingOption[]` | Yes | Initial shipping options shown in the wallet sheet. Must include at least one. |
1500
- | `lineItems` | `LineItem[]` | No | Line item breakdown shown in the **Apple Pay** sheet (subtotal, tax, etc.). Ignored by Google Pay. |
1501
- | `walletOptions` | `('apple_pay' \| 'google_pay')[]` | No | Which wallets to show. Defaults to both. |
1502
- | `layout` | `'auto' \| 'row' \| 'column'` | No | Button layout. `'auto'` *(default)* uses a ResizeObserver to switch between row (>540 px) and column (≤540 px) automatically. `'row'` is always side by side. `'column'` always stacks vertically. |
1503
- | `locale` | `string` | No | ISO 639-1 two-letter language code (e.g. `'en'`, `'bg'`, `'pl'`). Controls the language of the wallet button labels. Each wallet applies this independently — not all languages are supported by every wallet; unsupported values fall back to `'en'`. |
1504
- | `buttonOptions` | `ExpressButtonOptions` | No | Customize the label type and color/style of the wallet buttons. See [Button Options](#button-options) below. |
1729
+ | Option | Type | Required | Description |
1730
+ | ----------------- | --------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1731
+ | `publishableKey` | `string` | Yes | Your Paypercut publishable API key (`pk_test_…` or `pk_live_…`) |
1732
+ | `amount` | `number` | Yes | Total amount in **minor units** (e.g. `1200` = €12.00) |
1733
+ | `currency` | `string` | Yes | ISO 4217 currency code (e.g. `'EUR'`, `'USD'`) |
1734
+ | `countryCode` | `string` | Yes | ISO 3166-1 alpha-2 merchant country code (e.g. `'DE'`). Required for Google Pay in production. |
1735
+ | `shippingOptions` | `ExpressCheckoutShippingOption[]` | Yes | Initial shipping options shown in the wallet sheet. Must include at least one. |
1736
+ | `lineItems` | `LineItem[]` | No | Line item breakdown shown in the **Apple Pay** sheet (subtotal, tax, etc.). Ignored by Google Pay. |
1737
+ | `walletOptions` | `('apple_pay' \| 'google_pay')[]` | No | Which wallets to show. Defaults to both. |
1738
+ | `layout` | `'auto' \| 'row' \| 'column'` | No | Button layout. `'auto'` _(default)_ uses a ResizeObserver to switch between row (>540 px) and column (≤540 px) automatically. `'row'` is always side by side. `'column'` always stacks vertically. |
1739
+ | `locale` | `string` | No | ISO 639-1 two-letter language code (e.g. `'en'`, `'bg'`, `'pl'`). Controls the language of the wallet button labels. Each wallet applies this independently — not all languages are supported by every wallet; unsupported values fall back to `'en'`. |
1740
+ | `buttonOptions` | `ExpressButtonOptions` | No | Customize the label type and color/style of the wallet buttons. See [Button Options](#button-options) below. |
1505
1741
 
1506
1742
  ---
1507
1743
 
@@ -1513,36 +1749,36 @@ Control the label and appearance of the Apple Pay and Google Pay buttons via the
1513
1749
  PaypercutExpressCheckout({
1514
1750
  // ...
1515
1751
  buttonOptions: {
1516
- type: 'pay', // label shown on both buttons — defaults to 'buy'
1517
- applePayStyle: 'black', // Apple Pay button color — defaults to 'black'
1752
+ type: 'pay', // label shown on both buttons — defaults to 'buy'
1753
+ applePayStyle: 'black', // Apple Pay button color — defaults to 'black'
1518
1754
  googlePayColor: 'default', // Google Pay button color — defaults to 'default'
1519
- borderRadius: '0.5rem', // border radius for both buttons — defaults to '0.5rem'
1755
+ borderRadius: '0.5rem', // border radius for both buttons — defaults to '0.5rem'
1520
1756
  },
1521
1757
  });
1522
1758
  ```
1523
1759
 
1524
1760
  #### `type` — applies to both Apple Pay and Google Pay
1525
1761
 
1526
- | Value | Button label |
1527
- |-------|-------------|
1528
- | `'plain'` *(default)* | Logo only (no text) |
1529
- | `'pay'` | Pay with Apple Pay / Pay with Google Pay |
1530
- | `'buy'` | Buy with Apple Pay / Buy with Google Pay |
1531
- | `'donate'` | Donate with … |
1532
- | `'checkout'` | Checkout with … |
1533
- | `'subscribe'` | Subscribe with … |
1534
- | `'book'` | Book with … |
1535
- | `'order'` | Order with … |
1536
- | `'tip'` | Tip with … |
1537
- | `'contribute'` | Contribute with … |
1762
+ | Value | Button label |
1763
+ | --------------------- | ---------------------------------------- |
1764
+ | `'plain'` _(default)_ | Logo only (no text) |
1765
+ | `'pay'` | Pay with Apple Pay / Pay with Google Pay |
1766
+ | `'buy'` | Buy with Apple Pay / Buy with Google Pay |
1767
+ | `'donate'` | Donate with … |
1768
+ | `'checkout'` | Checkout with … |
1769
+ | `'subscribe'` | Subscribe with … |
1770
+ | `'book'` | Book with … |
1771
+ | `'order'` | Order with … |
1772
+ | `'tip'` | Tip with … |
1773
+ | `'contribute'` | Contribute with … |
1538
1774
 
1539
1775
  #### `applePayStyle` — Apple Pay only
1540
1776
 
1541
- | Value | Appearance |
1542
- |-------|-----------|
1543
- | `'black'` *(default)* | Black background, white logo |
1544
- | `'white'` | White background, black logo |
1545
- | `'white-outline'` | White background with a black border, black logo |
1777
+ | Value | Appearance |
1778
+ | --------------------- | ------------------------------------------------ |
1779
+ | `'black'` _(default)_ | Black background, white logo |
1780
+ | `'white'` | White background, black logo |
1781
+ | `'white-outline'` | White background with a black border, black logo |
1546
1782
 
1547
1783
  #### `borderRadius` — applies to both
1548
1784
 
@@ -1550,23 +1786,23 @@ Any valid CSS value (e.g. `'0.5rem'`, `'8px'`, `'50%'`). Defaults to `'0.5rem'`.
1550
1786
 
1551
1787
  #### `googlePayColor` — Google Pay only
1552
1788
 
1553
- | Value | Appearance |
1554
- |-------|-----------|
1555
- | `'default'` *(default)* | White background on light themes, dark on dark themes |
1556
- | `'black'` | Black background |
1557
- | `'white'` | White background |
1789
+ | Value | Appearance |
1790
+ | ----------------------- | ----------------------------------------------------- |
1791
+ | `'default'` _(default)_ | White background on light themes, dark on dark themes |
1792
+ | `'black'` | Black background |
1793
+ | `'white'` | White background |
1558
1794
 
1559
1795
  ```typescript
1560
1796
  interface ExpressCheckoutShippingOption {
1561
- id: string; // unique identifier, e.g. 'standard'
1562
- label: string; // display label, e.g. 'Standard Shipping'
1563
- detail?: string; // subtitle, e.g. '3–5 business days'
1564
- amount: number; // cost in minor units
1797
+ id: string; // unique identifier, e.g. 'standard'
1798
+ label: string; // display label, e.g. 'Standard Shipping'
1799
+ detail?: string; // subtitle, e.g. '3–5 business days'
1800
+ amount: number; // cost in minor units
1565
1801
  }
1566
1802
 
1567
1803
  interface LineItem {
1568
1804
  label: string;
1569
- amount: number; // minor units
1805
+ amount: number; // minor units
1570
1806
  type?: 'final' | 'pending';
1571
1807
  }
1572
1808
  ```
@@ -1603,7 +1839,7 @@ express.update({
1603
1839
  amount: 3998,
1604
1840
  shippingOptions: [
1605
1841
  { id: 'standard', label: 'Standard Shipping', amount: 499 },
1606
- { id: 'express', label: 'Express Shipping', amount: 999 },
1842
+ { id: 'express', label: 'Express Shipping', amount: 999 },
1607
1843
  ],
1608
1844
  });
1609
1845
  ```
@@ -1620,17 +1856,17 @@ express.destroy();
1620
1856
 
1621
1857
  ### Express Checkout Events
1622
1858
 
1623
- | Event | Enum | Payload | Description |
1624
- |-------|------|---------|-------------|
1625
- | `ready` | `ExpressSdkEvent.Ready` | — | Wallet buttons are rendered and ready |
1626
- | `click` | `ExpressSdkEvent.Click` | — | User tapped a wallet button |
1627
- | `session_start` | `ExpressSdkEvent.SessionStart` | `ExpressSessionStartEvent` | Wallet sheet opened — **must call `updateWith()`** with initial options to unblock |
1628
- | `shipping_address_change` | `ExpressSdkEvent.ShippingAddressChange` | `ShippingAddressChangeEvent` | User changed shipping address — must call `updateWith()` |
1629
- | `shipping_option_change` | `ExpressSdkEvent.ShippingOptionChange` | `ShippingOptionChangeEvent` | User selected a different shipping option — must call `updateWith()` |
1630
- | `payment_method_created` | `ExpressSdkEvent.PaymentMethodCreated` | `ExpressPaymentMethodCreatedEvent` | Payment method created — use `paymentMethodId` to confirm on backend |
1631
- | `payment_method_failed` | `ExpressSdkEvent.PaymentMethodFailed` | `ExpressPaymentMethodFailedEvent` | Tokenization or payment method creation failed |
1632
- | `cancel` | `ExpressSdkEvent.Cancel` | — | User dismissed the wallet sheet |
1633
- | `error` | `ExpressSdkEvent.Error` | `Error` | Unrecoverable SDK error |
1859
+ | Event | Enum | Payload | Description |
1860
+ | ------------------------- | --------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------- |
1861
+ | `ready` | `ExpressSdkEvent.Ready` | — | Wallet buttons are rendered and ready |
1862
+ | `click` | `ExpressSdkEvent.Click` | — | User tapped a wallet button |
1863
+ | `session_start` | `ExpressSdkEvent.SessionStart` | `ExpressSessionStartEvent` | Wallet sheet opened — **must call `updateWith()`** with initial options to unblock |
1864
+ | `shipping_address_change` | `ExpressSdkEvent.ShippingAddressChange` | `ShippingAddressChangeEvent` | User changed shipping address — must call `updateWith()` |
1865
+ | `shipping_option_change` | `ExpressSdkEvent.ShippingOptionChange` | `ShippingOptionChangeEvent` | User selected a different shipping option — must call `updateWith()` |
1866
+ | `payment_method_created` | `ExpressSdkEvent.PaymentMethodCreated` | `ExpressPaymentMethodCreatedEvent` | Payment method created — use `paymentMethodId` to confirm on backend |
1867
+ | `payment_method_failed` | `ExpressSdkEvent.PaymentMethodFailed` | `ExpressPaymentMethodFailedEvent` | Tokenization or payment method creation failed |
1868
+ | `cancel` | `ExpressSdkEvent.Cancel` | — | User dismissed the wallet sheet |
1869
+ | `error` | `ExpressSdkEvent.Error` | `Error` | Unrecoverable SDK error |
1634
1870
 
1635
1871
  ---
1636
1872
 
@@ -1656,7 +1892,7 @@ express.on('shipping_address_change', ({ address, updateWith }) => {
1656
1892
  amount: newTotal,
1657
1893
  shippingOptions: [
1658
1894
  { id: 'standard', label: 'Standard Shipping', amount: shippingCost },
1659
- { id: 'express', label: 'Express Shipping', amount: shippingCost + 500 },
1895
+ { id: 'express', label: 'Express Shipping', amount: shippingCost + 500 },
1660
1896
  ],
1661
1897
  // Use 'invalid_shipping_address' if you don't ship to this address:
1662
1898
  // status: 'invalid_shipping_address',
@@ -1689,12 +1925,12 @@ express.on('shipping_option_change', ({ shippingOption, updateWith }) => {
1689
1925
 
1690
1926
  #### `updateWith()` options
1691
1927
 
1692
- | Field | Type | Description |
1693
- |-------|------|-------------|
1694
- | `amount` | `number` | New total in minor units |
1695
- | `shippingOptions` | `ExpressCheckoutShippingOption[]` | Updated shipping options list |
1696
- | `lineItems` | `LineItem[]` | Updated Apple Pay line items (ignored by Google Pay) |
1697
- | `status` | `'success' \| 'invalid_shipping_address' \| 'invalid_shipping_option'` | Use an invalid status to show an error inside the sheet without closing it |
1928
+ | Field | Type | Description |
1929
+ | ----------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------- |
1930
+ | `amount` | `number` | New total in minor units |
1931
+ | `shippingOptions` | `ExpressCheckoutShippingOption[]` | Updated shipping options list |
1932
+ | `lineItems` | `LineItem[]` | Updated Apple Pay line items (ignored by Google Pay) |
1933
+ | `status` | `'success' \| 'invalid_shipping_address' \| 'invalid_shipping_option'` | Use an invalid status to show an error inside the sheet without closing it |
1698
1934
 
1699
1935
  ---
1700
1936
 
@@ -1745,7 +1981,7 @@ express.on('shipping_address_change', ({ address, updateWith }) => {
1745
1981
  amount: subtotal + shippingCost,
1746
1982
  shippingOptions: [
1747
1983
  { id: 'standard', label: 'Standard Shipping', amount: shippingCost },
1748
- { id: 'express', label: 'Express Shipping', amount: shippingCost + 500 },
1984
+ { id: 'express', label: 'Express Shipping', amount: shippingCost + 500 },
1749
1985
  ],
1750
1986
  });
1751
1987
  });
@@ -1790,11 +2026,11 @@ express.on('shipping_address_change', ({ address, updateWith }) => {
1790
2026
 
1791
2027
  #### Summary
1792
2028
 
1793
- | Approach | Apple Pay | Google Pay | UX |
1794
- |----------|-----------|------------|-----|
1795
- | `allowedCountries` in options | ✗ not supported | ✅ restricts picker | Best — error before user interacts |
1796
- | `status: 'invalid_shipping_address'` in `shipping_address_change` | ✅ | ✅ | Sheet shows inline error, stays open |
1797
- | Both combined | ✅ (runtime only) | ✅ (picker + runtime) | Recommended |
2029
+ | Approach | Apple Pay | Google Pay | UX |
2030
+ | ----------------------------------------------------------------- | ----------------- | --------------------- | ------------------------------------ |
2031
+ | `allowedCountries` in options | ✗ not supported | ✅ restricts picker | Best — error before user interacts |
2032
+ | `status: 'invalid_shipping_address'` in `shipping_address_change` | ✅ | ✅ | Sheet shows inline error, stays open |
2033
+ | Both combined | ✅ (runtime only) | ✅ (picker + runtime) | Recommended |
1798
2034
 
1799
2035
  ---
1800
2036
 
@@ -1814,10 +2050,10 @@ const SUBTOTAL = 4900; // €49.00
1814
2050
 
1815
2051
  const express = PaypercutExpressCheckout({
1816
2052
  publishableKey: 'pk_live_...',
1817
- amount: SUBTOTAL + 499, // subtotal + default shipping
2053
+ amount: SUBTOTAL + 499, // subtotal + default shipping
1818
2054
  currency: 'EUR',
1819
2055
  countryCode: 'DE',
1820
- allowedCountries: SUPPORTED_COUNTRIES, // Google Pay: restricts picker to these countries
2056
+ allowedCountries: SUPPORTED_COUNTRIES, // Google Pay: restricts picker to these countries
1821
2057
  });
1822
2058
 
1823
2059
  // Step 1 — Provide initial shipping options when wallet sheet opens
@@ -1826,10 +2062,10 @@ express.on('session_start', ({ wallet, updateWith }) => {
1826
2062
  amount: SUBTOTAL + 499,
1827
2063
  shippingOptions: [
1828
2064
  { id: 'standard', label: 'Standard Shipping', detail: '3–5 days', amount: 499 },
1829
- { id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
2065
+ { id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
1830
2066
  ],
1831
2067
  lineItems: [
1832
- { label: 'Subtotal', amount: SUBTOTAL },
2068
+ { label: 'Subtotal', amount: SUBTOTAL },
1833
2069
  { label: 'Standard Shipping', amount: 499 },
1834
2070
  ],
1835
2071
  });
@@ -1846,10 +2082,10 @@ express.on('shipping_address_change', ({ address, updateWith }) => {
1846
2082
  amount: SUBTOTAL + 499,
1847
2083
  shippingOptions: [
1848
2084
  { id: 'standard', label: 'Standard Shipping', detail: '3–5 days', amount: 499 },
1849
- { id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
2085
+ { id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
1850
2086
  ],
1851
2087
  lineItems: [
1852
- { label: 'Subtotal', amount: SUBTOTAL },
2088
+ { label: 'Subtotal', amount: SUBTOTAL },
1853
2089
  { label: 'Standard Shipping', amount: 499 },
1854
2090
  ],
1855
2091
  });
@@ -1860,26 +2096,29 @@ express.on('shipping_option_change', ({ shippingOption, updateWith }) => {
1860
2096
  updateWith({
1861
2097
  amount: SUBTOTAL + shippingOption.amount,
1862
2098
  lineItems: [
1863
- { label: 'Subtotal', amount: SUBTOTAL },
2099
+ { label: 'Subtotal', amount: SUBTOTAL },
1864
2100
  { label: shippingOption.label, amount: shippingOption.amount },
1865
2101
  ],
1866
2102
  });
1867
2103
  });
1868
2104
 
1869
2105
  // Step 4 — Payment method created, confirm on your backend
1870
- express.on('payment_method_created', async ({ paymentMethodId, idempotencyKey, shippingDetails, selectedShippingOption }) => {
1871
- await fetch('/api/orders', {
1872
- method: 'POST',
1873
- headers: { 'Content-Type': 'application/json' },
1874
- body: JSON.stringify({
1875
- paymentMethodId,
1876
- idempotencyKey,
1877
- shippingAddress: shippingDetails?.address,
1878
- shippingOption: selectedShippingOption?.id,
1879
- }),
1880
- });
1881
- window.location.href = '/order/confirmation';
1882
- });
2106
+ express.on(
2107
+ 'payment_method_created',
2108
+ async ({ paymentMethodId, idempotencyKey, shippingDetails, selectedShippingOption }) => {
2109
+ await fetch('/api/orders', {
2110
+ method: 'POST',
2111
+ headers: { 'Content-Type': 'application/json' },
2112
+ body: JSON.stringify({
2113
+ paymentMethodId,
2114
+ idempotencyKey,
2115
+ shippingAddress: shippingDetails?.address,
2116
+ shippingOption: selectedShippingOption?.id,
2117
+ }),
2118
+ });
2119
+ window.location.href = '/order/confirmation';
2120
+ },
2121
+ );
1883
2122
 
1884
2123
  express.on('shipping_options_required', ({ wallet }) => {
1885
2124
  console.error(`${wallet}: session_start timed out — shipping options were not provided`);
@@ -1902,7 +2141,7 @@ const SUBTOTAL = 7500; // €75.00
1902
2141
 
1903
2142
  const express = PaypercutExpressCheckout({
1904
2143
  publishableKey: 'pk_live_...',
1905
- amount: SUBTOTAL, // no shipping added yet — will be set in session_start
2144
+ amount: SUBTOTAL, // no shipping added yet — will be set in session_start
1906
2145
  currency: 'EUR',
1907
2146
  countryCode: 'DE',
1908
2147
  allowedCountries: ['DE', 'AT', 'CH', 'NL', 'BE', 'FR', 'IT', 'ES'],
@@ -1911,15 +2150,15 @@ const express = PaypercutExpressCheckout({
1911
2150
  // Step 1 — Fetch initial options from your API before the sheet opens
1912
2151
  express.on('session_start', async ({ wallet, updateWith }) => {
1913
2152
  // Call your backend — you have 3 seconds
1914
- const { options, defaultAmount } = await fetch('/api/shipping/default').then(r => r.json());
2153
+ const { options, defaultAmount } = await fetch('/api/shipping/default').then((r) => r.json());
1915
2154
  // e.g. { options: [{ id: 'standard', label: 'Standard', amount: 599 }], defaultAmount: 8099 }
1916
2155
 
1917
2156
  updateWith({
1918
2157
  amount: defaultAmount,
1919
2158
  shippingOptions: options,
1920
2159
  lineItems: [
1921
- { label: 'Subtotal', amount: SUBTOTAL },
1922
- { label: options[0].label, amount: options[0].amount },
2160
+ { label: 'Subtotal', amount: SUBTOTAL },
2161
+ { label: options[0].label, amount: options[0].amount },
1923
2162
  ],
1924
2163
  });
1925
2164
  });
@@ -1945,7 +2184,7 @@ express.on('shipping_address_change', async ({ address, updateWith }) => {
1945
2184
  amount: total,
1946
2185
  shippingOptions: options,
1947
2186
  lineItems: [
1948
- { label: 'Subtotal', amount: SUBTOTAL },
2187
+ { label: 'Subtotal', amount: SUBTOTAL },
1949
2188
  { label: options[0].label, amount: options[0].amount },
1950
2189
  ],
1951
2190
  });
@@ -1956,28 +2195,37 @@ express.on('shipping_option_change', ({ shippingOption, updateWith }) => {
1956
2195
  updateWith({
1957
2196
  amount: SUBTOTAL + shippingOption.amount,
1958
2197
  lineItems: [
1959
- { label: 'Subtotal', amount: SUBTOTAL },
2198
+ { label: 'Subtotal', amount: SUBTOTAL },
1960
2199
  { label: shippingOption.label, amount: shippingOption.amount },
1961
2200
  ],
1962
2201
  });
1963
2202
  });
1964
2203
 
1965
2204
  // Step 4 — Create order on backend
1966
- express.on('payment_method_created', async ({ paymentMethodId, idempotencyKey, billingDetails, shippingDetails, selectedShippingOption }) => {
1967
- const res = await fetch('/api/orders', {
1968
- method: 'POST',
1969
- headers: { 'Content-Type': 'application/json' },
1970
- body: JSON.stringify({
1971
- paymentMethodId,
1972
- idempotencyKey,
1973
- billing: billingDetails,
1974
- shipping: shippingDetails,
1975
- shippingOptionId: selectedShippingOption?.id,
1976
- }),
1977
- });
1978
- const { orderId } = await res.json();
1979
- window.location.href = `/orders/${orderId}/confirmation`;
1980
- });
2205
+ express.on(
2206
+ 'payment_method_created',
2207
+ async ({
2208
+ paymentMethodId,
2209
+ idempotencyKey,
2210
+ billingDetails,
2211
+ shippingDetails,
2212
+ selectedShippingOption,
2213
+ }) => {
2214
+ const res = await fetch('/api/orders', {
2215
+ method: 'POST',
2216
+ headers: { 'Content-Type': 'application/json' },
2217
+ body: JSON.stringify({
2218
+ paymentMethodId,
2219
+ idempotencyKey,
2220
+ billing: billingDetails,
2221
+ shipping: shippingDetails,
2222
+ shippingOptionId: selectedShippingOption?.id,
2223
+ }),
2224
+ });
2225
+ const { orderId } = await res.json();
2226
+ window.location.href = `/orders/${orderId}/confirmation`;
2227
+ },
2228
+ );
1981
2229
 
1982
2230
  express.on('shipping_options_required', ({ wallet }) => {
1983
2231
  alert(`Could not load shipping options for ${wallet}. Please try again.`);
@@ -2002,7 +2250,7 @@ import {
2002
2250
  } from '@paypercut/checkout-js';
2003
2251
 
2004
2252
  interface Props {
2005
- subtotal: number; // minor units
2253
+ subtotal: number; // minor units
2006
2254
  onSuccess: (orderId: string) => void;
2007
2255
  onCancel: () => void;
2008
2256
  }
@@ -2026,12 +2274,12 @@ export function ExpressCheckout({ subtotal, onSuccess, onCancel }: Props) {
2026
2274
 
2027
2275
  // Provide initial options before sheet opens
2028
2276
  express.on(ExpressSdkEvent.SessionStart, async ({ wallet, updateWith }) => {
2029
- const { options } = await fetch('/api/shipping/default').then(r => r.json());
2277
+ const { options } = await fetch('/api/shipping/default').then((r) => r.json());
2030
2278
  updateWith({
2031
2279
  amount: subtotal + options[0].amount,
2032
2280
  shippingOptions: options,
2033
2281
  lineItems: [
2034
- { label: 'Subtotal', amount: subtotal },
2282
+ { label: 'Subtotal', amount: subtotal },
2035
2283
  { label: options[0].label, amount: options[0].amount },
2036
2284
  ],
2037
2285
  });
@@ -2047,13 +2295,13 @@ export function ExpressCheckout({ subtotal, onSuccess, onCancel }: Props) {
2047
2295
  method: 'POST',
2048
2296
  headers: { 'Content-Type': 'application/json' },
2049
2297
  body: JSON.stringify({ country: address.country, postalCode: address.postalCode }),
2050
- }).then(r => r.json());
2298
+ }).then((r) => r.json());
2051
2299
 
2052
2300
  updateWith({
2053
2301
  amount: total,
2054
2302
  shippingOptions: options,
2055
2303
  lineItems: [
2056
- { label: 'Subtotal', amount: subtotal },
2304
+ { label: 'Subtotal', amount: subtotal },
2057
2305
  { label: options[0].label, amount: options[0].amount },
2058
2306
  ],
2059
2307
  });
@@ -2064,33 +2312,38 @@ export function ExpressCheckout({ subtotal, onSuccess, onCancel }: Props) {
2064
2312
  updateWith({
2065
2313
  amount: subtotal + shippingOption.amount,
2066
2314
  lineItems: [
2067
- { label: 'Subtotal', amount: subtotal },
2315
+ { label: 'Subtotal', amount: subtotal },
2068
2316
  { label: shippingOption.label, amount: shippingOption.amount },
2069
2317
  ],
2070
2318
  });
2071
2319
  });
2072
2320
 
2073
2321
  // Payment method ready — confirm on backend
2074
- express.on(ExpressSdkEvent.PaymentMethodCreated, async ({ paymentMethodId, idempotencyKey, shippingDetails, selectedShippingOption }) => {
2075
- const { orderId } = await fetch('/api/orders', {
2076
- method: 'POST',
2077
- headers: { 'Content-Type': 'application/json' },
2078
- body: JSON.stringify({
2079
- paymentMethodId,
2080
- idempotencyKey,
2081
- shipping: shippingDetails,
2082
- shippingOptionId: selectedShippingOption?.id,
2083
- }),
2084
- }).then(r => r.json());
2085
-
2086
- onSuccess(orderId);
2087
- });
2322
+ express.on(
2323
+ ExpressSdkEvent.PaymentMethodCreated,
2324
+ async ({ paymentMethodId, idempotencyKey, shippingDetails, selectedShippingOption }) => {
2325
+ const { orderId } = await fetch('/api/orders', {
2326
+ method: 'POST',
2327
+ headers: { 'Content-Type': 'application/json' },
2328
+ body: JSON.stringify({
2329
+ paymentMethodId,
2330
+ idempotencyKey,
2331
+ shipping: shippingDetails,
2332
+ shippingOptionId: selectedShippingOption?.id,
2333
+ }),
2334
+ }).then((r) => r.json());
2335
+
2336
+ onSuccess(orderId);
2337
+ },
2338
+ );
2088
2339
 
2089
2340
  express.on(ExpressSdkEvent.ShippingOptionsRequired, ({ wallet }) => {
2090
2341
  console.error(`${wallet}: session_start timed out — implement the session_start handler`);
2091
2342
  });
2092
2343
 
2093
- express.on(ExpressSdkEvent.PaymentMethodFailed, ({ error }) => console.error('Payment failed:', error));
2344
+ express.on(ExpressSdkEvent.PaymentMethodFailed, ({ error }) =>
2345
+ console.error('Payment failed:', error),
2346
+ );
2094
2347
  express.on(ExpressSdkEvent.Cancel, onCancel);
2095
2348
 
2096
2349
  express.mount(containerRef.current);
@@ -2138,18 +2391,32 @@ express.on('payment_method_created', (event) => {
2138
2391
 
2139
2392
  ```typescript
2140
2393
  interface ExpressPaymentMethodCreatedEvent {
2141
- paymentMethodId: string; // Paypercut PM ID (pm_xxx)
2394
+ paymentMethodId: string; // Paypercut PM ID (pm_xxx)
2142
2395
  token: { id: string; type: 'apple_pay' | 'google_pay' };
2143
2396
  idempotencyKey: string;
2144
2397
  billingDetails?: {
2145
2398
  name?: string;
2146
2399
  email?: string;
2147
2400
  phone?: string;
2148
- address?: { line1?: string; line2?: string; city?: string; state?: string; postalCode?: string; country?: string };
2401
+ address?: {
2402
+ line1?: string;
2403
+ line2?: string;
2404
+ city?: string;
2405
+ state?: string;
2406
+ postalCode?: string;
2407
+ country?: string;
2408
+ };
2149
2409
  };
2150
2410
  shippingDetails?: {
2151
2411
  name?: string;
2152
- address?: { line1?: string; line2?: string; city?: string; state?: string; postalCode?: string; country?: string };
2412
+ address?: {
2413
+ line1?: string;
2414
+ line2?: string;
2415
+ city?: string;
2416
+ state?: string;
2417
+ postalCode?: string;
2418
+ country?: string;
2419
+ };
2153
2420
  };
2154
2421
  selectedShippingOption?: { id: string; label: string; detail?: string; amount: number };
2155
2422
  }
@@ -2162,80 +2429,82 @@ interface ExpressPaymentMethodCreatedEvent {
2162
2429
  ```html
2163
2430
  <!DOCTYPE html>
2164
2431
  <html>
2165
- <head><title>Express Checkout</title></head>
2166
- <body>
2167
- <div id="express-checkout" style="max-width: 400px;"></div>
2168
-
2169
- <script src="https://cdn.jsdelivr.net/npm/@paypercut/checkout-js/dist/paypercut-checkout.iife.min.js"></script>
2170
- <script>
2171
- const express = PaypercutExpressCheckout({
2172
- publishableKey: 'pk_test_...',
2173
- amount: 2500,
2174
- currency: 'EUR',
2175
- countryCode: 'DE',
2176
- shippingOptions: [
2177
- { id: 'standard', label: 'Standard Shipping', detail: '3–5 days', amount: 499 },
2178
- { id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
2179
- ],
2180
- lineItems: [
2181
- { label: 'Subtotal', amount: 2500 },
2182
- { label: 'Standard Shipping', amount: 499 },
2183
- ],
2184
- });
2185
-
2186
- // Wallet buttons ready
2187
- express.on('ready', () => console.log('Express Checkout ready'));
2188
-
2189
- // Shipping address changed — recalculate and respond
2190
- express.on('shipping_address_change', ({ address, updateWith }) => {
2191
- const shippingCost = address.country === 'DE' ? 499 : 799;
2192
- updateWith({
2193
- amount: 2500 + shippingCost,
2432
+ <head>
2433
+ <title>Express Checkout</title>
2434
+ </head>
2435
+ <body>
2436
+ <div id="express-checkout" style="max-width: 400px;"></div>
2437
+
2438
+ <script src="https://cdn.jsdelivr.net/npm/@paypercut/checkout-js/dist/paypercut-checkout.iife.min.js"></script>
2439
+ <script>
2440
+ const express = PaypercutExpressCheckout({
2441
+ publishableKey: 'pk_test_...',
2442
+ amount: 2500,
2443
+ currency: 'EUR',
2444
+ countryCode: 'DE',
2194
2445
  shippingOptions: [
2195
- { id: 'standard', label: 'Standard Shipping', amount: shippingCost },
2196
- { id: 'express', label: 'Express Shipping', amount: shippingCost + 500 },
2446
+ { id: 'standard', label: 'Standard Shipping', detail: '3–5 days', amount: 499 },
2447
+ { id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
2197
2448
  ],
2198
2449
  lineItems: [
2199
2450
  { label: 'Subtotal', amount: 2500 },
2200
- { label: 'Standard Shipping', amount: shippingCost },
2451
+ { label: 'Standard Shipping', amount: 499 },
2201
2452
  ],
2202
2453
  });
2203
- });
2204
2454
 
2205
- // Shipping option changed — update total
2206
- express.on('shipping_option_change', ({ shippingOption, updateWith }) => {
2207
- updateWith({
2208
- amount: 2500 + shippingOption.amount,
2209
- lineItems: [
2210
- { label: 'Subtotal', amount: 2500 },
2211
- { label: shippingOption.label, amount: shippingOption.amount },
2212
- ],
2455
+ // Wallet buttons ready
2456
+ express.on('ready', () => console.log('Express Checkout ready'));
2457
+
2458
+ // Shipping address changed — recalculate and respond
2459
+ express.on('shipping_address_change', ({ address, updateWith }) => {
2460
+ const shippingCost = address.country === 'DE' ? 499 : 799;
2461
+ updateWith({
2462
+ amount: 2500 + shippingCost,
2463
+ shippingOptions: [
2464
+ { id: 'standard', label: 'Standard Shipping', amount: shippingCost },
2465
+ { id: 'express', label: 'Express Shipping', amount: shippingCost + 500 },
2466
+ ],
2467
+ lineItems: [
2468
+ { label: 'Subtotal', amount: 2500 },
2469
+ { label: 'Standard Shipping', amount: shippingCost },
2470
+ ],
2471
+ });
2213
2472
  });
2214
- });
2215
2473
 
2216
- // Payment method created — confirm on backend
2217
- express.on('payment_method_created', async (event) => {
2218
- console.log('Payment method:', event.paymentMethodId);
2219
- console.log('Shipping option:', event.selectedShippingOption?.label);
2220
- await fetch('/api/confirm-payment', {
2221
- method: 'POST',
2222
- headers: { 'Content-Type': 'application/json' },
2223
- body: JSON.stringify({ paymentMethodId: event.paymentMethodId }),
2474
+ // Shipping option changed — update total
2475
+ express.on('shipping_option_change', ({ shippingOption, updateWith }) => {
2476
+ updateWith({
2477
+ amount: 2500 + shippingOption.amount,
2478
+ lineItems: [
2479
+ { label: 'Subtotal', amount: 2500 },
2480
+ { label: shippingOption.label, amount: shippingOption.amount },
2481
+ ],
2482
+ });
2224
2483
  });
2225
- window.location.href = '/success';
2226
- });
2227
2484
 
2228
- express.on('payment_method_failed', ({ error }) => {
2229
- console.error('Payment failed:', error);
2230
- });
2485
+ // Payment method created — confirm on backend
2486
+ express.on('payment_method_created', async (event) => {
2487
+ console.log('Payment method:', event.paymentMethodId);
2488
+ console.log('Shipping option:', event.selectedShippingOption?.label);
2489
+ await fetch('/api/confirm-payment', {
2490
+ method: 'POST',
2491
+ headers: { 'Content-Type': 'application/json' },
2492
+ body: JSON.stringify({ paymentMethodId: event.paymentMethodId }),
2493
+ });
2494
+ window.location.href = '/success';
2495
+ });
2231
2496
 
2232
- express.on('cancel', () => {
2233
- console.log('User dismissed the wallet sheet');
2234
- });
2497
+ express.on('payment_method_failed', ({ error }) => {
2498
+ console.error('Payment failed:', error);
2499
+ });
2500
+
2501
+ express.on('cancel', () => {
2502
+ console.log('User dismissed the wallet sheet');
2503
+ });
2235
2504
 
2236
- express.mount('#express-checkout');
2237
- </script>
2238
- </body>
2505
+ express.mount('#express-checkout');
2506
+ </script>
2507
+ </body>
2239
2508
  </html>
2240
2509
  ```
2241
2510
 
@@ -2245,10 +2514,14 @@ interface ExpressPaymentMethodCreatedEvent {
2245
2514
 
2246
2515
  ```tsx
2247
2516
  import { useEffect, useRef } from 'react';
2248
- import { PaypercutExpressCheckout, ExpressSdkEvent, ExpressCheckoutInstance } from '@paypercut/checkout-js';
2517
+ import {
2518
+ PaypercutExpressCheckout,
2519
+ ExpressSdkEvent,
2520
+ ExpressCheckoutInstance,
2521
+ } from '@paypercut/checkout-js';
2249
2522
 
2250
2523
  interface Props {
2251
- subtotal: number; // minor units
2524
+ subtotal: number; // minor units
2252
2525
  onSuccess: (paymentMethodId: string) => void;
2253
2526
  }
2254
2527
 
@@ -2261,12 +2534,12 @@ export function ExpressCheckoutButton({ subtotal, onSuccess }: Props) {
2261
2534
 
2262
2535
  const express = PaypercutExpressCheckout({
2263
2536
  publishableKey: process.env.NEXT_PUBLIC_PAYPERCUT_KEY!,
2264
- amount: subtotal + 499, // subtotal + default shipping
2537
+ amount: subtotal + 499, // subtotal + default shipping
2265
2538
  currency: 'EUR',
2266
2539
  countryCode: 'DE',
2267
2540
  shippingOptions: [
2268
2541
  { id: 'standard', label: 'Standard Shipping', detail: '3–5 days', amount: 499 },
2269
- { id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
2542
+ { id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
2270
2543
  ],
2271
2544
  });
2272
2545
 
@@ -2276,7 +2549,7 @@ export function ExpressCheckoutButton({ subtotal, onSuccess }: Props) {
2276
2549
  amount: subtotal + shipping,
2277
2550
  shippingOptions: [
2278
2551
  { id: 'standard', label: 'Standard Shipping', amount: shipping },
2279
- { id: 'express', label: 'Express Shipping', amount: shipping + 500 },
2552
+ { id: 'express', label: 'Express Shipping', amount: shipping + 500 },
2280
2553
  ],
2281
2554
  });
2282
2555
  });