@flopay/shared 1.4.1 → 1.4.2

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.cts CHANGED
@@ -74,7 +74,7 @@ interface ButtonsLayoutStyles {
74
74
  * style config handed to the vault PCI card form, so these win over the
75
75
  * auto-translated `cardInput*` knobs and `appearance.variables`. Keys are
76
76
  * passed through verbatim — use vault-supported style property names.
77
- * No effect on the legacy Stripe-Elements card path.
77
+ * Applied only to the hosted vault card form.
78
78
  */
79
79
  vaultCardForm?: Record<string, string | number>;
80
80
  /** Style for the full-name text input. */
@@ -273,8 +273,8 @@ interface CheckoutGateway {
273
273
  * {@link STRIPE_EXPRESS_METHODS} to decide which methods render in the
274
274
  * `ExpressCheckoutElement` row (Apple Pay / Google Pay / PayPal / Link /
275
275
  * Amazon Pay / Klarna) vs the `PaymentElement` accordion (Cash App Pay /
276
- * Affirm / iDEAL / Bancontact / …). `card` is always filtered out — the
277
- * card path stays on the split-fields elements. Absent on legacy backends.
276
+ * Affirm / iDEAL / Bancontact / …). `card` is always filtered out because
277
+ * the hosted vault owns the card path. Absent on legacy backends.
278
278
  */
279
279
  enabledPaymentMethods?: string[];
280
280
  /**
@@ -311,12 +311,11 @@ interface CheckoutSession {
311
311
  metadata?: Record<string, string>;
312
312
  checkoutMode?: CheckoutMode;
313
313
  /**
314
- * Embedded hosted vault capture credentials (TeamFloPay/backend#823),
315
- * populated on the `POST /v1/checkouts/sessions` response when the SDK
316
- * declared `X-Flo-SDK-Version >= 1.3.0` and the backend advertises a
317
- * `pcivault` gateway. The SDK injects {@link VaultCaptureBlock.html} as the
318
- * card-capture widget. Absent on legacy backends or when the SDK must fetch
319
- * the block via `POST /v1/checkouts/sessions/{id}/vault/capture` instead.
314
+ * Embedded hosted vault capture credentials (TeamFloPay/backend#823).
315
+ * Card-capable session create/read responses include this block without
316
+ * SDK-version dispatch. The SDK injects {@link VaultCaptureBlock.html} as
317
+ * the card-capture widget; the explicit recovery path remains
318
+ * `POST /v1/checkouts/sessions/{id}/vault/capture`.
320
319
  */
321
320
  vault?: VaultCaptureBlock;
322
321
  /**
@@ -377,16 +376,19 @@ interface PaymentResult {
377
376
  checkoutMethod?: CheckoutButtonMethod;
378
377
  error?: FloPayError;
379
378
  }
380
- /** Parameters for confirming a payment. */
379
+ /** Parameters for confirming a wallet/APM payment from a mounted PaymentElement. */
381
380
  interface ConfirmPaymentParams {
382
381
  clientSecret: string;
382
+ /** Explicit non-card category for the selected payment method. */
383
+ paymentMethodCategory: NonCardPaymentMethodCategory;
384
+ /** Provider method type (for example `cashapp` or `ideal`); `card` is rejected. */
385
+ paymentMethodType: string;
383
386
  /** Optional redirect URL after 3-D Secure or wallet authentication. */
384
387
  returnUrl?: string;
385
388
  /**
386
389
  * Optional billing details appended to `payment_method_data` on the confirm call.
387
390
  * Ensures `billing_details.email` (and name/address) lands on the PaymentMethod
388
- * Stripe mints from Elements during 3DS confirmation — otherwise the new PM
389
- * inherits none of the info we attached at `createPaymentMethod` time.
391
+ * Stripe mints from Elements during 3DS confirmation.
390
392
  */
391
393
  billingDetails?: BillingDetails;
392
394
  }
@@ -403,33 +405,68 @@ interface BillingDetails {
403
405
  state?: string;
404
406
  };
405
407
  }
406
- /** Result from creating a payment method (tokenizing card fields). */
407
- interface CreatePaymentMethodResult {
408
- paymentMethodId: string | null;
409
- error?: FloPayError;
410
- }
411
- /** Parameters for confirming a card payment with a known client secret. */
412
- interface ConfirmCardPaymentParams {
413
- clientSecret: string;
414
- paymentMethodId: string;
415
- }
416
- /** Provider-observed 3DS lifecycle for one opaque, attempt-scoped confirmation. */
417
- interface CardThreeDsLifecycle {
418
- /** Opaque in-memory identifier; never derived from payment identifiers. */
419
- attemptId: string;
420
- status: 'handoff' | 'returned' | 'failed';
421
- }
422
- /** Result from confirming a card payment. */
423
- interface ConfirmCardPaymentResult {
408
+ /** Result from the Stripe-hosted PayPal confirmation or redirect-resume flow. */
409
+ interface PayPalPaymentResult {
424
410
  status: 'succeeded' | 'processing' | 'requires_action' | 'requires_capture' | 'failed';
425
411
  paymentIntentId?: string;
426
412
  paymentMethodId?: string;
427
413
  error?: FloPayError;
428
- /** @internal Provider-observed lifecycle used for privacy-safe telemetry. */
429
- threeDs?: CardThreeDsLifecycle;
430
414
  }
415
+ /** Non-card method families accepted by the public session intent endpoint. */
416
+ type NonCardPaymentMethodCategory = 'wallet' | 'apm';
417
+ /**
418
+ * Stable identity of one buyer authorization attempt (a v4 UUID).
419
+ *
420
+ * The backend folds this into the provider idempotency key, so reusing the same
421
+ * value makes a transport retry reuse the *same* provider intent, while a fresh
422
+ * value deliberately starts a new authorization. Optional on the SDK request:
423
+ * `PaymentAPI.createSessionIntent` generates one when omitted and only advanced
424
+ * callers that drive their own retries need to pass a stable value.
425
+ */
426
+ interface SessionIntentAuthorizationAttempt {
427
+ authorizationAttemptId?: string;
428
+ }
429
+ /** Stripe wallet/APM request. Direct card is deliberately not representable. */
430
+ interface StripeSessionIntentRequest extends SessionIntentAuthorizationAttempt {
431
+ provider: 'stripe';
432
+ paymentMethodCategory: NonCardPaymentMethodCategory;
433
+ paymentMethodType: string;
434
+ paymentMethodId: string | null;
435
+ intentKind: 'payment' | 'setup';
436
+ }
437
+ /** Direct PayPal order/subscription request. */
438
+ interface PayPalSessionIntentRequest extends SessionIntentAuthorizationAttempt {
439
+ provider: 'paypal';
440
+ paymentMethodCategory: 'wallet';
441
+ paymentMethodType: 'paypal';
442
+ paymentMethodId: null;
443
+ intentKind: 'order' | 'subscription';
444
+ }
445
+ type CreateSessionIntentRequest = StripeSessionIntentRequest | PayPalSessionIntentRequest;
446
+ interface StripeSessionIntent extends StripeSessionIntentRequest {
447
+ clientSecret: string;
448
+ providerObjectId: string;
449
+ }
450
+ interface PayPalSessionIntent extends PayPalSessionIntentRequest {
451
+ clientSecret: null;
452
+ providerObjectId: string;
453
+ }
454
+ type SessionIntent = StripeSessionIntent | PayPalSessionIntent;
455
+ type SessionIntentDeclineRequest = {
456
+ provider: 'stripe';
457
+ paymentMethodCategory: NonCardPaymentMethodCategory;
458
+ paymentMethodType: string;
459
+ /** Provider classification code only; messages and identifiers are rejected. */
460
+ providerDeclineReason: string;
461
+ } | {
462
+ provider: 'paypal';
463
+ paymentMethodCategory: 'wallet';
464
+ paymentMethodType: 'paypal';
465
+ /** Provider classification code only; messages and identifiers are rejected. */
466
+ providerDeclineReason: string;
467
+ };
431
468
  /** The type of payment element to render. */
432
- type ElementType = 'payment' | 'card' | 'cardNumber' | 'cardExpiry' | 'cardCvc' | 'address';
469
+ type ElementType = 'payment' | 'address';
433
470
  /** Emitted when an element's internal state changes. */
434
471
  interface ElementChangeEvent {
435
472
  elementType: ElementType;
@@ -445,7 +482,17 @@ interface ElementChangeEvent {
445
482
  /** Configuration options when creating an element. */
446
483
  interface ElementOptions {
447
484
  appearance?: FloPayAppearance;
448
- /** Client secret for the PaymentIntent or SetupIntent. When present, Stripe uses it directly. */
485
+ /**
486
+ * Explicit non-card provider method types rendered by a payment element.
487
+ * The SDK removes `card`; card collection belongs to the hosted vault.
488
+ */
489
+ paymentMethodTypes?: readonly string[];
490
+ /**
491
+ * Client secret for an existing non-card PaymentIntent or SetupIntent.
492
+ * The explicit `paymentMethodTypes` allowlist remains required; the SDK uses
493
+ * it to validate the provider intent before mounting. Card checkout uses the
494
+ * hosted vault.
495
+ */
449
496
  clientSecret?: string;
450
497
  /**
451
498
  * Total amount in the smallest currency unit (e.g. cents).
@@ -467,19 +514,6 @@ interface ElementOptions {
467
514
  readOnly?: boolean;
468
515
  /** Address element mode: 'billing' or 'shipping'. */
469
516
  mode?: 'billing' | 'shipping';
470
- /**
471
- * Style object for individual card elements (cardNumber, cardExpiry, cardCvc).
472
- * Passed directly to the underlying provider element.
473
- *
474
- * @example
475
- * ```ts
476
- * style: {
477
- * base: { color: '#f9fafb', fontSize: '16px', '::placeholder': { color: '#6b7280' } },
478
- * invalid: { color: '#ef4444' },
479
- * }
480
- * ```
481
- */
482
- style?: Record<string, Record<string, unknown>>;
483
517
  }
484
518
  /**
485
519
  * A payment element that has been created and can be mounted into the DOM.
@@ -528,18 +562,14 @@ interface PaymentProviderAdapter {
528
562
  submitElements(): Promise<{
529
563
  error?: FloPayError;
530
564
  }>;
531
- /** Create a payment method from the current elements (tokenize card). */
532
- createPaymentMethod(billingDetails?: BillingDetails): Promise<CreatePaymentMethodResult>;
533
- /** Confirm a card payment with a known client secret and payment method. */
534
- confirmCardPayment(params: ConfirmCardPaymentParams): Promise<ConfirmCardPaymentResult>;
565
+ /** Confirm a non-card wallet/APM payment from mounted elements. */
535
566
  confirmPayment(params: ConfirmPaymentParams): Promise<PaymentResult>;
536
567
  /**
537
568
  * Create a PayPal payment: create PM → create intent → confirm with redirect.
538
569
  * Returns the confirmed PaymentIntent ID if completed inline, or redirects to PayPal.
539
570
  *
540
- * `nonce` is the session-bound checkout token from session creation. Post-#640
541
- * backends reject `POST /v1/checkouts/payments/intents` with 401 when the
542
- * `x-checkout-session-token` header is missing — pass `nonce` to forward it.
571
+ * `nonce` is the session-bound checkout token forwarded to the
572
+ * session-scoped non-card intent contract.
543
573
  */
544
574
  confirmPayPalPayment(params: {
545
575
  billingApiUrl: string;
@@ -547,21 +577,18 @@ interface PaymentProviderAdapter {
547
577
  email: string;
548
578
  returnUrl: string;
549
579
  nonce?: string;
550
- }): Promise<ConfirmCardPaymentResult>;
580
+ }): Promise<PayPalPaymentResult>;
551
581
  /**
552
582
  * Resume a PayPal payment after redirect return.
553
583
  * Checks URL params for payment_intent + redirect_status.
554
584
  */
555
- resumePayPalPayment(): Promise<ConfirmCardPaymentResult | null>;
585
+ resumePayPalPayment(): Promise<PayPalPaymentResult | null>;
556
586
  /**
557
587
  * Get the raw underlying provider instance (e.g. Stripe object).
558
588
  * Used internally for creating secondary Elements groups (e.g. PayPal).
559
589
  */
560
590
  getRawProvider(): unknown;
561
- /**
562
- * Create a secondary Elements group for PayPal.
563
- * PayPal can't share Elements with card fields that use paymentMethodCreation: 'manual'.
564
- */
591
+ /** Create a secondary Elements group for PayPal's automatic payment-method flow. */
565
592
  createPayPalElements(options: ElementOptions): unknown;
566
593
  destroy(): void;
567
594
  }
@@ -576,8 +603,8 @@ type CardCaptureProviderId = 'pcivault';
576
603
  /**
577
604
  * Server-rendered hosted vault capture credentials (TeamFloPay/backend#823).
578
605
  *
579
- * Returned either embedded on the `POST /v1/checkouts/sessions` response (when
580
- * the SDK declared `X-Flo-SDK-Version >= 1.3.0`) or from the explicit
606
+ * Returned either embedded on every card-capable session create/read response
607
+ * or from the explicit
581
608
  * `POST /v1/checkouts/sessions/{id}/vault/capture` endpoint. `html` is a
582
609
  * self-contained, Flo-bundled hosted-form widget (PCIVault card fields, its own
583
610
  * submit button, status overlay, and — owned entirely by the backend — card
@@ -739,7 +766,7 @@ interface CardCaptureMountOptions {
739
766
  }
740
767
  /**
741
768
  * Merchant style values the SDK pushes into the hosted vault card form so it
742
- * matches the SDK-rendered (Stripe) card fields. The form's own surface stays
769
+ * matches the surrounding checkout fields. The form's own surface stays
743
770
  * transparent — these only drive the inputs, submit button, and overlay.
744
771
  */
745
772
  interface VaultCardThemeColors {
@@ -1466,10 +1493,9 @@ declare function getFloPayEnvironment(): FloPayEnvironment;
1466
1493
  declare const SDK_VERSION = "1.4.1";
1467
1494
  /**
1468
1495
  * HTTP header the SDK sends on `POST /v1/checkouts/sessions` so the backend
1469
- * can decide whether to embed the vault capture block (the hosted PCI card
1470
- * widget) in the create-session response. Backends at TeamFloPay/backend#823
1471
- * only serve the embedded `vault` block to SDKs that declare `>= 1.3.0` here;
1472
- * older SDKs are unaffected and keep the legacy Stripe card path.
1496
+ * provides compatibility visibility on session create/read requests. Vault
1497
+ * capability is part of the session contract and must not be gated by this
1498
+ * value.
1473
1499
  *
1474
1500
  * @see SDK_VERSION — the value sent in this header.
1475
1501
  */
@@ -1828,7 +1854,7 @@ declare function partitionStripeMethods(enabledPaymentMethods: readonly string[]
1828
1854
  paymentElementMethods: string[];
1829
1855
  };
1830
1856
  /** All supported element type identifiers. */
1831
- declare const ELEMENT_TYPES: readonly ["payment", "card", "cardNumber", "cardExpiry", "cardCvc", "address"];
1857
+ declare const ELEMENT_TYPES: readonly ["payment", "address"];
1832
1858
  declare const SUPPORTED_CARD_BRANDS: readonly ["visa", "mastercard", "mastercard_debit", "amex", "discover"];
1833
1859
  /** Country code to currency information mapping. */
1834
1860
  declare const CURRENCY_MAP: Record<string, CurrencyInfo>;
@@ -2114,4 +2140,24 @@ declare function generateIdempotencyKey(): string | undefined;
2114
2140
  */
2115
2141
  declare function resolveIdempotencyKey(supplied?: string): string | undefined;
2116
2142
 
2117
- export { type AVSFieldConfig, BILLING_API_URL, BILLING_API_URL_PRODUCTION, BILLING_API_URL_STAGING, BOLD_DARK_APPEARANCE, BOLD_LIGHT_APPEARANCE, BUTTONS_LAYOUT_BOLD_DARK, BUTTONS_LAYOUT_BOLD_LIGHT, BUTTONS_LAYOUT_DARK, BUTTONS_LAYOUT_DEFAULT, BUTTONS_LAYOUT_GLASS_DARK, BUTTONS_LAYOUT_GLASS_LIGHT, BUTTONS_LAYOUT_MINIMAL, BUTTONS_LAYOUT_MODERN_DARK, BUTTONS_LAYOUT_MODERN_LIGHT, BUTTONS_LAYOUT_ROUNDED, type BeforeButtonClickEvent, type BillingDetails, type BillingProvider, type BuildCheckoutDisplayDataOptions, type BuildTelemetryErrorEventInput, type BuildTelemetryLogEventInput, type BuildTelemetryPerformanceEventInput, type BuildTelemetryTerminalEventInput, type ButtonsLayoutStyles, type ButtonsLayoutTheme, CA_PROVINCES, COUNTRY_OPTIONS, CURRENCY_MAP, type CardCaptureAdapter, type CardCaptureEventType, type CardCaptureMountOptions, type CardCaptureOutcomeEvent, type CardCaptureProviderId, type CardThreeDsLifecycle, type CheckoutAccount, type CheckoutButtonMethod, type CheckoutDisplayData, type CheckoutGateway, type CheckoutGateways, type CheckoutItem, type CheckoutMode, type CheckoutModeKind, type CheckoutProcessError, type CheckoutProcessingPending, type CheckoutProduct, type CheckoutProductType, type CheckoutSession, type CheckoutSessionProduct, type CheckoutSessionResult, type CheckoutSubscription, type ConfirmCardPaymentParams, type ConfirmCardPaymentResult, type ConfirmPaymentParams, type CountryOption, type CreateCustomerParams, type CreatePaymentMethodResult, type CreateSessionParams, type CurrencyInfo, type Customer, DEFAULT_API_BASE_URL, DEFAULT_API_VERSION, DEFAULT_APPEARANCE, DEFAULT_CURRENCY, type DeclineEvent, type DisplayLineItem, ELEMENT_TYPES, type ElementChangeEvent, type ElementOptions, type ElementType, FLAT_APPEARANCE, FLO_SDK_VERSION_HEADER, type FloPayAppearance, type FloPayConfig, type FloPayEnvironment, FloPayError, type FloPayErrorType, type FloPayThemeVariables, GLASS_DARK_APPEARANCE, GLASS_LIGHT_APPEARANCE, type GatewayEnvironment, IDEMPOTENCY_IN_PROGRESS_CODE, IDEMPOTENCY_KEY_HEADER, type InlineSessionDraft, type InlineSessionParams, type InlineSessionPatch, type LineItem, MAX_IDEMPOTENCY_KEY_LENGTH, MODERN_DARK_APPEARANCE, MODERN_LIGHT_APPEARANCE, type MountedElement, NIGHT_APPEARANCE, type NormalizedCheckoutSession, type NormalizedGatewayEnvironment, type PaymentProviderAdapter, type PaymentResult, type PriceData, type ProcessPaymentParams, type RecurringInterval, SDK_VERSION, STRIPE_EXPRESS_METHODS, STRIPE_METHOD_AMOUNT_LIMITS, STRIPE_METHOD_COUNTRIES, STRIPE_METHOD_CURRENCIES, STRIPE_METHOD_MATRIX, SUPPORTED_CARD_BRANDS, type SerializeTelemetryBatchOptions, type StateOption, type StripeMethodEntry, type StripeMethodThemeVariant, TELEMETRY_ERROR_CODES, TELEMETRY_LOG_NAMES, TELEMETRY_MAX_BATCH_BYTES, TELEMETRY_MAX_BATCH_EVENTS, TELEMETRY_SCHEMA_VERSION, TELEMETRY_SDK_PACKAGES, THEMES, type TagsData, type TelemetryBatchEnvelope, type TelemetryCheckoutMode, type TelemetryDurationMode, type TelemetryErrorCode, type TelemetryErrorEvent, type TelemetryEvent, type TelemetryEventClass, type TelemetryExpectedOutcome, type TelemetryExpectedOutcomeEvent, type TelemetryLayout, type TelemetryLogEvent, type TelemetryLogName, type TelemetryPaymentMethodCategory, type TelemetryPerformanceEvent, type TelemetryProvider, type TelemetryProviderInput, type TelemetryRequestCategory, type TelemetrySdkPackage, type TelemetryStage, type TelemetryStatusClass, type ThemeBundle, type ThemeBundleId, type ThemeId, type TokenizedBody, US_STATES, type UpdateCustomerParams, type VaultCaptureBlock, type VaultCaptureResultMessage, type VaultCardFieldKey, type VaultCardThemeColors, type WebhookEvent, apiError, authenticationError, buildCheckoutDisplayData, buildItemPayload, buildProductPayload, buildSubscriptionPayload, buildTelemetryErrorEvent, buildTelemetryLogEvent, buildTelemetryPerformanceEvent, buildTelemetryTerminalEvent, configureFlopay, filterStripeMethodsByAmount, filterStripeMethodsByCountry, filterStripeMethodsByCurrency, foldIntoProducts, generateIdempotencyKey, getConfiguredBillingApiUrl, getCountryByCode, getCurrencyByCountry, getFloPayEnvironment, getPostalCodeExample, getPostalCodeLabel, getStateFromPostalCode, getStateLabel, getStateOptions, getStripeMethodDisplayName, hasVendoredStripeMethodLogo, isAVSEnabled, isAVSFieldVisible, isPostalCodeSupported, isSetupIntentClientSecret, isValidPostalCode, isValidPublishableKey, isValidSecretKey, needsStripeMethodExplicitConfirm, networkError, normalizeGatewayEnvironment, partitionStripeMethods, rateLimitError, resolveAVSConfig, resolveBillingApiUrl, resolveButtonsLayoutTheme, resolveIdempotencyKey, resolveSessionCurrency, resolveStripeMethodBrandVariant, resolveTheme, serializeTelemetryBatch, stripeExpressMethodToOptionKey, validationError };
2143
+ /**
2144
+ * RFC 4122 v4 UUID shape (case-insensitive). Mirrors the backend's `@IsUUID()`
2145
+ * acceptance for the fields the SDK fills, e.g. the session-intent
2146
+ * `authorizationAttemptId`.
2147
+ */
2148
+ declare const UUID_V4: RegExp;
2149
+ /** True when `value` is a v4 UUID string. */
2150
+ declare function isUuidV4(value: unknown): value is string;
2151
+ /**
2152
+ * Generate a cryptographically-random v4 UUID.
2153
+ *
2154
+ * Prefers `crypto.randomUUID()`, falls back to `crypto.getRandomValues`, and
2155
+ * only as a last resort to `Math.random`, so the SDK still produces a
2156
+ * well-formed UUID in environments without a secure RNG. Unlike
2157
+ * {@link generateIdempotencyKey} this never returns `undefined` or a non-UUID
2158
+ * string, because callers send it to backend fields validated as `@IsUUID()`
2159
+ * (a weak or missing value there is a hard `400`, not a silent downgrade).
2160
+ */
2161
+ declare function randomUuidV4(): string;
2162
+
2163
+ export { type AVSFieldConfig, BILLING_API_URL, BILLING_API_URL_PRODUCTION, BILLING_API_URL_STAGING, BOLD_DARK_APPEARANCE, BOLD_LIGHT_APPEARANCE, BUTTONS_LAYOUT_BOLD_DARK, BUTTONS_LAYOUT_BOLD_LIGHT, BUTTONS_LAYOUT_DARK, BUTTONS_LAYOUT_DEFAULT, BUTTONS_LAYOUT_GLASS_DARK, BUTTONS_LAYOUT_GLASS_LIGHT, BUTTONS_LAYOUT_MINIMAL, BUTTONS_LAYOUT_MODERN_DARK, BUTTONS_LAYOUT_MODERN_LIGHT, BUTTONS_LAYOUT_ROUNDED, type BeforeButtonClickEvent, type BillingDetails, type BillingProvider, type BuildCheckoutDisplayDataOptions, type BuildTelemetryErrorEventInput, type BuildTelemetryLogEventInput, type BuildTelemetryPerformanceEventInput, type BuildTelemetryTerminalEventInput, type ButtonsLayoutStyles, type ButtonsLayoutTheme, CA_PROVINCES, COUNTRY_OPTIONS, CURRENCY_MAP, type CardCaptureAdapter, type CardCaptureEventType, type CardCaptureMountOptions, type CardCaptureOutcomeEvent, type CardCaptureProviderId, type CheckoutAccount, type CheckoutButtonMethod, type CheckoutDisplayData, type CheckoutGateway, type CheckoutGateways, type CheckoutItem, type CheckoutMode, type CheckoutModeKind, type CheckoutProcessError, type CheckoutProcessingPending, type CheckoutProduct, type CheckoutProductType, type CheckoutSession, type CheckoutSessionProduct, type CheckoutSessionResult, type CheckoutSubscription, type ConfirmPaymentParams, type CountryOption, type CreateCustomerParams, type CreateSessionIntentRequest, type CreateSessionParams, type CurrencyInfo, type Customer, DEFAULT_API_BASE_URL, DEFAULT_API_VERSION, DEFAULT_APPEARANCE, DEFAULT_CURRENCY, type DeclineEvent, type DisplayLineItem, ELEMENT_TYPES, type ElementChangeEvent, type ElementOptions, type ElementType, FLAT_APPEARANCE, FLO_SDK_VERSION_HEADER, type FloPayAppearance, type FloPayConfig, type FloPayEnvironment, FloPayError, type FloPayErrorType, type FloPayThemeVariables, GLASS_DARK_APPEARANCE, GLASS_LIGHT_APPEARANCE, type GatewayEnvironment, IDEMPOTENCY_IN_PROGRESS_CODE, IDEMPOTENCY_KEY_HEADER, type InlineSessionDraft, type InlineSessionParams, type InlineSessionPatch, type LineItem, MAX_IDEMPOTENCY_KEY_LENGTH, MODERN_DARK_APPEARANCE, MODERN_LIGHT_APPEARANCE, type MountedElement, NIGHT_APPEARANCE, type NonCardPaymentMethodCategory, type NormalizedCheckoutSession, type NormalizedGatewayEnvironment, type PayPalPaymentResult, type PayPalSessionIntent, type PayPalSessionIntentRequest, type PaymentProviderAdapter, type PaymentResult, type PriceData, type ProcessPaymentParams, type RecurringInterval, SDK_VERSION, STRIPE_EXPRESS_METHODS, STRIPE_METHOD_AMOUNT_LIMITS, STRIPE_METHOD_COUNTRIES, STRIPE_METHOD_CURRENCIES, STRIPE_METHOD_MATRIX, SUPPORTED_CARD_BRANDS, type SerializeTelemetryBatchOptions, type SessionIntent, type SessionIntentDeclineRequest, type StateOption, type StripeMethodEntry, type StripeMethodThemeVariant, type StripeSessionIntent, type StripeSessionIntentRequest, TELEMETRY_ERROR_CODES, TELEMETRY_LOG_NAMES, TELEMETRY_MAX_BATCH_BYTES, TELEMETRY_MAX_BATCH_EVENTS, TELEMETRY_SCHEMA_VERSION, TELEMETRY_SDK_PACKAGES, THEMES, type TagsData, type TelemetryBatchEnvelope, type TelemetryCheckoutMode, type TelemetryDurationMode, type TelemetryErrorCode, type TelemetryErrorEvent, type TelemetryEvent, type TelemetryEventClass, type TelemetryExpectedOutcome, type TelemetryExpectedOutcomeEvent, type TelemetryLayout, type TelemetryLogEvent, type TelemetryLogName, type TelemetryPaymentMethodCategory, type TelemetryPerformanceEvent, type TelemetryProvider, type TelemetryProviderInput, type TelemetryRequestCategory, type TelemetrySdkPackage, type TelemetryStage, type TelemetryStatusClass, type ThemeBundle, type ThemeBundleId, type ThemeId, type TokenizedBody, US_STATES, UUID_V4, type UpdateCustomerParams, type VaultCaptureBlock, type VaultCaptureResultMessage, type VaultCardFieldKey, type VaultCardThemeColors, type WebhookEvent, apiError, authenticationError, buildCheckoutDisplayData, buildItemPayload, buildProductPayload, buildSubscriptionPayload, buildTelemetryErrorEvent, buildTelemetryLogEvent, buildTelemetryPerformanceEvent, buildTelemetryTerminalEvent, configureFlopay, filterStripeMethodsByAmount, filterStripeMethodsByCountry, filterStripeMethodsByCurrency, foldIntoProducts, generateIdempotencyKey, getConfiguredBillingApiUrl, getCountryByCode, getCurrencyByCountry, getFloPayEnvironment, getPostalCodeExample, getPostalCodeLabel, getStateFromPostalCode, getStateLabel, getStateOptions, getStripeMethodDisplayName, hasVendoredStripeMethodLogo, isAVSEnabled, isAVSFieldVisible, isPostalCodeSupported, isSetupIntentClientSecret, isUuidV4, isValidPostalCode, isValidPublishableKey, isValidSecretKey, needsStripeMethodExplicitConfirm, networkError, normalizeGatewayEnvironment, partitionStripeMethods, randomUuidV4, rateLimitError, resolveAVSConfig, resolveBillingApiUrl, resolveButtonsLayoutTheme, resolveIdempotencyKey, resolveSessionCurrency, resolveStripeMethodBrandVariant, resolveTheme, serializeTelemetryBatch, stripeExpressMethodToOptionKey, validationError };
package/dist/index.d.ts CHANGED
@@ -74,7 +74,7 @@ interface ButtonsLayoutStyles {
74
74
  * style config handed to the vault PCI card form, so these win over the
75
75
  * auto-translated `cardInput*` knobs and `appearance.variables`. Keys are
76
76
  * passed through verbatim — use vault-supported style property names.
77
- * No effect on the legacy Stripe-Elements card path.
77
+ * Applied only to the hosted vault card form.
78
78
  */
79
79
  vaultCardForm?: Record<string, string | number>;
80
80
  /** Style for the full-name text input. */
@@ -273,8 +273,8 @@ interface CheckoutGateway {
273
273
  * {@link STRIPE_EXPRESS_METHODS} to decide which methods render in the
274
274
  * `ExpressCheckoutElement` row (Apple Pay / Google Pay / PayPal / Link /
275
275
  * Amazon Pay / Klarna) vs the `PaymentElement` accordion (Cash App Pay /
276
- * Affirm / iDEAL / Bancontact / …). `card` is always filtered out — the
277
- * card path stays on the split-fields elements. Absent on legacy backends.
276
+ * Affirm / iDEAL / Bancontact / …). `card` is always filtered out because
277
+ * the hosted vault owns the card path. Absent on legacy backends.
278
278
  */
279
279
  enabledPaymentMethods?: string[];
280
280
  /**
@@ -311,12 +311,11 @@ interface CheckoutSession {
311
311
  metadata?: Record<string, string>;
312
312
  checkoutMode?: CheckoutMode;
313
313
  /**
314
- * Embedded hosted vault capture credentials (TeamFloPay/backend#823),
315
- * populated on the `POST /v1/checkouts/sessions` response when the SDK
316
- * declared `X-Flo-SDK-Version >= 1.3.0` and the backend advertises a
317
- * `pcivault` gateway. The SDK injects {@link VaultCaptureBlock.html} as the
318
- * card-capture widget. Absent on legacy backends or when the SDK must fetch
319
- * the block via `POST /v1/checkouts/sessions/{id}/vault/capture` instead.
314
+ * Embedded hosted vault capture credentials (TeamFloPay/backend#823).
315
+ * Card-capable session create/read responses include this block without
316
+ * SDK-version dispatch. The SDK injects {@link VaultCaptureBlock.html} as
317
+ * the card-capture widget; the explicit recovery path remains
318
+ * `POST /v1/checkouts/sessions/{id}/vault/capture`.
320
319
  */
321
320
  vault?: VaultCaptureBlock;
322
321
  /**
@@ -377,16 +376,19 @@ interface PaymentResult {
377
376
  checkoutMethod?: CheckoutButtonMethod;
378
377
  error?: FloPayError;
379
378
  }
380
- /** Parameters for confirming a payment. */
379
+ /** Parameters for confirming a wallet/APM payment from a mounted PaymentElement. */
381
380
  interface ConfirmPaymentParams {
382
381
  clientSecret: string;
382
+ /** Explicit non-card category for the selected payment method. */
383
+ paymentMethodCategory: NonCardPaymentMethodCategory;
384
+ /** Provider method type (for example `cashapp` or `ideal`); `card` is rejected. */
385
+ paymentMethodType: string;
383
386
  /** Optional redirect URL after 3-D Secure or wallet authentication. */
384
387
  returnUrl?: string;
385
388
  /**
386
389
  * Optional billing details appended to `payment_method_data` on the confirm call.
387
390
  * Ensures `billing_details.email` (and name/address) lands on the PaymentMethod
388
- * Stripe mints from Elements during 3DS confirmation — otherwise the new PM
389
- * inherits none of the info we attached at `createPaymentMethod` time.
391
+ * Stripe mints from Elements during 3DS confirmation.
390
392
  */
391
393
  billingDetails?: BillingDetails;
392
394
  }
@@ -403,33 +405,68 @@ interface BillingDetails {
403
405
  state?: string;
404
406
  };
405
407
  }
406
- /** Result from creating a payment method (tokenizing card fields). */
407
- interface CreatePaymentMethodResult {
408
- paymentMethodId: string | null;
409
- error?: FloPayError;
410
- }
411
- /** Parameters for confirming a card payment with a known client secret. */
412
- interface ConfirmCardPaymentParams {
413
- clientSecret: string;
414
- paymentMethodId: string;
415
- }
416
- /** Provider-observed 3DS lifecycle for one opaque, attempt-scoped confirmation. */
417
- interface CardThreeDsLifecycle {
418
- /** Opaque in-memory identifier; never derived from payment identifiers. */
419
- attemptId: string;
420
- status: 'handoff' | 'returned' | 'failed';
421
- }
422
- /** Result from confirming a card payment. */
423
- interface ConfirmCardPaymentResult {
408
+ /** Result from the Stripe-hosted PayPal confirmation or redirect-resume flow. */
409
+ interface PayPalPaymentResult {
424
410
  status: 'succeeded' | 'processing' | 'requires_action' | 'requires_capture' | 'failed';
425
411
  paymentIntentId?: string;
426
412
  paymentMethodId?: string;
427
413
  error?: FloPayError;
428
- /** @internal Provider-observed lifecycle used for privacy-safe telemetry. */
429
- threeDs?: CardThreeDsLifecycle;
430
414
  }
415
+ /** Non-card method families accepted by the public session intent endpoint. */
416
+ type NonCardPaymentMethodCategory = 'wallet' | 'apm';
417
+ /**
418
+ * Stable identity of one buyer authorization attempt (a v4 UUID).
419
+ *
420
+ * The backend folds this into the provider idempotency key, so reusing the same
421
+ * value makes a transport retry reuse the *same* provider intent, while a fresh
422
+ * value deliberately starts a new authorization. Optional on the SDK request:
423
+ * `PaymentAPI.createSessionIntent` generates one when omitted and only advanced
424
+ * callers that drive their own retries need to pass a stable value.
425
+ */
426
+ interface SessionIntentAuthorizationAttempt {
427
+ authorizationAttemptId?: string;
428
+ }
429
+ /** Stripe wallet/APM request. Direct card is deliberately not representable. */
430
+ interface StripeSessionIntentRequest extends SessionIntentAuthorizationAttempt {
431
+ provider: 'stripe';
432
+ paymentMethodCategory: NonCardPaymentMethodCategory;
433
+ paymentMethodType: string;
434
+ paymentMethodId: string | null;
435
+ intentKind: 'payment' | 'setup';
436
+ }
437
+ /** Direct PayPal order/subscription request. */
438
+ interface PayPalSessionIntentRequest extends SessionIntentAuthorizationAttempt {
439
+ provider: 'paypal';
440
+ paymentMethodCategory: 'wallet';
441
+ paymentMethodType: 'paypal';
442
+ paymentMethodId: null;
443
+ intentKind: 'order' | 'subscription';
444
+ }
445
+ type CreateSessionIntentRequest = StripeSessionIntentRequest | PayPalSessionIntentRequest;
446
+ interface StripeSessionIntent extends StripeSessionIntentRequest {
447
+ clientSecret: string;
448
+ providerObjectId: string;
449
+ }
450
+ interface PayPalSessionIntent extends PayPalSessionIntentRequest {
451
+ clientSecret: null;
452
+ providerObjectId: string;
453
+ }
454
+ type SessionIntent = StripeSessionIntent | PayPalSessionIntent;
455
+ type SessionIntentDeclineRequest = {
456
+ provider: 'stripe';
457
+ paymentMethodCategory: NonCardPaymentMethodCategory;
458
+ paymentMethodType: string;
459
+ /** Provider classification code only; messages and identifiers are rejected. */
460
+ providerDeclineReason: string;
461
+ } | {
462
+ provider: 'paypal';
463
+ paymentMethodCategory: 'wallet';
464
+ paymentMethodType: 'paypal';
465
+ /** Provider classification code only; messages and identifiers are rejected. */
466
+ providerDeclineReason: string;
467
+ };
431
468
  /** The type of payment element to render. */
432
- type ElementType = 'payment' | 'card' | 'cardNumber' | 'cardExpiry' | 'cardCvc' | 'address';
469
+ type ElementType = 'payment' | 'address';
433
470
  /** Emitted when an element's internal state changes. */
434
471
  interface ElementChangeEvent {
435
472
  elementType: ElementType;
@@ -445,7 +482,17 @@ interface ElementChangeEvent {
445
482
  /** Configuration options when creating an element. */
446
483
  interface ElementOptions {
447
484
  appearance?: FloPayAppearance;
448
- /** Client secret for the PaymentIntent or SetupIntent. When present, Stripe uses it directly. */
485
+ /**
486
+ * Explicit non-card provider method types rendered by a payment element.
487
+ * The SDK removes `card`; card collection belongs to the hosted vault.
488
+ */
489
+ paymentMethodTypes?: readonly string[];
490
+ /**
491
+ * Client secret for an existing non-card PaymentIntent or SetupIntent.
492
+ * The explicit `paymentMethodTypes` allowlist remains required; the SDK uses
493
+ * it to validate the provider intent before mounting. Card checkout uses the
494
+ * hosted vault.
495
+ */
449
496
  clientSecret?: string;
450
497
  /**
451
498
  * Total amount in the smallest currency unit (e.g. cents).
@@ -467,19 +514,6 @@ interface ElementOptions {
467
514
  readOnly?: boolean;
468
515
  /** Address element mode: 'billing' or 'shipping'. */
469
516
  mode?: 'billing' | 'shipping';
470
- /**
471
- * Style object for individual card elements (cardNumber, cardExpiry, cardCvc).
472
- * Passed directly to the underlying provider element.
473
- *
474
- * @example
475
- * ```ts
476
- * style: {
477
- * base: { color: '#f9fafb', fontSize: '16px', '::placeholder': { color: '#6b7280' } },
478
- * invalid: { color: '#ef4444' },
479
- * }
480
- * ```
481
- */
482
- style?: Record<string, Record<string, unknown>>;
483
517
  }
484
518
  /**
485
519
  * A payment element that has been created and can be mounted into the DOM.
@@ -528,18 +562,14 @@ interface PaymentProviderAdapter {
528
562
  submitElements(): Promise<{
529
563
  error?: FloPayError;
530
564
  }>;
531
- /** Create a payment method from the current elements (tokenize card). */
532
- createPaymentMethod(billingDetails?: BillingDetails): Promise<CreatePaymentMethodResult>;
533
- /** Confirm a card payment with a known client secret and payment method. */
534
- confirmCardPayment(params: ConfirmCardPaymentParams): Promise<ConfirmCardPaymentResult>;
565
+ /** Confirm a non-card wallet/APM payment from mounted elements. */
535
566
  confirmPayment(params: ConfirmPaymentParams): Promise<PaymentResult>;
536
567
  /**
537
568
  * Create a PayPal payment: create PM → create intent → confirm with redirect.
538
569
  * Returns the confirmed PaymentIntent ID if completed inline, or redirects to PayPal.
539
570
  *
540
- * `nonce` is the session-bound checkout token from session creation. Post-#640
541
- * backends reject `POST /v1/checkouts/payments/intents` with 401 when the
542
- * `x-checkout-session-token` header is missing — pass `nonce` to forward it.
571
+ * `nonce` is the session-bound checkout token forwarded to the
572
+ * session-scoped non-card intent contract.
543
573
  */
544
574
  confirmPayPalPayment(params: {
545
575
  billingApiUrl: string;
@@ -547,21 +577,18 @@ interface PaymentProviderAdapter {
547
577
  email: string;
548
578
  returnUrl: string;
549
579
  nonce?: string;
550
- }): Promise<ConfirmCardPaymentResult>;
580
+ }): Promise<PayPalPaymentResult>;
551
581
  /**
552
582
  * Resume a PayPal payment after redirect return.
553
583
  * Checks URL params for payment_intent + redirect_status.
554
584
  */
555
- resumePayPalPayment(): Promise<ConfirmCardPaymentResult | null>;
585
+ resumePayPalPayment(): Promise<PayPalPaymentResult | null>;
556
586
  /**
557
587
  * Get the raw underlying provider instance (e.g. Stripe object).
558
588
  * Used internally for creating secondary Elements groups (e.g. PayPal).
559
589
  */
560
590
  getRawProvider(): unknown;
561
- /**
562
- * Create a secondary Elements group for PayPal.
563
- * PayPal can't share Elements with card fields that use paymentMethodCreation: 'manual'.
564
- */
591
+ /** Create a secondary Elements group for PayPal's automatic payment-method flow. */
565
592
  createPayPalElements(options: ElementOptions): unknown;
566
593
  destroy(): void;
567
594
  }
@@ -576,8 +603,8 @@ type CardCaptureProviderId = 'pcivault';
576
603
  /**
577
604
  * Server-rendered hosted vault capture credentials (TeamFloPay/backend#823).
578
605
  *
579
- * Returned either embedded on the `POST /v1/checkouts/sessions` response (when
580
- * the SDK declared `X-Flo-SDK-Version >= 1.3.0`) or from the explicit
606
+ * Returned either embedded on every card-capable session create/read response
607
+ * or from the explicit
581
608
  * `POST /v1/checkouts/sessions/{id}/vault/capture` endpoint. `html` is a
582
609
  * self-contained, Flo-bundled hosted-form widget (PCIVault card fields, its own
583
610
  * submit button, status overlay, and — owned entirely by the backend — card
@@ -739,7 +766,7 @@ interface CardCaptureMountOptions {
739
766
  }
740
767
  /**
741
768
  * Merchant style values the SDK pushes into the hosted vault card form so it
742
- * matches the SDK-rendered (Stripe) card fields. The form's own surface stays
769
+ * matches the surrounding checkout fields. The form's own surface stays
743
770
  * transparent — these only drive the inputs, submit button, and overlay.
744
771
  */
745
772
  interface VaultCardThemeColors {
@@ -1466,10 +1493,9 @@ declare function getFloPayEnvironment(): FloPayEnvironment;
1466
1493
  declare const SDK_VERSION = "1.4.1";
1467
1494
  /**
1468
1495
  * HTTP header the SDK sends on `POST /v1/checkouts/sessions` so the backend
1469
- * can decide whether to embed the vault capture block (the hosted PCI card
1470
- * widget) in the create-session response. Backends at TeamFloPay/backend#823
1471
- * only serve the embedded `vault` block to SDKs that declare `>= 1.3.0` here;
1472
- * older SDKs are unaffected and keep the legacy Stripe card path.
1496
+ * provides compatibility visibility on session create/read requests. Vault
1497
+ * capability is part of the session contract and must not be gated by this
1498
+ * value.
1473
1499
  *
1474
1500
  * @see SDK_VERSION — the value sent in this header.
1475
1501
  */
@@ -1828,7 +1854,7 @@ declare function partitionStripeMethods(enabledPaymentMethods: readonly string[]
1828
1854
  paymentElementMethods: string[];
1829
1855
  };
1830
1856
  /** All supported element type identifiers. */
1831
- declare const ELEMENT_TYPES: readonly ["payment", "card", "cardNumber", "cardExpiry", "cardCvc", "address"];
1857
+ declare const ELEMENT_TYPES: readonly ["payment", "address"];
1832
1858
  declare const SUPPORTED_CARD_BRANDS: readonly ["visa", "mastercard", "mastercard_debit", "amex", "discover"];
1833
1859
  /** Country code to currency information mapping. */
1834
1860
  declare const CURRENCY_MAP: Record<string, CurrencyInfo>;
@@ -2114,4 +2140,24 @@ declare function generateIdempotencyKey(): string | undefined;
2114
2140
  */
2115
2141
  declare function resolveIdempotencyKey(supplied?: string): string | undefined;
2116
2142
 
2117
- export { type AVSFieldConfig, BILLING_API_URL, BILLING_API_URL_PRODUCTION, BILLING_API_URL_STAGING, BOLD_DARK_APPEARANCE, BOLD_LIGHT_APPEARANCE, BUTTONS_LAYOUT_BOLD_DARK, BUTTONS_LAYOUT_BOLD_LIGHT, BUTTONS_LAYOUT_DARK, BUTTONS_LAYOUT_DEFAULT, BUTTONS_LAYOUT_GLASS_DARK, BUTTONS_LAYOUT_GLASS_LIGHT, BUTTONS_LAYOUT_MINIMAL, BUTTONS_LAYOUT_MODERN_DARK, BUTTONS_LAYOUT_MODERN_LIGHT, BUTTONS_LAYOUT_ROUNDED, type BeforeButtonClickEvent, type BillingDetails, type BillingProvider, type BuildCheckoutDisplayDataOptions, type BuildTelemetryErrorEventInput, type BuildTelemetryLogEventInput, type BuildTelemetryPerformanceEventInput, type BuildTelemetryTerminalEventInput, type ButtonsLayoutStyles, type ButtonsLayoutTheme, CA_PROVINCES, COUNTRY_OPTIONS, CURRENCY_MAP, type CardCaptureAdapter, type CardCaptureEventType, type CardCaptureMountOptions, type CardCaptureOutcomeEvent, type CardCaptureProviderId, type CardThreeDsLifecycle, type CheckoutAccount, type CheckoutButtonMethod, type CheckoutDisplayData, type CheckoutGateway, type CheckoutGateways, type CheckoutItem, type CheckoutMode, type CheckoutModeKind, type CheckoutProcessError, type CheckoutProcessingPending, type CheckoutProduct, type CheckoutProductType, type CheckoutSession, type CheckoutSessionProduct, type CheckoutSessionResult, type CheckoutSubscription, type ConfirmCardPaymentParams, type ConfirmCardPaymentResult, type ConfirmPaymentParams, type CountryOption, type CreateCustomerParams, type CreatePaymentMethodResult, type CreateSessionParams, type CurrencyInfo, type Customer, DEFAULT_API_BASE_URL, DEFAULT_API_VERSION, DEFAULT_APPEARANCE, DEFAULT_CURRENCY, type DeclineEvent, type DisplayLineItem, ELEMENT_TYPES, type ElementChangeEvent, type ElementOptions, type ElementType, FLAT_APPEARANCE, FLO_SDK_VERSION_HEADER, type FloPayAppearance, type FloPayConfig, type FloPayEnvironment, FloPayError, type FloPayErrorType, type FloPayThemeVariables, GLASS_DARK_APPEARANCE, GLASS_LIGHT_APPEARANCE, type GatewayEnvironment, IDEMPOTENCY_IN_PROGRESS_CODE, IDEMPOTENCY_KEY_HEADER, type InlineSessionDraft, type InlineSessionParams, type InlineSessionPatch, type LineItem, MAX_IDEMPOTENCY_KEY_LENGTH, MODERN_DARK_APPEARANCE, MODERN_LIGHT_APPEARANCE, type MountedElement, NIGHT_APPEARANCE, type NormalizedCheckoutSession, type NormalizedGatewayEnvironment, type PaymentProviderAdapter, type PaymentResult, type PriceData, type ProcessPaymentParams, type RecurringInterval, SDK_VERSION, STRIPE_EXPRESS_METHODS, STRIPE_METHOD_AMOUNT_LIMITS, STRIPE_METHOD_COUNTRIES, STRIPE_METHOD_CURRENCIES, STRIPE_METHOD_MATRIX, SUPPORTED_CARD_BRANDS, type SerializeTelemetryBatchOptions, type StateOption, type StripeMethodEntry, type StripeMethodThemeVariant, TELEMETRY_ERROR_CODES, TELEMETRY_LOG_NAMES, TELEMETRY_MAX_BATCH_BYTES, TELEMETRY_MAX_BATCH_EVENTS, TELEMETRY_SCHEMA_VERSION, TELEMETRY_SDK_PACKAGES, THEMES, type TagsData, type TelemetryBatchEnvelope, type TelemetryCheckoutMode, type TelemetryDurationMode, type TelemetryErrorCode, type TelemetryErrorEvent, type TelemetryEvent, type TelemetryEventClass, type TelemetryExpectedOutcome, type TelemetryExpectedOutcomeEvent, type TelemetryLayout, type TelemetryLogEvent, type TelemetryLogName, type TelemetryPaymentMethodCategory, type TelemetryPerformanceEvent, type TelemetryProvider, type TelemetryProviderInput, type TelemetryRequestCategory, type TelemetrySdkPackage, type TelemetryStage, type TelemetryStatusClass, type ThemeBundle, type ThemeBundleId, type ThemeId, type TokenizedBody, US_STATES, type UpdateCustomerParams, type VaultCaptureBlock, type VaultCaptureResultMessage, type VaultCardFieldKey, type VaultCardThemeColors, type WebhookEvent, apiError, authenticationError, buildCheckoutDisplayData, buildItemPayload, buildProductPayload, buildSubscriptionPayload, buildTelemetryErrorEvent, buildTelemetryLogEvent, buildTelemetryPerformanceEvent, buildTelemetryTerminalEvent, configureFlopay, filterStripeMethodsByAmount, filterStripeMethodsByCountry, filterStripeMethodsByCurrency, foldIntoProducts, generateIdempotencyKey, getConfiguredBillingApiUrl, getCountryByCode, getCurrencyByCountry, getFloPayEnvironment, getPostalCodeExample, getPostalCodeLabel, getStateFromPostalCode, getStateLabel, getStateOptions, getStripeMethodDisplayName, hasVendoredStripeMethodLogo, isAVSEnabled, isAVSFieldVisible, isPostalCodeSupported, isSetupIntentClientSecret, isValidPostalCode, isValidPublishableKey, isValidSecretKey, needsStripeMethodExplicitConfirm, networkError, normalizeGatewayEnvironment, partitionStripeMethods, rateLimitError, resolveAVSConfig, resolveBillingApiUrl, resolveButtonsLayoutTheme, resolveIdempotencyKey, resolveSessionCurrency, resolveStripeMethodBrandVariant, resolveTheme, serializeTelemetryBatch, stripeExpressMethodToOptionKey, validationError };
2143
+ /**
2144
+ * RFC 4122 v4 UUID shape (case-insensitive). Mirrors the backend's `@IsUUID()`
2145
+ * acceptance for the fields the SDK fills, e.g. the session-intent
2146
+ * `authorizationAttemptId`.
2147
+ */
2148
+ declare const UUID_V4: RegExp;
2149
+ /** True when `value` is a v4 UUID string. */
2150
+ declare function isUuidV4(value: unknown): value is string;
2151
+ /**
2152
+ * Generate a cryptographically-random v4 UUID.
2153
+ *
2154
+ * Prefers `crypto.randomUUID()`, falls back to `crypto.getRandomValues`, and
2155
+ * only as a last resort to `Math.random`, so the SDK still produces a
2156
+ * well-formed UUID in environments without a secure RNG. Unlike
2157
+ * {@link generateIdempotencyKey} this never returns `undefined` or a non-UUID
2158
+ * string, because callers send it to backend fields validated as `@IsUUID()`
2159
+ * (a weak or missing value there is a hard `400`, not a silent downgrade).
2160
+ */
2161
+ declare function randomUuidV4(): string;
2162
+
2163
+ export { type AVSFieldConfig, BILLING_API_URL, BILLING_API_URL_PRODUCTION, BILLING_API_URL_STAGING, BOLD_DARK_APPEARANCE, BOLD_LIGHT_APPEARANCE, BUTTONS_LAYOUT_BOLD_DARK, BUTTONS_LAYOUT_BOLD_LIGHT, BUTTONS_LAYOUT_DARK, BUTTONS_LAYOUT_DEFAULT, BUTTONS_LAYOUT_GLASS_DARK, BUTTONS_LAYOUT_GLASS_LIGHT, BUTTONS_LAYOUT_MINIMAL, BUTTONS_LAYOUT_MODERN_DARK, BUTTONS_LAYOUT_MODERN_LIGHT, BUTTONS_LAYOUT_ROUNDED, type BeforeButtonClickEvent, type BillingDetails, type BillingProvider, type BuildCheckoutDisplayDataOptions, type BuildTelemetryErrorEventInput, type BuildTelemetryLogEventInput, type BuildTelemetryPerformanceEventInput, type BuildTelemetryTerminalEventInput, type ButtonsLayoutStyles, type ButtonsLayoutTheme, CA_PROVINCES, COUNTRY_OPTIONS, CURRENCY_MAP, type CardCaptureAdapter, type CardCaptureEventType, type CardCaptureMountOptions, type CardCaptureOutcomeEvent, type CardCaptureProviderId, type CheckoutAccount, type CheckoutButtonMethod, type CheckoutDisplayData, type CheckoutGateway, type CheckoutGateways, type CheckoutItem, type CheckoutMode, type CheckoutModeKind, type CheckoutProcessError, type CheckoutProcessingPending, type CheckoutProduct, type CheckoutProductType, type CheckoutSession, type CheckoutSessionProduct, type CheckoutSessionResult, type CheckoutSubscription, type ConfirmPaymentParams, type CountryOption, type CreateCustomerParams, type CreateSessionIntentRequest, type CreateSessionParams, type CurrencyInfo, type Customer, DEFAULT_API_BASE_URL, DEFAULT_API_VERSION, DEFAULT_APPEARANCE, DEFAULT_CURRENCY, type DeclineEvent, type DisplayLineItem, ELEMENT_TYPES, type ElementChangeEvent, type ElementOptions, type ElementType, FLAT_APPEARANCE, FLO_SDK_VERSION_HEADER, type FloPayAppearance, type FloPayConfig, type FloPayEnvironment, FloPayError, type FloPayErrorType, type FloPayThemeVariables, GLASS_DARK_APPEARANCE, GLASS_LIGHT_APPEARANCE, type GatewayEnvironment, IDEMPOTENCY_IN_PROGRESS_CODE, IDEMPOTENCY_KEY_HEADER, type InlineSessionDraft, type InlineSessionParams, type InlineSessionPatch, type LineItem, MAX_IDEMPOTENCY_KEY_LENGTH, MODERN_DARK_APPEARANCE, MODERN_LIGHT_APPEARANCE, type MountedElement, NIGHT_APPEARANCE, type NonCardPaymentMethodCategory, type NormalizedCheckoutSession, type NormalizedGatewayEnvironment, type PayPalPaymentResult, type PayPalSessionIntent, type PayPalSessionIntentRequest, type PaymentProviderAdapter, type PaymentResult, type PriceData, type ProcessPaymentParams, type RecurringInterval, SDK_VERSION, STRIPE_EXPRESS_METHODS, STRIPE_METHOD_AMOUNT_LIMITS, STRIPE_METHOD_COUNTRIES, STRIPE_METHOD_CURRENCIES, STRIPE_METHOD_MATRIX, SUPPORTED_CARD_BRANDS, type SerializeTelemetryBatchOptions, type SessionIntent, type SessionIntentDeclineRequest, type StateOption, type StripeMethodEntry, type StripeMethodThemeVariant, type StripeSessionIntent, type StripeSessionIntentRequest, TELEMETRY_ERROR_CODES, TELEMETRY_LOG_NAMES, TELEMETRY_MAX_BATCH_BYTES, TELEMETRY_MAX_BATCH_EVENTS, TELEMETRY_SCHEMA_VERSION, TELEMETRY_SDK_PACKAGES, THEMES, type TagsData, type TelemetryBatchEnvelope, type TelemetryCheckoutMode, type TelemetryDurationMode, type TelemetryErrorCode, type TelemetryErrorEvent, type TelemetryEvent, type TelemetryEventClass, type TelemetryExpectedOutcome, type TelemetryExpectedOutcomeEvent, type TelemetryLayout, type TelemetryLogEvent, type TelemetryLogName, type TelemetryPaymentMethodCategory, type TelemetryPerformanceEvent, type TelemetryProvider, type TelemetryProviderInput, type TelemetryRequestCategory, type TelemetrySdkPackage, type TelemetryStage, type TelemetryStatusClass, type ThemeBundle, type ThemeBundleId, type ThemeId, type TokenizedBody, US_STATES, UUID_V4, type UpdateCustomerParams, type VaultCaptureBlock, type VaultCaptureResultMessage, type VaultCardFieldKey, type VaultCardThemeColors, type WebhookEvent, apiError, authenticationError, buildCheckoutDisplayData, buildItemPayload, buildProductPayload, buildSubscriptionPayload, buildTelemetryErrorEvent, buildTelemetryLogEvent, buildTelemetryPerformanceEvent, buildTelemetryTerminalEvent, configureFlopay, filterStripeMethodsByAmount, filterStripeMethodsByCountry, filterStripeMethodsByCurrency, foldIntoProducts, generateIdempotencyKey, getConfiguredBillingApiUrl, getCountryByCode, getCurrencyByCountry, getFloPayEnvironment, getPostalCodeExample, getPostalCodeLabel, getStateFromPostalCode, getStateLabel, getStateOptions, getStripeMethodDisplayName, hasVendoredStripeMethodLogo, isAVSEnabled, isAVSFieldVisible, isPostalCodeSupported, isSetupIntentClientSecret, isUuidV4, isValidPostalCode, isValidPublishableKey, isValidSecretKey, needsStripeMethodExplicitConfirm, networkError, normalizeGatewayEnvironment, partitionStripeMethods, randomUuidV4, rateLimitError, resolveAVSConfig, resolveBillingApiUrl, resolveButtonsLayoutTheme, resolveIdempotencyKey, resolveSessionCurrency, resolveStripeMethodBrandVariant, resolveTheme, serializeTelemetryBatch, stripeExpressMethodToOptionKey, validationError };