@paypercut/checkout-js 1.2.19 → 1.3.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.
package/dist/index.d.ts CHANGED
@@ -488,20 +488,35 @@ interface PaypercutOptions {
488
488
  hostedCheckoutUrl?: string;
489
489
  /** Internal builds only. Production builds ignore this override. */
490
490
  apiUrl?: string;
491
- /**
492
- * Internal builds only. Enables the local developer assistant after the
493
- * merchant application has authorized the current viewer.
494
- */
491
+ /** Internal builds only. Ignored by production builds. */
495
492
  developerAssistant?: boolean;
496
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';
497
498
  /** Initial configuration shared by the Elements group. */
498
499
  interface PaypercutElementsOptions {
499
- mode: 'payment';
500
+ mode: PaypercutElementsMode;
500
501
  /** Amount in minor units. */
501
502
  amount: number;
502
503
  /** ISO 4217 alphabetic currency code. */
503
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;
504
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;
505
520
  appearance?: PaypercutElementsAppearance;
506
521
  }
507
522
  /** Visual configuration shared by every component in one Elements group. */
@@ -511,7 +526,7 @@ type PaypercutElementsAppearanceRuleSelector = '.Input' | '.Input--invalid' | '.
511
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';
512
527
  type PaypercutElementsAppearanceRules = Partial<Record<PaypercutElementsAppearanceRuleSelector, Partial<Record<PaypercutElementsAppearanceRuleProperty, string>>>>;
513
528
  interface PaypercutElementsAppearance {
514
- /** Light is the default. The developer assistant presents dark as the Night theme. */
529
+ /** Light is the default. */
515
530
  theme?: 'light' | 'dark';
516
531
  /** Condensed keeps all card fields on one line; spaced renders separate secure inputs. */
517
532
  inputs?: 'condensed' | 'spaced';
@@ -526,32 +541,28 @@ interface PaypercutElementsAppearance {
526
541
  /** Disable non-essential transitions and animations inside every Elements frame. */
527
542
  disableAnimations?: boolean;
528
543
  }
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
544
  /** Mutable configuration for an existing Elements group. */
537
545
  interface PaypercutElementsUpdateOptions {
538
546
  /** Updated amount in minor units. Currency remains immutable for the lifetime of the group. */
539
547
  amount?: number;
540
- customer?: PaypercutElementsCustomerUpdate;
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
+ */
541
552
  appearance?: PaypercutElementsAppearance;
542
553
  }
543
- interface PaymentElementResizeEvent {
554
+ interface ElementsResizeEvent {
544
555
  height: number;
545
556
  }
546
557
  /** 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';
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';
548
559
  /**
549
560
  * Elements error code. The open string member permits newer hosted components
550
561
  * to add codes without requiring a synchronous merchant SDK upgrade.
551
562
  */
552
- type PaymentElementErrorCode = KnownPaymentElementErrorCode | (string & Record<never, never>);
553
- interface PaymentElementErrorEvent {
554
- code: PaymentElementErrorCode;
563
+ type ElementsErrorCode = KnownElementsErrorCode | (string & Record<never, never>);
564
+ interface ElementsErrorEvent {
565
+ code: ElementsErrorCode;
555
566
  message: string;
556
567
  recoverable?: boolean;
557
568
  }
@@ -561,23 +572,105 @@ interface DeferredPaymentReference {
561
572
  /** Opaque Payment Method identifier. */
562
573
  id: string;
563
574
  }
564
- /** Typed rejection returned by PaymentElement.submit(). */
565
- interface PaymentElementSubmitError extends Error {
566
- code: PaymentElementErrorCode;
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;
567
619
  recoverable: boolean;
568
620
  }
569
- type PaymentElementEventName = 'ready' | 'resize' | 'error';
570
- /** Payment Element surface coordinated by one hidden Elements controller. */
571
- interface PaymentElement {
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;
572
647
  mount(target: string | HTMLElement): void;
573
- /** Validate and tokenize the mounted payment details into one narrow deferred reference. */
574
- submit(): Promise<DeferredPaymentReference>;
648
+ clear(): void;
649
+ focus(): void;
650
+ blur(): void;
575
651
  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;
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;
579
655
  destroy(): void;
580
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
+ }
581
674
  /** Wallets currently implemented by the Express Checkout Element. */
582
675
  type ExpressCheckoutWallet = 'apple_pay' | 'google_pay';
583
676
  /** Browser-safe display data for a wallet-backed Payment Method. */
@@ -750,8 +843,8 @@ interface ExpressCheckoutElement {
750
843
  /** Replace the checkout data used by the next native wallet sheet. */
751
844
  update(options: ExpressCheckoutElementUpdateOptions): void;
752
845
  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;
846
+ on(event: 'resize', handler: (event: ElementsResizeEvent) => void): () => void;
847
+ on(event: 'error', handler: (event: ElementsErrorEvent) => void): () => void;
755
848
  on(event: 'availablepaymentmethodschange', handler: (event: ExpressCheckoutAvailablePaymentMethodsChangeEvent) => void): () => void;
756
849
  on(event: 'click', handler: (event: ExpressCheckoutClickEvent) => void): () => void;
757
850
  on(event: 'shippingaddresschange', handler: (event: ExpressCheckoutShippingAddressChangeEvent) => void): () => void;
@@ -762,14 +855,29 @@ interface ExpressCheckoutElement {
762
855
  }
763
856
  /** A group owns one controller and all secure Elements created from it. */
764
857
  interface PaypercutElements {
765
- create(type: 'payment'): PaymentElement;
858
+ create(type: 'card'): CardElement;
766
859
  create(type: 'expressCheckout', options?: ExpressCheckoutElementOptions): ExpressCheckoutElement;
767
- /** Update customer details or appearance without replacing the controller or hosted frames. */
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
+ */
768
870
  update(options: PaypercutElementsUpdateOptions): void;
769
871
  destroy(): void;
770
872
  }
771
873
  interface PaypercutInstance {
772
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>;
773
881
  }
774
882
  interface PaypercutStatic {
775
883
  (options: PaypercutOptions): PaypercutInstance;
@@ -787,4 +895,4 @@ declare const Paypercut: PaypercutStatic;
787
895
  declare const PaypercutCheckout: PaypercutCheckoutStatic;
788
896
 
789
897
  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 };
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 };