@paypercut/checkout-js 1.3.0 → 1.4.0

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.
@@ -0,0 +1,898 @@
1
+ /**
2
+ * Supported locales for Paypercut Checkout
3
+ *
4
+ * @remarks
5
+ * Single source of truth for all supported locale codes.
6
+ *
7
+ * Supported languages:
8
+ * - Bulgarian: 'bg', 'bg-BG'
9
+ * - English: 'en', 'en-GB'
10
+ * - Greek: 'el', 'el-GR'
11
+ * - Romanian: 'ro', 'ro-RO'
12
+ * - Croatian: 'hr', 'hr-HR'
13
+ * - Polish: 'pl', 'pl-PL'
14
+ * - Czech: 'cs', 'cs-CZ'
15
+ * - Slovenian: 'sl', 'sl-SI'
16
+ * - Slovak: 'sk', 'sk-SK'
17
+ *
18
+ * @example
19
+ * ```typescript
20
+ * const checkout = PaypercutCheckout({
21
+ * locale: 'bg' // or 'bg-BG', 'en', 'en-GB', etc.
22
+ * });
23
+ * ```
24
+ */
25
+ declare const LOCALES: readonly ["bg", "bg-BG", "en", "en-GB", "el", "el-GR", "ro", "ro-RO", "hr", "hr-HR", "pl", "pl-PL", "cs", "cs-CZ", "sl", "sl-SI", "sk", "sk-SK", "hu", "hu-HU"];
26
+ /**
27
+ * Locale type - union of all supported locale codes plus 'auto'
28
+ * @example
29
+ * ```typescript
30
+ * const locale: Locale = 'bg';
31
+ * const lang: Locale = 'bg';
32
+ * const autoLocale: Locale = 'auto';
33
+ * ```
34
+ */
35
+ type Locale = typeof LOCALES[number] | 'auto';
36
+
37
+ /**
38
+ * UI mode for checkout
39
+ */
40
+ declare enum UIMode {
41
+ /** Embedded mode - checkout embedded in merchant page */
42
+ EMBEDDED = "embedded"
43
+ }
44
+ /**
45
+ * Payment method types
46
+ */
47
+ declare enum PaymentMethod {
48
+ /** Card payment (credit/debit) */
49
+ CARD = "card"
50
+ }
51
+ /**
52
+ * Wallet options for digital wallets
53
+ */
54
+ declare enum WalletOption {
55
+ /** Apple Pay */
56
+ APPLE_PAY = "apple_pay",
57
+ /** Google Pay */
58
+ GOOGLE_PAY = "google_pay"
59
+ }
60
+ /**
61
+ * Appearance variables for customising the hosted checkout visual style.
62
+ * All fields are optional — only override what you need.
63
+ */
64
+ interface AppearanceVariables {
65
+ /** Primary button / CTA background colour (hex, e.g. '#0066ff') */
66
+ brandColor?: `#${string}`;
67
+ /** Font family for the checkout UI (must be available in the iframe context) */
68
+ fontFamily?: string;
69
+ /** Merchant logo URL shown in the checkout header (https only) */
70
+ logoUrl?: string;
71
+ /** Border radius for checkout panels and payment method selector (e.g. '8px', '0.5rem') */
72
+ borderRadius?: string;
73
+ }
74
+ /**
75
+ * Appearance options for the hosted checkout UI.
76
+ */
77
+ interface Appearance {
78
+ /** Layout preset */
79
+ preset?: 'inline' | 'modal';
80
+ /** Colour theme */
81
+ theme?: 'light' | 'dark';
82
+ /** Fine-grained visual variable overrides */
83
+ variables?: AppearanceVariables;
84
+ }
85
+ /**
86
+ * Configuration options for PaypercutCheckout
87
+ */
88
+ interface PaypercutCheckoutOptions {
89
+ /** Checkout session identifier (e.g., 'CHK_12345') */
90
+ id: string;
91
+ /** CSS selector or HTMLElement where iframe mounts (required) */
92
+ containerId: string | HTMLElement;
93
+ /**
94
+ * Optional: Custom hosted checkout URL (only available in internal builds)
95
+ * Production builds will ignore this option for security
96
+ */
97
+ hostedCheckoutUrl?: string;
98
+ /**
99
+ * Optional: Locale for checkout UI
100
+ * @default 'en'
101
+ */
102
+ locale?: Locale | string;
103
+ /**
104
+ * Optional: Language for checkout UI
105
+ * @default 'en'
106
+ */
107
+ lang?: Locale | string;
108
+ /**
109
+ * Optional: UI mode for checkout
110
+ */
111
+ ui_mode?: UIMode | `${UIMode}`;
112
+ /**
113
+ * Optional: Payment methods to enable
114
+ * @default ['card']
115
+ */
116
+ payment_methods?: (PaymentMethod | `${PaymentMethod}`)[];
117
+ /**
118
+ * Optional: Digital wallet options
119
+ * Can include both or just one
120
+ * Default behaviour - shows both
121
+ */
122
+ wallet_options?: (WalletOption | `${WalletOption}`)[] | [];
123
+ /**
124
+ * Optional: Show only the payment form without header/footer
125
+ * @default false
126
+ */
127
+ form_only?: boolean;
128
+ /**
129
+ * Optional: Appearance options for theming the checkout UI
130
+ */
131
+ appearance?: Appearance;
132
+ /**
133
+ * Optional: Require form validation before wallet payment (Google Pay / Apple Pay)
134
+ * @default false
135
+ */
136
+ validate_form?: boolean;
137
+ }
138
+ /**
139
+ * Wallet type for form validation
140
+ */
141
+ type WalletType = 'apple_pay' | 'google_pay';
142
+ /**
143
+ * Wallet/checkout cancellation event payload
144
+ */
145
+ interface CancelPayload {
146
+ checkoutId: string;
147
+ wallet?: WalletType;
148
+ }
149
+ /**
150
+ * Event names that can be emitted by the checkout
151
+ */
152
+ type EventName = 'loaded' | 'processing' | 'success' | 'error' | 'expired' | 'resize' | 'threeds_complete' | 'threeds_error' | 'threeds_canceled' | 'threeds_started' | 'cancel' | 'form_validation';
153
+ /**
154
+ * Preferred enum for SDK event names (use instead of hardcoded strings)
155
+ */
156
+ declare enum SdkEvent {
157
+ Loaded = "loaded",
158
+ Processing = "processing",
159
+ Success = "success",
160
+ Error = "error",
161
+ Expired = "expired",
162
+ Resize = "resize",
163
+ ThreeDSComplete = "threeds_complete",
164
+ ThreeDSError = "threeds_error",
165
+ ThreeDSCanceled = "threeds_canceled",
166
+ ThreeDSStarted = "threeds_started",
167
+ Cancel = "cancel",
168
+ FormValidation = "form_validation"
169
+ }
170
+ /**
171
+ * Form validation error for failFormValidation
172
+ */
173
+ interface FormValidationError {
174
+ code?: string;
175
+ message?: string;
176
+ }
177
+ /**
178
+ * Checkout instance interface
179
+ */
180
+ interface CheckoutInstance {
181
+ /** Mount and render the iframe into the container */
182
+ render(): void;
183
+ /** Submit payment - sends message to hosted checkout to confirm payment */
184
+ submit(): void;
185
+ /** Destroy instance and cleanup all listeners */
186
+ destroy(): void;
187
+ /** Subscribe to events. Returns unsubscribe function */
188
+ on(event: EventName | SdkEvent, handler: (...args: any[]) => void): () => void;
189
+ /** Subscribe to event that auto-unsubscribes after first emission */
190
+ once(event: EventName | SdkEvent, handler: (...args: any[]) => void): () => void;
191
+ /** Unsubscribe from events */
192
+ off(event: EventName | SdkEvent, handler: (...args: any[]) => void): void;
193
+ /** Check if checkout is currently mounted */
194
+ isMounted(): boolean;
195
+ /**
196
+ * Complete form validation successfully - allows wallet payment to proceed.
197
+ * Call this in response to 'form_validation' event when merchant form is valid.
198
+ * @param wallet - The wallet type that requested validation ('apple_pay' | 'google_pay')
199
+ */
200
+ completeFormValidation(wallet: WalletType): void;
201
+ /**
202
+ * Fail form validation - prevents wallet payment from starting.
203
+ * Call this in response to 'form_validation' event when merchant form has errors.
204
+ * @param wallet - The wallet type that requested validation ('apple_pay' | 'google_pay')
205
+ * @param errors - Optional array of validation errors to pass back
206
+ */
207
+ failFormValidation(wallet: WalletType, errors?: FormValidationError[]): void;
208
+ /**
209
+ * Dynamically update the checkout appearance after it has been rendered.
210
+ * Useful for syncing the checkout theme with the merchant page (e.g. dark mode toggle).
211
+ * @param appearance - Partial appearance options to merge into the current appearance
212
+ */
213
+ updateAppearance(appearance: Appearance): void;
214
+ }
215
+ /**
216
+ * PaypercutCheckout static interface (callable and constructable)
217
+ */
218
+ interface PaypercutCheckoutStatic {
219
+ /** Callable factory function */
220
+ (options: PaypercutCheckoutOptions): CheckoutInstance;
221
+ /** Constructor support */
222
+ new (options: PaypercutCheckoutOptions): CheckoutInstance;
223
+ /** SDK version */
224
+ version: string;
225
+ }
226
+
227
+ /**
228
+ * ISO 639-1 two-letter language codes supported by the Express Checkout wallet buttons.
229
+ *
230
+ * Pass one of these to `locale` in the options or to `setLocale()` after mount.
231
+ * Each wallet applies the locale independently:
232
+ * - Apple Pay supports all values in this list.
233
+ * - Google Pay supports most; unsupported languages (e.g. 'ro', 'hu') fall back to 'en'.
234
+ */
235
+ declare const EXPRESS_LOCALES: readonly ["bg", "cs", "el", "en", "hr", "hu", "pl", "ro", "sk", "sl"];
236
+ type ExpressLocale = typeof EXPRESS_LOCALES[number];
237
+ /** Line item shown in the Apple Pay payment sheet breakdown. Not used by Google Pay. */
238
+ interface LineItem {
239
+ label: string;
240
+ /** Amount in minor units (e.g. 1200 = 12.00) */
241
+ amount: number;
242
+ type?: 'final' | 'pending';
243
+ }
244
+ interface ExpressCheckoutShippingOption {
245
+ id: string;
246
+ label: string;
247
+ detail?: string;
248
+ /** Amount in minor units */
249
+ amount: number;
250
+ }
251
+ type ExpressButtonType = 'buy' | 'pay' | 'plain' | 'donate' | 'checkout' | 'subscribe' | 'book' | 'order' | 'tip' | 'contribute';
252
+ type ApplePayButtonStyle = 'black' | 'white' | 'white-outline';
253
+ type GooglePayButtonColor = 'default' | 'black' | 'white';
254
+ interface ExpressButtonOptions {
255
+ /**
256
+ * Button label type shown on both Apple Pay and Google Pay buttons.
257
+ * @default 'plain'
258
+ */
259
+ type?: ExpressButtonType;
260
+ /**
261
+ * Apple Pay button color style.
262
+ * @default 'black'
263
+ */
264
+ applePayStyle?: ApplePayButtonStyle;
265
+ /**
266
+ * Google Pay button color.
267
+ * @default 'default'
268
+ */
269
+ googlePayColor?: GooglePayButtonColor;
270
+ /**
271
+ * Border radius applied to both Apple Pay and Google Pay buttons.
272
+ * Accepts any valid CSS border-radius value (e.g. '0.5rem', '8px', '50%').
273
+ * @default '0.5rem'
274
+ */
275
+ borderRadius?: string;
276
+ }
277
+ interface ExpressCheckoutOptions {
278
+ /** Publishable API key */
279
+ publishableKey: string;
280
+ /** Amount in minor units (e.g. 1200 = €12.00) */
281
+ amount: number;
282
+ /** ISO 4217 currency code (e.g. 'EUR', 'BGN') */
283
+ currency: string;
284
+ /** @default 'payment' */
285
+ mode?: 'payment';
286
+ /**
287
+ * Line items shown in the payment sheet breakdown (subtotal, tax, etc.).
288
+ * Currently displayed by Apple Pay only — Google Pay shows the total only and ignores this field.
289
+ */
290
+ lineItems?: LineItem[];
291
+ /** Initial shipping options. Can be updated via updateWith() */
292
+ shippingOptions?: ExpressCheckoutShippingOption[];
293
+ /** Request shipping address from the wallet sheet */
294
+ requestShipping?: boolean;
295
+ /** Request email from the wallet sheet */
296
+ requestEmail?: boolean;
297
+ /** Request cardholder name from the wallet sheet */
298
+ requestName?: boolean;
299
+ /** ISO 3166-1 alpha-2 country code (e.g. 'DE'). Used in wallet payment requests. */
300
+ countryCode?: string;
301
+ /**
302
+ * ISO 3166-1 alpha-2 country codes the merchant ships to (e.g. ['DE', 'AT', 'CH']).
303
+ * Google Pay only — restricts the address picker so users cannot select unsupported countries.
304
+ * Apple Pay does not support pre-filtering; use `status: 'invalid_shipping_address'`
305
+ * in your `shipping_address_change` handler to reject unsupported addresses at runtime.
306
+ */
307
+ allowedCountries?: string[];
308
+ /** Wallets to enable. Defaults to both Apple Pay and Google Pay */
309
+ walletOptions?: (WalletOption | `${WalletOption}`)[];
310
+ /**
311
+ * Layout of the wallet buttons.
312
+ * - 'row' (default) — buttons side by side, each equal width
313
+ * - 'column' — buttons stacked vertically, each full width
314
+ * - 'auto' — SDK observes container width: column at ≤540px, row above
315
+ */
316
+ layout?: 'column' | 'row' | 'auto';
317
+ /**
318
+ * ISO 639-1 two-letter language code for the wallet button labels (e.g. `'en'`, `'bg'`, `'pl'`).
319
+ * Can be changed after mount via `setLocale()`. Unsupported values fall back to `'en'`.
320
+ * See `ExpressLocale` for the full list of supported codes.
321
+ */
322
+ locale?: ExpressLocale | string;
323
+ /**
324
+ * Customize the wallet button appearance.
325
+ */
326
+ buttonOptions?: ExpressButtonOptions;
327
+ /**
328
+ * Override hosted checkout URL (only available in internal builds).
329
+ * Ignored in production builds.
330
+ */
331
+ hostedCheckoutUrl?: string;
332
+ /**
333
+ * Override Paypercut API URL (only available in internal builds).
334
+ * Ignored in production builds.
335
+ */
336
+ apiUrl?: string;
337
+ }
338
+ interface ExpressCheckoutUpdateOptions {
339
+ /** Updated total amount in minor units */
340
+ amount?: number;
341
+ /** Updated line items (breakdown rows). Currently used by Apple Pay only — ignored by Google Pay. */
342
+ lineItems?: LineItem[];
343
+ /** Updated shipping options */
344
+ shippingOptions?: ExpressCheckoutShippingOption[];
345
+ /**
346
+ * Result status to report back to the wallet.
347
+ * Use 'invalid_shipping_address' / 'invalid_shipping_option' to show an error
348
+ * in the wallet sheet without closing it.
349
+ * @default 'success'
350
+ */
351
+ status?: 'success' | 'fail' | 'invalid_shipping_address' | 'invalid_shipping_option';
352
+ }
353
+ interface ExpressShippingAddress {
354
+ country: string;
355
+ state?: string;
356
+ city?: string;
357
+ postalCode?: string;
358
+ }
359
+ interface ShippingAddressChangeEvent {
360
+ address: ExpressShippingAddress;
361
+ /**
362
+ * Call this with updated totals and shipping options.
363
+ * Must be called to unblock the wallet sheet.
364
+ */
365
+ updateWith: (options: ExpressCheckoutUpdateOptions) => void;
366
+ }
367
+ interface ShippingOptionChangeEvent {
368
+ shippingOption: ExpressCheckoutShippingOption;
369
+ /**
370
+ * Call this with updated totals.
371
+ * Must be called to unblock the wallet sheet.
372
+ */
373
+ updateWith: (options: ExpressCheckoutUpdateOptions) => void;
374
+ }
375
+ interface ExpressTokenPayload {
376
+ id: string;
377
+ type: 'apple_pay' | 'google_pay';
378
+ }
379
+ interface ExpressBillingDetails {
380
+ name?: string;
381
+ email?: string;
382
+ phone?: string;
383
+ address?: {
384
+ line1?: string;
385
+ line2?: string;
386
+ city?: string;
387
+ state?: string;
388
+ postalCode?: string;
389
+ country?: string;
390
+ };
391
+ }
392
+ interface ExpressShippingDetails {
393
+ name?: string;
394
+ address?: {
395
+ line1?: string;
396
+ line2?: string;
397
+ city?: string;
398
+ state?: string;
399
+ postalCode?: string;
400
+ country?: string;
401
+ };
402
+ }
403
+ interface ExpressSessionStartEvent {
404
+ /** Which wallet opened */
405
+ wallet: 'apple_pay' | 'google_pay';
406
+ /**
407
+ * Call this with your initial shipping options and amount.
408
+ * Must be called to unblock the wallet sheet.
409
+ * Identical signature to the updateWith() in shipping change events.
410
+ */
411
+ updateWith: (options: ExpressCheckoutUpdateOptions) => void;
412
+ }
413
+ interface ExpressPaymentMethodCreatedEvent {
414
+ /** Paypercut payment method ID — use this server-side to confirm the payment */
415
+ paymentMethodId: string;
416
+ /** Which wallet was used */
417
+ wallet: 'apple_pay' | 'google_pay';
418
+ billingDetails?: ExpressBillingDetails;
419
+ shippingDetails?: ExpressShippingDetails;
420
+ selectedShippingOption?: ExpressCheckoutShippingOption;
421
+ }
422
+ interface ExpressPaymentMethodFailedEvent {
423
+ error: string;
424
+ }
425
+ type ExpressEventName = 'ready' | 'click' | 'session_start' | 'shipping_options_required' | 'shipping_address_change' | 'shipping_option_change' | 'payment_method_created' | 'payment_method_failed' | 'cancel' | 'error';
426
+ declare enum ExpressSdkEvent {
427
+ Ready = "ready",
428
+ Click = "click",
429
+ SessionStart = "session_start",
430
+ ShippingOptionsRequired = "shipping_options_required",
431
+ ShippingAddressChange = "shipping_address_change",
432
+ ShippingOptionChange = "shipping_option_change",
433
+ PaymentMethodCreated = "payment_method_created",
434
+ PaymentMethodFailed = "payment_method_failed",
435
+ Cancel = "cancel",
436
+ Error = "error"
437
+ }
438
+ interface ExpressCheckoutInstance {
439
+ /** Mount the wallet button iframe into a container */
440
+ mount(container: HTMLElement | string): void;
441
+ /** Subscribe to events. Returns unsubscribe function */
442
+ on(event: 'ready', handler: () => void): () => void;
443
+ on(event: 'click', handler: () => void): () => void;
444
+ on(event: 'session_start', handler: (e: ExpressSessionStartEvent) => void): () => void;
445
+ on(event: 'shipping_options_required', handler: (e: {
446
+ wallet: 'apple_pay' | 'google_pay';
447
+ }) => void): () => void;
448
+ on(event: 'shipping_address_change', handler: (e: ShippingAddressChangeEvent) => void): () => void;
449
+ on(event: 'shipping_option_change', handler: (e: ShippingOptionChangeEvent) => void): () => void;
450
+ on(event: 'payment_method_created', handler: (e: ExpressPaymentMethodCreatedEvent) => void): () => void;
451
+ on(event: 'payment_method_failed', handler: (e: ExpressPaymentMethodFailedEvent) => void): () => void;
452
+ on(event: 'cancel', handler: () => void): () => void;
453
+ on(event: 'error', handler: (err: Error) => void): () => void;
454
+ on(event: ExpressEventName, handler: (...args: any[]) => void): () => void;
455
+ /**
456
+ * Push updated totals / shipping options into the wallet sheet.
457
+ * Call this after calculating shipping in response to shipping_address_change
458
+ * or shipping_option_change (via the event's updateWith() helper).
459
+ */
460
+ update(options: ExpressCheckoutUpdateOptions): void;
461
+ /**
462
+ * Dynamically change the button layout after mount.
463
+ * 'row' places buttons side by side, 'column' stacks them vertically.
464
+ */
465
+ setLayout(layout: 'row' | 'column'): void;
466
+ /**
467
+ * Dynamically change the locale of the wallet buttons after mount.
468
+ */
469
+ setLocale(locale: string): void;
470
+ /**
471
+ * Dynamically update button appearance after mount.
472
+ * Merges with existing buttonOptions — only the fields you pass are changed.
473
+ */
474
+ setButtonOptions(opts: Partial<ExpressButtonOptions>): void;
475
+ /** Destroy instance and clean up all listeners */
476
+ destroy(): void;
477
+ }
478
+ interface ExpressCheckoutStatic {
479
+ (options: ExpressCheckoutOptions): ExpressCheckoutInstance;
480
+ new (options: ExpressCheckoutOptions): ExpressCheckoutInstance;
481
+ }
482
+
483
+ /** Options used to initialise the Paypercut browser client. */
484
+ interface PaypercutOptions {
485
+ /** Public browser credential. The value is opaque; Paycore resolves its account and livemode. */
486
+ publishableKey: string;
487
+ /** Internal builds only. Production builds ignore this override. */
488
+ hostedCheckoutUrl?: string;
489
+ /** Internal builds only. Production builds ignore this override. */
490
+ apiUrl?: string;
491
+ /** Enables the optional Developer Assistant integration tool. Defaults to false. */
492
+ developerAssistant?: boolean;
493
+ }
494
+ /** Browser-side intent prepared by one Elements group. */
495
+ type PaypercutElementsMode = 'payment' | 'setup' | 'subscription';
496
+ /** Lifecycle policy for Appearance updates after an Element has mounted. */
497
+ type PaypercutElementsAppearanceUpdates = 'locked' | 'remount';
498
+ /** Initial configuration shared by the Elements group. */
499
+ interface PaypercutElementsOptions {
500
+ mode: PaypercutElementsMode;
501
+ /** Amount in minor units. */
502
+ amount: number;
503
+ /** ISO 4217 alphabetic currency code. */
504
+ currency: string;
505
+ /**
506
+ * Declares how a card prepared by this Elements group is expected to be
507
+ * reused. Omit in payment mode for one-time use. Setup and subscription
508
+ * modes always resolve to off_session.
509
+ *
510
+ * This does not create or confirm a SetupIntent or PaymentIntent.
511
+ */
512
+ setupFutureUsage?: PaypercutSetupFutureUsage;
513
+ locale?: Locale | string;
514
+ /**
515
+ * Controls mounted Appearance changes. Defaults to `locked`. Use `remount`
516
+ * only for integration previews; it temporarily makes payment fields
517
+ * unavailable and clears entered secure-field data.
518
+ */
519
+ appearanceUpdates?: PaypercutElementsAppearanceUpdates;
520
+ appearance?: PaypercutElementsAppearance;
521
+ }
522
+ /** Visual configuration shared by every component in one Elements group. */
523
+ type PaypercutElementsAppearanceVariableName = 'colorPrimary' | 'colorPrimaryText' | 'colorBackground' | 'colorSurface' | 'colorText' | 'colorTextSecondary' | 'colorTextPlaceholder' | 'colorDanger' | 'colorSuccess' | 'colorWarning' | 'colorBorder' | 'colorFocus' | 'colorMuted' | 'fontFamily' | 'fontSizeBase' | 'fontWeightNormal' | 'fontWeightMedium' | 'lineHeight' | 'spacingUnit' | 'gridColumnSpacing' | 'gridRowSpacing' | 'labelSpacing' | 'borderRadius' | 'buttonBorderRadius' | 'buttonExpressCheckoutBorderRadius' | 'buttonPadding';
524
+ type PaypercutElementsAppearanceVariables = Partial<Record<PaypercutElementsAppearanceVariableName, string>>;
525
+ type PaypercutElementsAppearanceRuleSelector = '.Input' | '.Input--invalid' | '.Input:focus' | '.Label' | '.Error' | '.Text' | '.WalletButton' | '.WalletButton--applePay' | '.WalletButton--googlePay' | '.ActionShell';
526
+ type PaypercutElementsAppearanceRuleProperty = 'backgroundColor' | 'borderColor' | 'borderRadius' | 'borderStyle' | 'borderWidth' | 'borderTopColor' | 'borderTopLeftRadius' | 'borderTopRightRadius' | 'borderTopStyle' | 'borderTopWidth' | 'borderRightColor' | 'borderRightStyle' | 'borderRightWidth' | 'borderBottomColor' | 'borderBottomLeftRadius' | 'borderBottomRightRadius' | 'borderBottomStyle' | 'borderBottomWidth' | 'borderLeftColor' | 'borderLeftStyle' | 'borderLeftWidth' | 'boxShadow' | 'color' | 'fontFamily' | 'fontSize' | 'fontWeight' | 'letterSpacing' | 'lineHeight' | 'opacity' | 'outline' | 'outlineOffset' | 'padding' | 'paddingTop' | 'paddingRight' | 'paddingBottom' | 'paddingLeft' | 'textDecoration' | 'textShadow' | 'textTransform' | 'transition';
527
+ type PaypercutElementsAppearanceRules = Partial<Record<PaypercutElementsAppearanceRuleSelector, Partial<Record<PaypercutElementsAppearanceRuleProperty, string>>>>;
528
+ interface PaypercutElementsAppearance {
529
+ /** Light is the default. */
530
+ theme?: 'light' | 'dark';
531
+ /** Condensed keeps all card fields on one line; spaced renders separate secure inputs. */
532
+ inputs?: 'condensed' | 'spaced';
533
+ /**
534
+ * Auto places labels above spaced inputs and uses in-field labels for condensed inputs.
535
+ */
536
+ labels?: 'auto' | 'above' | 'floating';
537
+ /** Fine-grained visual variables layered on top of the selected theme. */
538
+ variables?: PaypercutElementsAppearanceVariables;
539
+ /** Semantic, allow-listed component rules. Arbitrary CSS selectors are rejected. */
540
+ rules?: PaypercutElementsAppearanceRules;
541
+ /** Disable non-essential transitions and animations inside every Elements frame. */
542
+ disableAnimations?: boolean;
543
+ }
544
+ /** Mutable configuration for an existing Elements group. */
545
+ interface PaypercutElementsUpdateOptions {
546
+ /** Updated amount in minor units. Currency remains immutable for the lifetime of the group. */
547
+ amount?: number;
548
+ /**
549
+ * Partial Appearance update. Accepted before the first mount. After mounting,
550
+ * the default locked policy skips it while still applying independent fields.
551
+ */
552
+ appearance?: PaypercutElementsAppearance;
553
+ }
554
+ interface ElementsResizeEvent {
555
+ height: number;
556
+ }
557
+ /** Stable error codes emitted by the current Paypercut Elements implementation. */
558
+ type KnownElementsErrorCode = 'elements_payment_details_incomplete' | 'elements_payment_details_invalid' | 'elements_payment_method_creation_failed' | 'elements_destroyed' | 'elements_not_mounted' | 'elements_not_ready' | 'elements_reinitialized' | 'elements_initialization_invalid' | 'elements_locale_invalid' | 'elements_controller_failed' | 'elements_component_configuration_invalid' | 'elements_component_connect_failed' | 'elements_component_attach_failed' | 'elements_component_initialization_timeout' | 'elements_component_not_ready' | 'elements_provider_initialization_failed' | 'elements_provider_update_failed' | 'elements_session_expired' | 'elements_session_binding_mismatch' | 'elements_session_verification_failed' | 'elements_submission_in_progress' | 'elements_submit_in_progress' | 'elements_submit_required' | 'elements_test_preset_in_progress' | 'elements_submission_failed' | 'elements_submit_failed' | 'elements_submit_indeterminate' | 'elements_submit_invalid_response' | 'elements_submit_timeout' | 'elements_action_canceled' | 'elements_action_channel_unavailable' | 'elements_action_challenge_failed' | 'elements_action_in_progress' | 'elements_action_timeout' | 'elements_action_shell_timeout' | 'elements_client_secret_invalid' | 'elements_checkout_confirmation_failed' | 'elements_checkout_status_failed' | 'elements_checkout_status_invalid' | 'elements_next_action_invalid' | 'elements_next_action_loop' | 'elements_next_action_unsupported' | 'elements_payment_confirmation_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' | 'elements_card_field_duplicate' | 'elements_card_fields_incomplete' | 'elements_tokenization_duplicate' | 'elements_tokenization_timeout' | 'elements_component_conflict' | 'elements_capability_unsupported' | 'elements_apple_pay_start_failed' | 'elements_apple_pay_unavailable' | 'elements_google_pay_failed' | 'elements_google_pay_request_invalid' | 'elements_google_pay_unavailable';
559
+ /**
560
+ * Elements error code. The open string member permits newer hosted components
561
+ * to add codes without requiring a synchronous merchant SDK upgrade.
562
+ */
563
+ type ElementsErrorCode = KnownElementsErrorCode | (string & Record<never, never>);
564
+ interface ElementsErrorEvent {
565
+ code: ElementsErrorCode;
566
+ message: string;
567
+ recoverable?: boolean;
568
+ }
569
+ /** Server-consumable Payment Method produced without creating a Checkout Session. */
570
+ interface DeferredPaymentReference {
571
+ type: 'payment_method';
572
+ /** Opaque Payment Method identifier. */
573
+ id: string;
574
+ }
575
+ /** Intended reuse context shared by every Payment Method created from one Elements group. */
576
+ type PaypercutSetupFutureUsage = 'on_session' | 'off_session';
577
+ /** Billing address associated with the Payment Method being created. */
578
+ interface PaypercutBillingAddress {
579
+ line1?: string;
580
+ line2?: string;
581
+ city?: string;
582
+ state?: string;
583
+ postal_code?: string;
584
+ /** ISO 3166-1 alpha-2 country code. */
585
+ country?: string;
586
+ }
587
+ /** Billing identity associated with one Payment Method creation attempt. */
588
+ interface PaypercutBillingDetails {
589
+ name?: string;
590
+ email?: string;
591
+ phone?: string;
592
+ address?: PaypercutBillingAddress;
593
+ }
594
+ interface PaypercutCreatePaymentMethodParams {
595
+ billing_details: PaypercutBillingDetails;
596
+ }
597
+ /** Input for creating a Payment Method from one validated Elements group. */
598
+ interface PaypercutCreatePaymentMethodOptions {
599
+ elements: PaypercutElements;
600
+ /** Payment Method-owned billing details. They are frozen into the submission identity. */
601
+ params?: PaypercutCreatePaymentMethodParams;
602
+ }
603
+ /** Input for resuming a server-started payment through its opaque client capability. */
604
+ interface PaypercutConfirmPaymentOptions {
605
+ clientSecret: string;
606
+ }
607
+ /** Authoritative Checkout Session state returned by payment confirmation. */
608
+ interface PaypercutConfirmPaymentResult {
609
+ checkoutSession: {
610
+ id: string;
611
+ status: 'active' | 'completed' | 'expired' | 'canceled';
612
+ paymentStatus: 'failed' | 'no_payment_required' | 'paid' | 'processing' | 'unpaid';
613
+ paymentObjectStatus: 'canceled' | 'expired' | 'processing' | 'requires_action' | 'requires_capture' | 'requires_confirmation' | 'requires_payment_method' | 'succeeded' | null;
614
+ };
615
+ }
616
+ /** Typed rejection returned by Elements validation or Payment Method creation. */
617
+ interface ElementsSubmitError extends Error {
618
+ code: ElementsErrorCode;
619
+ recoverable: boolean;
620
+ }
621
+ type CardElementEventName = 'ready' | 'resize' | 'error';
622
+ /** Card-only surface coordinated by one hidden Elements controller. */
623
+ interface CardElement {
624
+ mount(target: string | HTMLElement): void;
625
+ on(event: 'ready', handler: () => void): () => void;
626
+ on(event: 'resize', handler: (event: ElementsResizeEvent) => void): () => void;
627
+ on(event: 'error', handler: (event: ElementsErrorEvent) => void): () => void;
628
+ on(event: CardElementEventName, handler: ((event: ElementsResizeEvent | ElementsErrorEvent) => void) | (() => void)): () => void;
629
+ destroy(): void;
630
+ }
631
+ type CardFieldElementType = 'cardNumber' | 'cardExpiry' | 'cardCvc';
632
+ type CardFieldElementEventName = 'ready' | 'change' | 'focus' | 'blur' | 'error';
633
+ /** PCI-safe state emitted by a split card field. Raw field values never enter this event. */
634
+ interface CardFieldChangeEvent {
635
+ complete: boolean;
636
+ empty: boolean;
637
+ /** Present only for the card-number field after the provider detects a brand. */
638
+ brand?: string;
639
+ error?: {
640
+ type: 'incomplete' | 'invalid';
641
+ message: string;
642
+ };
643
+ }
644
+ /** Shared lifecycle for a Paypercut-hosted secure card field. */
645
+ interface CardFieldElement {
646
+ readonly type: CardFieldElementType;
647
+ mount(target: string | HTMLElement): void;
648
+ clear(): void;
649
+ focus(): void;
650
+ blur(): void;
651
+ on(event: 'ready', handler: () => void): () => void;
652
+ on(event: 'change', handler: (event: CardFieldChangeEvent) => void): () => void;
653
+ on(event: 'focus' | 'blur', handler: () => void): () => void;
654
+ on(event: 'error', handler: (event: ElementsErrorEvent) => void): () => void;
655
+ destroy(): void;
656
+ }
657
+ /** Creation options for the split card-number field. */
658
+ interface CardNumberElementOptions {
659
+ /**
660
+ * Show Paypercut's accepted-card, detected-brand, and invalid-card badges.
661
+ * Defaults to true. Set to false to remove the adornment and reclaim its space.
662
+ */
663
+ showIcon?: boolean;
664
+ }
665
+ interface CardNumberElement extends CardFieldElement {
666
+ readonly type: 'cardNumber';
667
+ }
668
+ interface CardExpiryElement extends CardFieldElement {
669
+ readonly type: 'cardExpiry';
670
+ }
671
+ interface CardCvcElement extends CardFieldElement {
672
+ readonly type: 'cardCvc';
673
+ }
674
+ /** Wallets currently implemented by the Express Checkout Element. */
675
+ type ExpressCheckoutWallet = 'apple_pay' | 'google_pay';
676
+ /** Browser-safe display data for a wallet-backed Payment Method. */
677
+ interface ExpressCheckoutPaymentMethodPreview {
678
+ type: 'card';
679
+ brand: string;
680
+ displayBrand: string;
681
+ last4: string;
682
+ expMonth?: number;
683
+ expYear?: number;
684
+ wallet: ExpressCheckoutWallet;
685
+ }
686
+ /** Controls whether a wallet is considered when the hosted component checks availability. */
687
+ type ExpressCheckoutPaymentMethodVisibility = 'auto' | 'always' | 'never';
688
+ interface ExpressCheckoutElementOptions {
689
+ paymentMethods?: {
690
+ applePay?: ExpressCheckoutPaymentMethodVisibility;
691
+ googlePay?: ExpressCheckoutPaymentMethodVisibility;
692
+ };
693
+ layout?: {
694
+ maxColumns?: number;
695
+ maxRows?: number;
696
+ overflow?: 'auto' | 'never';
697
+ };
698
+ buttonType?: {
699
+ applePay?: 'plain' | 'buy' | 'check-out' | 'donate' | 'book' | 'subscribe';
700
+ googlePay?: 'plain' | 'pay' | 'buy' | 'checkout' | 'donate' | 'book' | 'subscribe';
701
+ };
702
+ buttonTheme?: {
703
+ applePay?: 'black' | 'white' | 'white-outline';
704
+ googlePay?: 'black' | 'white';
705
+ };
706
+ /** Button height in CSS pixels. */
707
+ buttonHeight?: number;
708
+ /** Corner radius shared by every provider button, in CSS pixels. Defaults to 4. */
709
+ buttonRadius?: number;
710
+ emailRequired?: boolean;
711
+ phoneNumberRequired?: boolean;
712
+ billingAddressRequired?: boolean;
713
+ shippingAddressRequired?: boolean;
714
+ allowedShippingCountries?: string[];
715
+ lineItems?: ExpressCheckoutLineItem[];
716
+ /** Initial rates shown by wallets that require rates before their sheet opens. */
717
+ shippingRates?: ExpressCheckoutShippingRate[];
718
+ }
719
+ interface ExpressCheckoutLineItem {
720
+ name: string;
721
+ amount: number;
722
+ }
723
+ /** One merchant shipping choice. Amount is expressed in minor currency units. */
724
+ interface ExpressCheckoutShippingRate {
725
+ id: string;
726
+ displayName: string;
727
+ amount: number;
728
+ /** Optional detailed shipping note returned by some providers. */
729
+ detail?: string;
730
+ }
731
+ /**
732
+ * Redacted shipping address supplied while the wallet sheet is open. Wallets
733
+ * may omit fields until the customer authorizes the payment.
734
+ */
735
+ interface ExpressCheckoutShippingAddress {
736
+ recipient?: string;
737
+ addressLine?: string[];
738
+ city?: string;
739
+ state?: string;
740
+ postalCode?: string;
741
+ country?: string;
742
+ }
743
+ interface ExpressCheckoutAddress {
744
+ /** @deprecated The contact name belongs on billingDetails or shippingAddress. */
745
+ name?: string;
746
+ line1?: string;
747
+ line2?: string;
748
+ city?: string;
749
+ state?: string;
750
+ postalCode?: string;
751
+ country?: string;
752
+ }
753
+ /** Final, unredacted shipping details returned after wallet authorization. */
754
+ interface ExpressCheckoutShippingDetails {
755
+ name?: string;
756
+ address?: ExpressCheckoutAddress;
757
+ }
758
+ interface ExpressCheckoutBillingDetails {
759
+ name?: string;
760
+ email?: string;
761
+ phone?: string;
762
+ address?: ExpressCheckoutAddress;
763
+ }
764
+ interface ExpressCheckoutAvailablePaymentMethodsChangeEvent {
765
+ availablePaymentMethods: {
766
+ applePay: boolean;
767
+ googlePay: boolean;
768
+ };
769
+ }
770
+ interface ExpressCheckoutConfirmEvent {
771
+ wallet: ExpressCheckoutWallet;
772
+ paymentMethod: DeferredPaymentReference;
773
+ paymentMethodPreview?: ExpressCheckoutPaymentMethodPreview;
774
+ billingDetails?: ExpressCheckoutBillingDetails;
775
+ shippingAddress?: ExpressCheckoutShippingDetails;
776
+ /** The final wallet-selected shipping rate, when shipping collection is enabled. */
777
+ shippingRate?: ExpressCheckoutShippingRate;
778
+ /** Complete the native wallet after the merchant accepts the prepared method or checkout. */
779
+ complete(): void;
780
+ /** Fail the native wallet after the merchant rejects preparation, payment, or order creation. */
781
+ paymentFailed(error?: {
782
+ code?: string;
783
+ message?: string;
784
+ }): void;
785
+ }
786
+ interface ExpressCheckoutCancelEvent {
787
+ wallet: ExpressCheckoutWallet;
788
+ }
789
+ /**
790
+ * Emitted before a wallet attempt is allowed to continue. Call exactly one of
791
+ * resolve() or reject(). When no click listener is registered, the Element
792
+ * continues automatically.
793
+ */
794
+ interface ExpressCheckoutClickEvent {
795
+ wallet: ExpressCheckoutWallet;
796
+ resolve(options?: ExpressCheckoutClickResolveOptions): void;
797
+ reject(): void;
798
+ }
799
+ /** Current checkout details supplied immediately before a wallet is opened. */
800
+ interface ExpressCheckoutClickResolveOptions {
801
+ lineItems?: ExpressCheckoutLineItem[];
802
+ emailRequired?: boolean;
803
+ phoneNumberRequired?: boolean;
804
+ billingAddressRequired?: boolean;
805
+ shippingAddressRequired?: boolean;
806
+ allowedShippingCountries?: string[];
807
+ shippingRates?: ExpressCheckoutShippingRate[];
808
+ }
809
+ /**
810
+ * Mutable checkout data for an already mounted Express Checkout Element.
811
+ *
812
+ * Provider selection, layout, and button styling remain immutable for the
813
+ * lifetime of the Element. Commerce state can be replaced before the next
814
+ * wallet gesture without remounting the secure component.
815
+ */
816
+ type ExpressCheckoutElementUpdateOptions = ExpressCheckoutClickResolveOptions;
817
+ /** Updated checkout details returned after a wallet address or rate changes. */
818
+ interface ExpressCheckoutShippingUpdate {
819
+ /** Recalculated order total in the group's currency, in minor units. */
820
+ amount?: number;
821
+ lineItems?: ExpressCheckoutLineItem[];
822
+ shippingRates?: ExpressCheckoutShippingRate[];
823
+ }
824
+ interface ExpressCheckoutShippingAddressChangeEvent {
825
+ wallet: ExpressCheckoutWallet;
826
+ address: ExpressCheckoutShippingAddress;
827
+ resolve(update?: ExpressCheckoutShippingUpdate): void;
828
+ reject(): void;
829
+ }
830
+ interface ExpressCheckoutShippingRateChangeEvent {
831
+ wallet: ExpressCheckoutWallet;
832
+ shippingRate: ExpressCheckoutShippingRate;
833
+ resolve(update?: ExpressCheckoutShippingUpdate): void;
834
+ reject(): void;
835
+ }
836
+ type ExpressCheckoutElementEventName = 'ready' | 'resize' | 'error' | 'availablepaymentmethodschange' | 'click' | 'shippingaddresschange' | 'shippingratechange' | 'confirm' | 'cancel';
837
+ /**
838
+ * A reusable wallet surface. The hosted component owns provider availability,
839
+ * native wallet rendering, tokenization, and Payment Method creation.
840
+ */
841
+ interface ExpressCheckoutElement {
842
+ mount(target: string | HTMLElement): void;
843
+ /** Replace the checkout data used by the next native wallet sheet. */
844
+ update(options: ExpressCheckoutElementUpdateOptions): void;
845
+ on(event: 'ready', handler: (event: ExpressCheckoutAvailablePaymentMethodsChangeEvent) => void): () => void;
846
+ on(event: 'resize', handler: (event: ElementsResizeEvent) => void): () => void;
847
+ on(event: 'error', handler: (event: ElementsErrorEvent) => void): () => void;
848
+ on(event: 'availablepaymentmethodschange', handler: (event: ExpressCheckoutAvailablePaymentMethodsChangeEvent) => void): () => void;
849
+ on(event: 'click', handler: (event: ExpressCheckoutClickEvent) => void): () => void;
850
+ on(event: 'shippingaddresschange', handler: (event: ExpressCheckoutShippingAddressChangeEvent) => void): () => void;
851
+ on(event: 'shippingratechange', handler: (event: ExpressCheckoutShippingRateChangeEvent) => void): () => void;
852
+ on(event: 'confirm', handler: (event: ExpressCheckoutConfirmEvent) => void): () => void;
853
+ on(event: 'cancel', handler: (event: ExpressCheckoutCancelEvent) => void): () => void;
854
+ destroy(): void;
855
+ }
856
+ /** A group owns one controller and all secure Elements created from it. */
857
+ interface PaypercutElements {
858
+ create(type: 'card'): CardElement;
859
+ create(type: 'expressCheckout', options?: ExpressCheckoutElementOptions): ExpressCheckoutElement;
860
+ create(type: 'cardNumber', options?: CardNumberElementOptions): CardNumberElement;
861
+ create(type: 'cardExpiry'): CardExpiryElement;
862
+ create(type: 'cardCvc'): CardCvcElement;
863
+ /** Validate the active payment-method source without creating server-side resources. */
864
+ submit(): Promise<void>;
865
+ /**
866
+ * Update mutable group configuration. Mounted Appearance is locked by default;
867
+ * integrations must explicitly opt into the remount preview lifecycle, which
868
+ * preserves public Element objects while replacing their secure fields.
869
+ */
870
+ update(options: PaypercutElementsUpdateOptions): void;
871
+ destroy(): void;
872
+ }
873
+ interface PaypercutInstance {
874
+ elements(options: PaypercutElementsOptions): PaypercutElements;
875
+ /** Create an opaque Payment Method from an Elements group owned by this client. */
876
+ createPaymentMethod(options: PaypercutCreatePaymentMethodOptions): Promise<DeferredPaymentReference>;
877
+ /** Complete any required browser action and confirm a server-started payment. */
878
+ confirmPayment(options: PaypercutConfirmPaymentOptions): Promise<PaypercutConfirmPaymentResult>;
879
+ /** Exact advanced alias of confirmPayment; re-entry uses the same authoritative state machine. */
880
+ handleNextAction(options: PaypercutConfirmPaymentOptions): Promise<PaypercutConfirmPaymentResult>;
881
+ }
882
+ interface PaypercutStatic {
883
+ (options: PaypercutOptions): PaypercutInstance;
884
+ version: string;
885
+ }
886
+
887
+ declare const PaypercutExpressCheckout: ExpressCheckoutStatic;
888
+
889
+ declare const Paypercut: PaypercutStatic;
890
+
891
+ /**
892
+ * Factory function that works both as callable and constructable.
893
+ * Always returns a new CheckoutImpl instance - no prototype manipulation needed.
894
+ */
895
+ declare const PaypercutCheckout: PaypercutCheckoutStatic;
896
+
897
+ export { ExpressSdkEvent, LOCALES, PaymentMethod, Paypercut, PaypercutCheckout, PaypercutExpressCheckout, SdkEvent, UIMode, WalletOption, PaypercutCheckout as default };
898
+ export type { Appearance, AppearanceVariables, ApplePayButtonStyle, CancelPayload, CardCvcElement, CardElement, CardElementEventName, CardExpiryElement, CardFieldChangeEvent, CardFieldElement, CardFieldElementEventName, CardFieldElementType, CardNumberElement, CardNumberElementOptions, CheckoutInstance, DeferredPaymentReference, ElementsErrorCode, ElementsErrorEvent, ElementsResizeEvent, ElementsSubmitError, EventName, ExpressBillingDetails, ExpressButtonOptions, ExpressButtonType, ExpressCheckoutAddress, ExpressCheckoutAvailablePaymentMethodsChangeEvent, ExpressCheckoutBillingDetails, ExpressCheckoutCancelEvent, ExpressCheckoutClickEvent, ExpressCheckoutConfirmEvent, ExpressCheckoutElement, ExpressCheckoutElementEventName, ExpressCheckoutElementOptions, ExpressCheckoutInstance, ExpressCheckoutLineItem, ExpressCheckoutOptions, ExpressCheckoutPaymentMethodVisibility, ExpressCheckoutShippingOption, ExpressCheckoutUpdateOptions, ExpressCheckoutWallet, ExpressEventName, ExpressPaymentMethodCreatedEvent, ExpressPaymentMethodFailedEvent, ExpressSessionStartEvent, ExpressShippingAddress, ExpressShippingDetails, ExpressTokenPayload, FormValidationError, GooglePayButtonColor, KnownElementsErrorCode, LineItem, Locale, PaypercutBillingAddress, PaypercutBillingDetails, PaypercutCheckoutOptions, PaypercutCheckoutStatic, PaypercutConfirmPaymentOptions, PaypercutConfirmPaymentResult, PaypercutCreatePaymentMethodOptions, PaypercutCreatePaymentMethodParams, PaypercutElements, PaypercutElementsAppearance, PaypercutElementsAppearanceRuleProperty, PaypercutElementsAppearanceRuleSelector, PaypercutElementsAppearanceRules, PaypercutElementsAppearanceUpdates, PaypercutElementsAppearanceVariableName, PaypercutElementsAppearanceVariables, PaypercutElementsMode, PaypercutElementsOptions, PaypercutElementsUpdateOptions, PaypercutInstance, PaypercutOptions, PaypercutSetupFutureUsage, PaypercutStatic, ShippingAddressChangeEvent, ShippingOptionChangeEvent, WalletType };