@paypercut/checkout-js 1.2.3 → 1.2.5

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
@@ -14,6 +14,10 @@ A lightweight, framework-agnostic JavaScript SDK for embedding Paypercut Checkou
14
14
  - [Installation](#installation)
15
15
  - [Quick Start — Embedded Checkout](#quick-start)
16
16
  - [API Reference — Embedded Checkout](#api-reference)
17
+ - [**Customisation**](#customisation)
18
+ - [Appearance at init time](#appearance-at-init-time)
19
+ - [Dynamic updates — updateAppearance()](#dynamic-updates--updateappearance)
20
+ - [AppearanceVariables reference](#appearancevariables-reference)
17
21
  - [Events — Embedded Checkout](#events)
18
22
  - [Form Validation for Wallet Payments](#form-validation-for-wallet-payments)
19
23
  - [**Express Checkout (Apple Pay / Google Pay)**](#express-checkout-apple-pay--google-pay)
@@ -63,12 +67,12 @@ pnpm add @paypercut/checkout-js
63
67
 
64
68
  ```html
65
69
  <!-- jsDelivr (recommended with SRI) -->
66
- <script src="https://cdn.jsdelivr.net/npm/@paypercut/checkout-js@1.2.3/dist/paypercut-checkout.iife.min.js"
70
+ <script src="https://cdn.jsdelivr.net/npm/@paypercut/checkout-js@1.2.5/dist/paypercut-checkout.iife.min.js"
67
71
  integrity="sha384-..."
68
72
  crossorigin="anonymous"></script>
69
73
 
70
74
  <!-- or UNPKG -->
71
- <script src="https://unpkg.com/@paypercut/checkout-js@1.2.3/dist/paypercut-checkout.iife.min.js"></script>
75
+ <script src="https://unpkg.com/@paypercut/checkout-js@1.2.5/dist/paypercut-checkout.iife.min.js"></script>
72
76
  ```
73
77
 
74
78
  ---
@@ -267,6 +271,113 @@ if (checkout.isMounted()) {
267
271
 
268
272
  ---
269
273
 
274
+ ## Customisation
275
+
276
+ > **Available since v1.2.5**
277
+
278
+ 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
+
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()` |
284
+
285
+ ---
286
+
287
+ ### Appearance at init time
288
+
289
+ Pass an `appearance` object when creating the checkout instance. These values are serialised into the iframe URL so the correct theme and CSS variables are applied before the first paint — no flash of unstyled content.
290
+
291
+ ```ts
292
+ const checkout = PaypercutCheckout({
293
+ id: 'CHK_xxx',
294
+ containerId: '#checkout',
295
+ appearance: {
296
+ theme: 'dark', // 'light' | 'dark'
297
+ preset: 'modal', // 'inline' | 'modal'
298
+ variables: {
299
+ brandColor: '#ff5500', // CTA button background
300
+ fontFamily: 'Inter, sans-serif',
301
+ borderRadius: '12px',
302
+ logoUrl: 'https://cdn.example.com/logo.png',
303
+ },
304
+ },
305
+ });
306
+
307
+ checkout.render();
308
+ ```
309
+
310
+ **`preset`**
311
+
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 |
316
+
317
+ ---
318
+
319
+ ### Dynamic updates — `updateAppearance()`
320
+
321
+ Call `checkout.updateAppearance(appearance)` at any point after `render()` to update the checkout's visual appearance without a full reload. The SDK sends an `UPDATE_APPEARANCE` postMessage to the iframe, which merges the incoming values on top of the current state.
322
+
323
+ ```ts
324
+ // Example: dark-mode toggle on merchant page
325
+ document.getElementById('dark-toggle').addEventListener('change', (e) => {
326
+ checkout.updateAppearance({ theme: e.target.checked ? 'dark' : 'light' });
327
+ });
328
+
329
+ // Example: update brand color after merchant customiser changes
330
+ checkout.updateAppearance({
331
+ variables: {
332
+ brandColor: '#e63946',
333
+ brandColorContrast: '#ffffff',
334
+ },
335
+ });
336
+
337
+ // Example: inject logo after it's fetched asynchronously
338
+ checkout.updateAppearance({
339
+ variables: { logoUrl: 'https://cdn.example.com/logo.png' },
340
+ });
341
+ ```
342
+
343
+ Updates are **merged** — you only need to pass the fields you want to change. Fields omitted from the update are left as-is.
344
+
345
+ > **Note:** `updateAppearance()` requires the checkout to be mounted (`render()` must have been called first). Calling it before `render()` logs a warning and is a no-op.
346
+
347
+ ---
348
+
349
+ ### `AppearanceVariables` reference
350
+
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://`. |
357
+
358
+ `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
+
360
+ ---
361
+
362
+ ### TypeScript types
363
+
364
+ ```ts
365
+ import type { Appearance, AppearanceVariables } from '@paypercut/checkout-js';
366
+
367
+ const appearance: Appearance = {
368
+ theme: 'dark',
369
+ variables: {
370
+ brandColor: '#6366f1',
371
+ fontFamily: 'Inter, sans-serif',
372
+ borderRadius: '10px',
373
+ },
374
+ };
375
+
376
+ checkout.updateAppearance(appearance);
377
+ ```
378
+
379
+ ---
380
+
270
381
  ## Events
271
382
 
272
383
  Subscribe to events using the `on()` method. You can use string event names or the `SdkEvent` enum.
@@ -760,7 +871,7 @@ Tip: Prefer subscribing with the SdkEvent enum for stronger typing.
760
871
  <body>
761
872
  <div id="checkout"></div>
762
873
 
763
- <script src="https://cdn.jsdelivr.net/npm/@paypercut/checkout-js@1.2.3/dist/paypercut-checkout.iife.min.js"></script>
874
+ <script src="https://cdn.jsdelivr.net/npm/@paypercut/checkout-js@1.2.5/dist/paypercut-checkout.iife.min.js"></script>
764
875
  <script>
765
876
  const checkout = PaypercutCheckout({
766
877
  id: '01KB23M9EC960C50G3AH14FTTT',
@@ -1388,7 +1499,7 @@ express.mount('#express-checkout');
1388
1499
  | `shippingOptions` | `ExpressCheckoutShippingOption[]` | Yes | Initial shipping options shown in the wallet sheet. Must include at least one. |
1389
1500
  | `lineItems` | `LineItem[]` | No | Line item breakdown shown in the **Apple Pay** sheet (subtotal, tax, etc.). Ignored by Google Pay. |
1390
1501
  | `walletOptions` | `('apple_pay' \| 'google_pay')[]` | No | Which wallets to show. Defaults to both. |
1391
- | `layout` | `'column' \| 'row'` | No | `'row'` (default) places buttons side by side. `'column'` stacks them vertically. |
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. |
1392
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'`. |
1393
1504
  | `buttonOptions` | `ExpressButtonOptions` | No | Customize the label type and color/style of the wallet buttons. See [Button Options](#button-options) below. |
1394
1505
 
package/dist/index.cjs CHANGED
@@ -91,7 +91,7 @@ class Emitter {
91
91
  * Production configuration (for merchants)
92
92
  */
93
93
  const productionConfig = {
94
- version: "1.2.3",
94
+ version: "1.2.5",
95
95
  defaultCheckoutOrigin: 'https://buy.paypercut.io',
96
96
  defaultApiOrigin: 'https://api.paypercut.io',
97
97
  defaultVaultApiUrl: 'https://api.basistheory.com',
@@ -762,9 +762,14 @@ class ExpressCheckoutImpl {
762
762
  async fetchExpressConfig() {
763
763
  const apiOrigin = getApiOrigin(this.options.apiUrl);
764
764
  const url = new URL('/v1/elements/sessions', apiOrigin);
765
+ const { amount } = this.options;
765
766
  url.searchParams.set('type', 'deferred_intent');
766
767
  url.searchParams.set('key', this.options.publishableKey);
767
768
  url.searchParams.set('deferred_intent[mode]', 'payment');
769
+ url.searchParams.set('deferred_intent[currency]', this.options.currency);
770
+ if (amount != null) {
771
+ url.searchParams.set('deferred_intent[amount]', `${amount}`);
772
+ }
768
773
  url.searchParams.set('referrer_host', window.location.hostname);
769
774
  try {
770
775
  const res = await fetch(url.toString(), { cache: 'no-store' });
@@ -964,8 +969,8 @@ class ExpressCheckoutImpl {
964
969
  : [exports.WalletOption.APPLE_PAY, exports.WalletOption.GOOGLE_PAY];
965
970
  const showApplePay = requestedWallets.includes(exports.WalletOption.APPLE_PAY);
966
971
  const showGooglePay = requestedWallets.includes(exports.WalletOption.GOOGLE_PAY);
967
- // Wrapper — row (default) or column layout; 'auto' uses ResizeObserver
968
- const layoutOption = this.options.layout ?? 'row';
972
+ // Wrapper — auto (default), row, or column layout; 'auto' uses ResizeObserver
973
+ const layoutOption = this.options.layout ?? 'auto';
969
974
  this.preferredLayout = layoutOption === 'auto' ? 'row' : layoutOption;
970
975
  const wrapper = document.createElement('div');
971
976
  this.wrapper = wrapper;
@@ -2008,6 +2013,30 @@ const PaypercutExpressCheckout = function (options) {
2008
2013
  return new ExpressCheckoutImpl(options);
2009
2014
  };
2010
2015
 
2016
+ // ── Appearance validation ─────────────────────────────────────────────────────
2017
+ const _HEX_RE = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
2018
+ const _CSS_LEN_RE = /^(0|(\d+(\.\d+)?(px|rem|em)))$/;
2019
+ function warnInvalidAppearanceVariables(variables) {
2020
+ if (!variables)
2021
+ return;
2022
+ if (variables.brandColor !== undefined && !_HEX_RE.test(variables.brandColor)) {
2023
+ console.warn(`[PaypercutCheckout] Invalid appearance.variables.brandColor: "${variables.brandColor}". ` +
2024
+ `Expected a hex color (#RGB or #RRGGBB). Value ignored.`);
2025
+ }
2026
+ if (variables.fontFamily !== undefined && !variables.fontFamily.trim()) {
2027
+ console.warn(`[PaypercutCheckout] Invalid appearance.variables.fontFamily: value is empty. Value ignored.`);
2028
+ }
2029
+ if (variables.logoUrl !== undefined && !/^https:\/\//.test(variables.logoUrl)) {
2030
+ console.warn(`[PaypercutCheckout] Invalid appearance.variables.logoUrl: "${variables.logoUrl}". ` +
2031
+ `Must start with https://. Value ignored.`);
2032
+ }
2033
+ if (variables.borderRadius !== undefined &&
2034
+ !_CSS_LEN_RE.test(variables.borderRadius.trim())) {
2035
+ console.warn(`[PaypercutCheckout] Invalid appearance.variables.borderRadius: "${variables.borderRadius}". ` +
2036
+ `Expected a CSS length like "8px", "0.5rem", or "0". Value ignored.`);
2037
+ }
2038
+ }
2039
+ // ── Checkout implementation ───────────────────────────────────────────────────
2011
2040
  /**
2012
2041
  * Internal implementation of CheckoutInstance
2013
2042
  */
@@ -2075,6 +2104,13 @@ class CheckoutImpl {
2075
2104
  if (this.options.appearance?.preset) {
2076
2105
  url.searchParams.set('preset', this.options.appearance.preset);
2077
2106
  }
2107
+ if (this.options.appearance?.theme) {
2108
+ url.searchParams.set('theme', this.options.appearance.theme);
2109
+ }
2110
+ if (this.options.appearance?.variables && Object.keys(this.options.appearance.variables).length > 0) {
2111
+ warnInvalidAppearanceVariables(this.options.appearance.variables);
2112
+ url.searchParams.set('appearance_vars', JSON.stringify(this.options.appearance.variables));
2113
+ }
2078
2114
  if (this.options.form_only !== undefined) {
2079
2115
  url.searchParams.set('form_only', String(this.options.form_only));
2080
2116
  }
@@ -2368,6 +2404,21 @@ class CheckoutImpl {
2368
2404
  status: 'success',
2369
2405
  });
2370
2406
  }
2407
+ /**
2408
+ * Dynamically update the checkout appearance after it has been rendered.
2409
+ */
2410
+ updateAppearance(appearance) {
2411
+ if (!this.mounted) {
2412
+ console.warn('[PaypercutCheckout] Cannot update appearance: not mounted');
2413
+ return;
2414
+ }
2415
+ warnInvalidAppearanceVariables(appearance.variables);
2416
+ this.postToIframe({
2417
+ type: 'UPDATE_APPEARANCE',
2418
+ checkoutId: this.options.id,
2419
+ appearance,
2420
+ });
2421
+ }
2371
2422
  /**
2372
2423
  * Fail form validation - prevents wallet payment from starting.
2373
2424
  * Call this in response to 'form_validation' event when merchant form has errors.