@paypercut/checkout-js 1.2.18 → 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/dist/index.d.ts CHANGED
@@ -480,13 +480,311 @@ interface ExpressCheckoutStatic {
480
480
  new (options: ExpressCheckoutOptions): ExpressCheckoutInstance;
481
481
  }
482
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
+ /**
492
+ * Internal builds only. Enables the local developer assistant after the
493
+ * merchant application has authorized the current viewer.
494
+ */
495
+ developerAssistant?: boolean;
496
+ }
497
+ /** Initial configuration shared by the Elements group. */
498
+ interface PaypercutElementsOptions {
499
+ mode: 'payment';
500
+ /** Amount in minor units. */
501
+ amount: number;
502
+ /** ISO 4217 alphabetic currency code. */
503
+ currency: string;
504
+ locale?: Locale | string;
505
+ appearance?: PaypercutElementsAppearance;
506
+ }
507
+ /** Visual configuration shared by every component in one Elements group. */
508
+ 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';
509
+ type PaypercutElementsAppearanceVariables = Partial<Record<PaypercutElementsAppearanceVariableName, string>>;
510
+ type PaypercutElementsAppearanceRuleSelector = '.Input' | '.Input--invalid' | '.Input:focus' | '.Label' | '.Error' | '.Text' | '.WalletButton' | '.WalletButton--applePay' | '.WalletButton--googlePay' | '.ActionShell';
511
+ 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';
512
+ type PaypercutElementsAppearanceRules = Partial<Record<PaypercutElementsAppearanceRuleSelector, Partial<Record<PaypercutElementsAppearanceRuleProperty, string>>>>;
513
+ interface PaypercutElementsAppearance {
514
+ /** Light is the default. The developer assistant presents dark as the Night theme. */
515
+ theme?: 'light' | 'dark';
516
+ /** Condensed keeps all card fields on one line; spaced renders separate secure inputs. */
517
+ inputs?: 'condensed' | 'spaced';
518
+ /**
519
+ * Auto places labels above spaced inputs and uses in-field labels for condensed inputs.
520
+ */
521
+ labels?: 'auto' | 'above' | 'floating';
522
+ /** Fine-grained visual variables layered on top of the selected theme. */
523
+ variables?: PaypercutElementsAppearanceVariables;
524
+ /** Semantic, allow-listed component rules. Arbitrary CSS selectors are rejected. */
525
+ rules?: PaypercutElementsAppearanceRules;
526
+ /** Disable non-essential transitions and animations inside every Elements frame. */
527
+ disableAnimations?: boolean;
528
+ }
529
+ /** Customer fields that may change while an Elements group remains mounted. */
530
+ interface PaypercutElementsCustomerUpdate {
531
+ /** Pass null to clear a previously supplied email. */
532
+ email?: string | null;
533
+ /** Pass null to clear a previously supplied name. */
534
+ name?: string | null;
535
+ }
536
+ /** Mutable configuration for an existing Elements group. */
537
+ interface PaypercutElementsUpdateOptions {
538
+ /** Updated amount in minor units. Currency remains immutable for the lifetime of the group. */
539
+ amount?: number;
540
+ customer?: PaypercutElementsCustomerUpdate;
541
+ appearance?: PaypercutElementsAppearance;
542
+ }
543
+ interface PaymentElementResizeEvent {
544
+ height: number;
545
+ }
546
+ /** Stable error codes emitted by the current Paypercut Elements implementation. */
547
+ type KnownPaymentElementErrorCode = '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_not_ready' | 'elements_provider_initialization_failed' | 'elements_session_expired' | 'elements_session_binding_mismatch' | 'elements_session_verification_failed' | 'elements_submission_in_progress' | 'elements_submit_in_progress' | '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_shell_timeout' | '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';
548
+ /**
549
+ * Elements error code. The open string member permits newer hosted components
550
+ * to add codes without requiring a synchronous merchant SDK upgrade.
551
+ */
552
+ type PaymentElementErrorCode = KnownPaymentElementErrorCode | (string & Record<never, never>);
553
+ interface PaymentElementErrorEvent {
554
+ code: PaymentElementErrorCode;
555
+ message: string;
556
+ recoverable?: boolean;
557
+ }
558
+ /** Server-consumable Payment Method produced without creating a Checkout Session. */
559
+ interface DeferredPaymentReference {
560
+ type: 'payment_method';
561
+ /** Opaque Payment Method identifier. */
562
+ id: string;
563
+ }
564
+ /** Typed rejection returned by PaymentElement.submit(). */
565
+ interface PaymentElementSubmitError extends Error {
566
+ code: PaymentElementErrorCode;
567
+ recoverable: boolean;
568
+ }
569
+ type PaymentElementEventName = 'ready' | 'resize' | 'error';
570
+ /** Payment Element surface coordinated by one hidden Elements controller. */
571
+ interface PaymentElement {
572
+ mount(target: string | HTMLElement): void;
573
+ /** Validate and tokenize the mounted payment details into one narrow deferred reference. */
574
+ submit(): Promise<DeferredPaymentReference>;
575
+ on(event: 'ready', handler: () => void): () => void;
576
+ on(event: 'resize', handler: (event: PaymentElementResizeEvent) => void): () => void;
577
+ on(event: 'error', handler: (event: PaymentElementErrorEvent) => void): () => void;
578
+ on(event: PaymentElementEventName, handler: ((event: PaymentElementResizeEvent | PaymentElementErrorEvent) => void) | (() => void)): () => void;
579
+ destroy(): void;
580
+ }
581
+ /** Wallets currently implemented by the Express Checkout Element. */
582
+ type ExpressCheckoutWallet = 'apple_pay' | 'google_pay';
583
+ /** Browser-safe display data for a wallet-backed Payment Method. */
584
+ interface ExpressCheckoutPaymentMethodPreview {
585
+ type: 'card';
586
+ brand: string;
587
+ displayBrand: string;
588
+ last4: string;
589
+ expMonth?: number;
590
+ expYear?: number;
591
+ wallet: ExpressCheckoutWallet;
592
+ }
593
+ /** Controls whether a wallet is considered when the hosted component checks availability. */
594
+ type ExpressCheckoutPaymentMethodVisibility = 'auto' | 'always' | 'never';
595
+ interface ExpressCheckoutElementOptions {
596
+ paymentMethods?: {
597
+ applePay?: ExpressCheckoutPaymentMethodVisibility;
598
+ googlePay?: ExpressCheckoutPaymentMethodVisibility;
599
+ };
600
+ layout?: {
601
+ maxColumns?: number;
602
+ maxRows?: number;
603
+ overflow?: 'auto' | 'never';
604
+ };
605
+ buttonType?: {
606
+ applePay?: 'plain' | 'buy' | 'check-out' | 'donate' | 'book' | 'subscribe';
607
+ googlePay?: 'plain' | 'pay' | 'buy' | 'checkout' | 'donate' | 'book' | 'subscribe';
608
+ };
609
+ buttonTheme?: {
610
+ applePay?: 'black' | 'white' | 'white-outline';
611
+ googlePay?: 'black' | 'white';
612
+ };
613
+ /** Button height in CSS pixels. */
614
+ buttonHeight?: number;
615
+ /** Corner radius shared by every provider button, in CSS pixels. Defaults to 4. */
616
+ buttonRadius?: number;
617
+ emailRequired?: boolean;
618
+ phoneNumberRequired?: boolean;
619
+ billingAddressRequired?: boolean;
620
+ shippingAddressRequired?: boolean;
621
+ allowedShippingCountries?: string[];
622
+ lineItems?: ExpressCheckoutLineItem[];
623
+ /** Initial rates shown by wallets that require rates before their sheet opens. */
624
+ shippingRates?: ExpressCheckoutShippingRate[];
625
+ }
626
+ interface ExpressCheckoutLineItem {
627
+ name: string;
628
+ amount: number;
629
+ }
630
+ /** One merchant shipping choice. Amount is expressed in minor currency units. */
631
+ interface ExpressCheckoutShippingRate {
632
+ id: string;
633
+ displayName: string;
634
+ amount: number;
635
+ /** Optional detailed shipping note returned by some providers. */
636
+ detail?: string;
637
+ }
638
+ /**
639
+ * Redacted shipping address supplied while the wallet sheet is open. Wallets
640
+ * may omit fields until the customer authorizes the payment.
641
+ */
642
+ interface ExpressCheckoutShippingAddress {
643
+ recipient?: string;
644
+ addressLine?: string[];
645
+ city?: string;
646
+ state?: string;
647
+ postalCode?: string;
648
+ country?: string;
649
+ }
650
+ interface ExpressCheckoutAddress {
651
+ /** @deprecated The contact name belongs on billingDetails or shippingAddress. */
652
+ name?: string;
653
+ line1?: string;
654
+ line2?: string;
655
+ city?: string;
656
+ state?: string;
657
+ postalCode?: string;
658
+ country?: string;
659
+ }
660
+ /** Final, unredacted shipping details returned after wallet authorization. */
661
+ interface ExpressCheckoutShippingDetails {
662
+ name?: string;
663
+ address?: ExpressCheckoutAddress;
664
+ }
665
+ interface ExpressCheckoutBillingDetails {
666
+ name?: string;
667
+ email?: string;
668
+ phone?: string;
669
+ address?: ExpressCheckoutAddress;
670
+ }
671
+ interface ExpressCheckoutAvailablePaymentMethodsChangeEvent {
672
+ availablePaymentMethods: {
673
+ applePay: boolean;
674
+ googlePay: boolean;
675
+ };
676
+ }
677
+ interface ExpressCheckoutConfirmEvent {
678
+ wallet: ExpressCheckoutWallet;
679
+ paymentMethod: DeferredPaymentReference;
680
+ paymentMethodPreview?: ExpressCheckoutPaymentMethodPreview;
681
+ billingDetails?: ExpressCheckoutBillingDetails;
682
+ shippingAddress?: ExpressCheckoutShippingDetails;
683
+ /** The final wallet-selected shipping rate, when shipping collection is enabled. */
684
+ shippingRate?: ExpressCheckoutShippingRate;
685
+ /** Complete the native wallet after the merchant accepts the prepared method or checkout. */
686
+ complete(): void;
687
+ /** Fail the native wallet after the merchant rejects preparation, payment, or order creation. */
688
+ paymentFailed(error?: {
689
+ code?: string;
690
+ message?: string;
691
+ }): void;
692
+ }
693
+ interface ExpressCheckoutCancelEvent {
694
+ wallet: ExpressCheckoutWallet;
695
+ }
696
+ /**
697
+ * Emitted before a wallet attempt is allowed to continue. Call exactly one of
698
+ * resolve() or reject(). When no click listener is registered, the Element
699
+ * continues automatically.
700
+ */
701
+ interface ExpressCheckoutClickEvent {
702
+ wallet: ExpressCheckoutWallet;
703
+ resolve(options?: ExpressCheckoutClickResolveOptions): void;
704
+ reject(): void;
705
+ }
706
+ /** Current checkout details supplied immediately before a wallet is opened. */
707
+ interface ExpressCheckoutClickResolveOptions {
708
+ lineItems?: ExpressCheckoutLineItem[];
709
+ emailRequired?: boolean;
710
+ phoneNumberRequired?: boolean;
711
+ billingAddressRequired?: boolean;
712
+ shippingAddressRequired?: boolean;
713
+ allowedShippingCountries?: string[];
714
+ shippingRates?: ExpressCheckoutShippingRate[];
715
+ }
716
+ /**
717
+ * Mutable checkout data for an already mounted Express Checkout Element.
718
+ *
719
+ * Provider selection, layout, and button styling remain immutable for the
720
+ * lifetime of the Element. Commerce state can be replaced before the next
721
+ * wallet gesture without remounting the secure component.
722
+ */
723
+ type ExpressCheckoutElementUpdateOptions = ExpressCheckoutClickResolveOptions;
724
+ /** Updated checkout details returned after a wallet address or rate changes. */
725
+ interface ExpressCheckoutShippingUpdate {
726
+ /** Recalculated order total in the group's currency, in minor units. */
727
+ amount?: number;
728
+ lineItems?: ExpressCheckoutLineItem[];
729
+ shippingRates?: ExpressCheckoutShippingRate[];
730
+ }
731
+ interface ExpressCheckoutShippingAddressChangeEvent {
732
+ wallet: ExpressCheckoutWallet;
733
+ address: ExpressCheckoutShippingAddress;
734
+ resolve(update?: ExpressCheckoutShippingUpdate): void;
735
+ reject(): void;
736
+ }
737
+ interface ExpressCheckoutShippingRateChangeEvent {
738
+ wallet: ExpressCheckoutWallet;
739
+ shippingRate: ExpressCheckoutShippingRate;
740
+ resolve(update?: ExpressCheckoutShippingUpdate): void;
741
+ reject(): void;
742
+ }
743
+ type ExpressCheckoutElementEventName = 'ready' | 'resize' | 'error' | 'availablepaymentmethodschange' | 'click' | 'shippingaddresschange' | 'shippingratechange' | 'confirm' | 'cancel';
744
+ /**
745
+ * A reusable wallet surface. The hosted component owns provider availability,
746
+ * native wallet rendering, tokenization, and Payment Method creation.
747
+ */
748
+ interface ExpressCheckoutElement {
749
+ mount(target: string | HTMLElement): void;
750
+ /** Replace the checkout data used by the next native wallet sheet. */
751
+ update(options: ExpressCheckoutElementUpdateOptions): void;
752
+ on(event: 'ready', handler: (event: ExpressCheckoutAvailablePaymentMethodsChangeEvent) => void): () => void;
753
+ on(event: 'resize', handler: (event: PaymentElementResizeEvent) => void): () => void;
754
+ on(event: 'error', handler: (event: PaymentElementErrorEvent) => void): () => void;
755
+ on(event: 'availablepaymentmethodschange', handler: (event: ExpressCheckoutAvailablePaymentMethodsChangeEvent) => void): () => void;
756
+ on(event: 'click', handler: (event: ExpressCheckoutClickEvent) => void): () => void;
757
+ on(event: 'shippingaddresschange', handler: (event: ExpressCheckoutShippingAddressChangeEvent) => void): () => void;
758
+ on(event: 'shippingratechange', handler: (event: ExpressCheckoutShippingRateChangeEvent) => void): () => void;
759
+ on(event: 'confirm', handler: (event: ExpressCheckoutConfirmEvent) => void): () => void;
760
+ on(event: 'cancel', handler: (event: ExpressCheckoutCancelEvent) => void): () => void;
761
+ destroy(): void;
762
+ }
763
+ /** A group owns one controller and all secure Elements created from it. */
764
+ interface PaypercutElements {
765
+ create(type: 'payment'): PaymentElement;
766
+ create(type: 'expressCheckout', options?: ExpressCheckoutElementOptions): ExpressCheckoutElement;
767
+ /** Update customer details or appearance without replacing the controller or hosted frames. */
768
+ update(options: PaypercutElementsUpdateOptions): void;
769
+ destroy(): void;
770
+ }
771
+ interface PaypercutInstance {
772
+ elements(options: PaypercutElementsOptions): PaypercutElements;
773
+ }
774
+ interface PaypercutStatic {
775
+ (options: PaypercutOptions): PaypercutInstance;
776
+ version: string;
777
+ }
778
+
483
779
  declare const PaypercutExpressCheckout: ExpressCheckoutStatic;
484
780
 
781
+ declare const Paypercut: PaypercutStatic;
782
+
485
783
  /**
486
784
  * Factory function that works both as callable and constructable.
487
785
  * Always returns a new CheckoutImpl instance - no prototype manipulation needed.
488
786
  */
489
787
  declare const PaypercutCheckout: PaypercutCheckoutStatic;
490
788
 
491
- export { ExpressSdkEvent, LOCALES, PaymentMethod, PaypercutCheckout, PaypercutExpressCheckout, SdkEvent, UIMode, WalletOption, PaypercutCheckout as default };
492
- export type { Appearance, AppearanceVariables, ApplePayButtonStyle, CancelPayload, CheckoutInstance, EventName, ExpressBillingDetails, ExpressButtonOptions, ExpressButtonType, ExpressCheckoutInstance, ExpressCheckoutOptions, ExpressCheckoutShippingOption, ExpressCheckoutUpdateOptions, ExpressEventName, ExpressPaymentMethodCreatedEvent, ExpressPaymentMethodFailedEvent, ExpressSessionStartEvent, ExpressShippingAddress, ExpressShippingDetails, ExpressTokenPayload, FormValidationError, GooglePayButtonColor, LineItem, Locale, PaypercutCheckoutOptions, PaypercutCheckoutStatic, ShippingAddressChangeEvent, ShippingOptionChangeEvent, WalletType };
789
+ export { ExpressSdkEvent, LOCALES, PaymentMethod, Paypercut, PaypercutCheckout, PaypercutExpressCheckout, SdkEvent, UIMode, WalletOption, PaypercutCheckout as default };
790
+ export type { Appearance, AppearanceVariables, ApplePayButtonStyle, CancelPayload, CheckoutInstance, DeferredPaymentReference, 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, KnownPaymentElementErrorCode, LineItem, Locale, PaymentElement, PaymentElementErrorCode, PaymentElementErrorEvent, PaymentElementEventName, PaymentElementResizeEvent, PaymentElementSubmitError, PaypercutCheckoutOptions, PaypercutCheckoutStatic, PaypercutElements, PaypercutElementsAppearance, PaypercutElementsAppearanceRuleProperty, PaypercutElementsAppearanceRuleSelector, PaypercutElementsAppearanceRules, PaypercutElementsAppearanceVariableName, PaypercutElementsAppearanceVariables, PaypercutElementsCustomerUpdate, PaypercutElementsOptions, PaypercutElementsUpdateOptions, PaypercutInstance, PaypercutOptions, PaypercutStatic, ShippingAddressChangeEvent, ShippingOptionChangeEvent, WalletType };