@authvia/payment-method-create 1.0.18 → 2.0.0

package/dist/types/applePay/payment.d.ts

@@ -0,0 +1,38 @@
+import { ApplePayCardType } from './common';
+/** Apple `ApplePayPaymentContact` as received on `billingContact`. */
+export interface ApplePayContact {
+    phoneNumber?: string;
+    emailAddress?: string;
+    givenName?: string;
+    familyName?: string;
+    phoneticGivenName?: string;
+    phoneticFamilyName?: string;
+    addressLines?: string[];
+    subLocality?: string;
+    locality?: string;
+    postalCode?: string;
+    subAdministrativeArea?: string;
+    administrativeArea?: string;
+    country?: string;
+    countryCode?: string;
+}
+export interface ApplePayPaymentToken {
+    paymentData?: unknown;
+    paymentMethod?: {
+        displayName?: string;
+        network?: string;
+        type?: ApplePayCardType;
+    };
+    transactionIdentifier?: string;
+}
+/** Payload from Apple `onpaymentauthorized`. */
+export interface ApplePayAuthorizedPayment {
+    token?: ApplePayPaymentToken;
+    billingContact?: ApplePayContact;
+    shippingContact?: unknown;
+}
+export interface ApplePayPaymentMethodCreatePayload {
+    type: 'ApplePay';
+    token: NonNullable<ApplePayAuthorizedPayment['token']>;
+    address?: ApplePayContact;
+}

package/dist/types/applePay/sdk.d.ts

@@ -0,0 +1,93 @@
+import { ApplePayBillingContactField, ApplePayCardType, ApplePayCredentialStatus, ApplePayLineItemType, ApplePayRecurringInterval } from './common';
+import { ApplePayAuthorizedPayment } from './payment';
+export type { ApplePayBillingContactField, ApplePayCardType, ApplePayCredentialStatus, ApplePayLineItemType, ApplePayRecurringInterval, } from './common';
+export interface ApplePayCapabilitiesResponse {
+    paymentCredentialStatus?: ApplePayCredentialStatus;
+}
+/** A line item as Apple renders it on the sheet. `pending` hides the amount and shows "Pending". */
+export interface ApplePayLineItem {
+    label: string;
+    amount: string;
+    type?: ApplePayLineItemType;
+    paymentTiming?: 'immediate' | 'recurring' | 'deferred' | 'automaticReload';
+    deferredPaymentDate?: Date;
+    recurringPaymentStartDate?: Date;
+    recurringPaymentEndDate?: Date;
+    recurringPaymentIntervalUnit?: ApplePayRecurringInterval;
+    recurringPaymentIntervalCount?: number;
+}
+/** Declares a future charge; makes Apple issue a merchant token (MPAN). Requires version 14. */
+export interface ApplePayDeferredPaymentRequest {
+    paymentDescription: string;
+    managementURL: string;
+    deferredBilling: ApplePayLineItem;
+    billingAgreement?: string;
+    tokenNotificationURL?: string;
+    freeCancellationDate?: Date;
+    freeCancellationDateTimeZone?: string;
+}
+/** Declares fixed-interval billing; mutually exclusive with `deferredPaymentRequest`. */
+export interface ApplePayRecurringPaymentRequest {
+    paymentDescription: string;
+    managementURL: string;
+    regularBilling: ApplePayLineItem;
+    trialBilling?: ApplePayLineItem;
+    billingAgreement?: string;
+    tokenNotificationURL?: string;
+}
+/** Minimal Apple Pay payment request; Apple requires a total even when only saving a card. */
+export interface ApplePayPaymentRequest {
+    countryCode: string;
+    currencyCode: string;
+    merchantCapabilities: string[];
+    supportedNetworks: string[];
+    total: {
+        label: string;
+        amount: string;
+        type?: ApplePayLineItemType;
+    };
+    lineItems?: ApplePayLineItem[];
+    requiredBillingContactFields?: ApplePayBillingContactField[];
+    deferredPaymentRequest?: ApplePayDeferredPaymentRequest;
+    recurringPaymentRequest?: ApplePayRecurringPaymentRequest;
+}
+/** The card the person selected on the sheet. `type` is what surcharge rules key off. */
+export interface ApplePaySelectedPaymentMethod {
+    displayName?: string;
+    network?: string;
+    type?: ApplePayCardType;
+}
+/** Revised totals handed back from `onpaymentmethodselected`. */
+export interface ApplePayPaymentMethodUpdate {
+    newTotal: {
+        label: string;
+        amount: string;
+        type?: ApplePayLineItemType;
+    };
+    newLineItems?: ApplePayLineItem[];
+}
+export interface ApplePaySessionInstance {
+    onvalidatemerchant: ((event: {
+        validationURL: string;
+    }) => void) | null;
+    onpaymentauthorized: ((event: {
+        payment: ApplePayAuthorizedPayment;
+    }) => void) | null;
+    onpaymentmethodselected: ((event: {
+        paymentMethod: ApplePaySelectedPaymentMethod;
+    }) => void) | null;
+    oncancel: ((event?: unknown) => void) | null;
+    begin: () => void;
+    abort: () => void;
+    completeMerchantValidation: (merchantSession: unknown) => void;
+    completePaymentMethodSelection: (update: ApplePayPaymentMethodUpdate) => void;
+    completePayment: (result: {
+        status: number;
+    }) => void;
+}
+export interface ApplePaySessionStatic {
+    new (version: number, request: ApplePayPaymentRequest): ApplePaySessionInstance;
+    canMakePayments?: () => boolean;
+    applePayCapabilities?: (merchantIdentifier: string) => Promise<ApplePayCapabilitiesResponse>;
+    supportsVersion?: (version: number) => boolean;
+}

package/dist/types/applePay/session.d.ts

@@ -0,0 +1,30 @@
+import { ApplePayConfig } from './config';
+import { ApplePayAuthorizedPayment } from './payment';
+import { ApplePayPaymentRequest } from './sdk';
+import { PaymentMethodErrorPayload } from '..';
+/** Saved payment method id returned after a successful Apple Pay authorization. */
+export type ApplePayPaymentMethodSuccessResult = string | {
+    id: string;
+    forgetCard?: boolean;
+};
+export interface ApplePaySessionStartInput {
+    applePay?: boolean | ApplePayConfig;
+    merchantId?: string;
+    token?: string;
+    fetchMerchantSession?: () => Promise<unknown>;
+    submitApplePayPaymentMethod?: (payment: ApplePayAuthorizedPayment) => Promise<ApplePayPaymentMethodSuccessResult>;
+}
+export interface ApplePaySessionStartCallbacks {
+    onSuccess: (paymentMethodId: ApplePayPaymentMethodSuccessResult) => void;
+    onError: (error: PaymentMethodErrorPayload) => void;
+    onCancel: () => void;
+}
+export interface ApplePaySessionDiagnostics {
+    configuredDomain: string;
+    pageOrigin: string | undefined;
+    merchantSession: Record<string, unknown> | null;
+    paymentRequest: ApplePayPaymentRequest;
+    merchantValidationCompleted: boolean;
+    paymentAuthorized: boolean;
+    authorizedTotal?: string;
+}

package/dist/types/index.d.ts

@@ -1,6 +1,7 @@
 import { PaymentMethodType } from '../model';
+import { ApplePayConfig } from './applePay';
 /**
- * Runtime error from a specific payment method flow (card, ACH, Paze, PayPal, Venmo).
+ * Runtime error from a specific payment method flow (card, ACH, Paze, PayPal, Venmo, Apple Pay).
  * Inner components attach `type` so hosts can branch without parsing `message`.
  */
 export interface PaymentMethodFlowError {
@@ -32,6 +33,7 @@ export interface PaymentMethodDisplayConfigMap {
     paypal?: PaymentMethodDisplayText;
     paze?: PaymentMethodDisplayText;
     venmo?: PaymentMethodDisplayText;
+    applePay?: PaymentMethodDisplayText;
 }
 /** Keys under `paymentMethodDisplay` that configure a single method (excludes list-level `gap`). */
 export type PaymentMethodDisplayRowKey = Exclude<keyof PaymentMethodDisplayConfigMap, 'gap'>;
@@ -112,6 +114,11 @@ export interface AuthviaPaymentMethodFormProps {
         profileId?: string;
         name?: string;
     };
+    /**
+     * `true`, or `{ partnerInternalMerchantIdentifier, countryCode?, currencyCode?, amount? }`.
+     * `partnerInternalMerchantIdentifier` (or form `merchantId`) is required to open the Apple Pay sheet.
+     */
+    applePay?: boolean | ApplePayConfig;
     intent?: string;
     customerRef?: string;
     variant?: VuetifyProps['variant'];
@@ -279,6 +286,8 @@ export interface AuthviaPaymentMethodFormPluginOptions {
     pazeSDKURL: string;
     plaidEnv: string;
     paypalSDKURL: string;
+    /** Apple Pay JS SDK script URL; falls back to `VITE_APPLE_PAY_SDK_URL` then Apple's CDN. */
+    applePaySDKURL?: string;
     paypalClientId: string;
     paypalEnvironment?: string;
 }

package/dist/types/paymentMethodOptions.d.ts

@@ -26,6 +26,8 @@ export interface PaymentMethodOptionsProps {
     achBillingAddress?: PaymentMethodBillingAddress;
     pzSettings?: Record<string, unknown>;
     pvSettings?: Record<string, unknown>;
+    /** Apple Pay config (`partnerInternalMerchantIdentifier`, `countryCode`, `currencyCode`, `amount`). */
+    apSettings?: Record<string, unknown>;
     forgetHidden?: boolean;
     forgetDefault?: boolean;
     color?: string;

package/dist/utils/applePay/constants.d.ts

@@ -0,0 +1,9 @@
+/** Card networks Apple accepts on the payment sheet when the host does not override them. */
+export declare const DEFAULT_APPLE_PAY_SUPPORTED_NETWORKS: readonly string[];
+/**
+ * Default merchant capabilities. Only `supports3DS` is listed: naming `supportsCredit` or
+ * `supportsDebit` alone excludes the other card type from the sheet.
+ */
+export declare const DEFAULT_APPLE_PAY_MERCHANT_CAPABILITIES: readonly string[];
+export declare const APPLE_PAY_RECURRING_INTERVALS: readonly string[];
+export declare const MERCHANT_SESSION_KEYS: readonly string[];

package/dist/utils/applePay/deferredFlow.d.ts

@@ -0,0 +1,18 @@
+import { ApplePayDeferredPaymentRequest } from '../../types/applePay/sdk';
+import { ApplePayConfig } from './types';
+/** True when the host asked for the stored-credential flow by supplying a `deferred` block. */
+export declare function isApplePayDeferredRequested(applePay: boolean | ApplePayConfig | undefined): boolean;
+/**
+ * Validates the `deferred` block against what Apple marks required.
+ *
+ * @param applePay - The `applePay` prop
+ * @returns A host-facing message describing the first problem, or `null` when valid
+ */
+export declare function validateApplePayDeferredConfig(applePay: boolean | ApplePayConfig | undefined): string | null;
+/**
+ * Builds Apple's `deferredPaymentRequest` from the `deferred` block.
+ *
+ * @param applePay - The `applePay` prop
+ * @returns The request block, or `null` when the host did not ask for this flow
+ */
+export declare function buildApplePayDeferredPaymentRequest(applePay: boolean | ApplePayConfig | undefined): ApplePayDeferredPaymentRequest | null;

package/dist/utils/applePay/device.d.ts

@@ -0,0 +1,9 @@
+/** True on iPhone/iPad where the native Apple Pay sheet should be used. */
+export declare function isIOSApplePayDevice(): boolean;
+/** True when the browser is Safari (not Chrome/Edge/Firefox shells that also report Safari). */
+export declare function isSafariBrowser(): boolean;
+/**
+ * Non-iOS browsers such as desktop Chrome open Apple's scan-with-iPhone QR immediately
+ * instead of showing a separate Apple Pay button screen.
+ */
+export declare function shouldAutoStartApplePayQr(): boolean;

package/dist/utils/applePay/diagnostics.d.ts

@@ -0,0 +1,12 @@
+import { ApplePaySessionFailureDiagnostics } from './types';
+/** Safe summary of Apple `oncancel` event (sessionError code/info when provided). */
+export declare function summarizeApplePayCancelEvent(...args: unknown[]): Record<string, unknown>;
+/** Non-sensitive merchant session fields useful when cancel has no Apple error payload. */
+export declare function summarizeApplePayMerchantSessionForLog(session: unknown): Record<string, unknown> | null;
+/**
+ * Best-effort diagnosis when Apple cancels after validation (Chrome QR gives no sessionError).
+ * Returns human-readable findings for logs and UI.
+ */
+export declare function diagnoseApplePaySessionFailure(diagnostics: ApplePaySessionFailureDiagnostics): string[];
+/** User-facing message when authorization fails after successful merchant validation. */
+export declare function buildApplePayAuthorizationFailureMessage(diagnostics: ApplePaySessionFailureDiagnostics, fallbackMessage: string): string;

package/dist/utils/applePay/paymentPayload.d.ts

@@ -0,0 +1,14 @@
+import { ApplePayAuthorizedPayment, ApplePayContact, ApplePayPaymentMethodCreatePayload } from './types';
+/** Token object from Apple `onpaymentauthorized` → POST .../payment-methods body. */
+export declare function extractApplePayTokenForCreate(payment: unknown): NonNullable<ApplePayAuthorizedPayment['token']> | null;
+/**
+ * Apple's `billingContact` exactly as received, or `null` when Apple sent nothing.
+ *
+ * Returning `null` for an empty object keeps the key out of the create body instead of
+ * posting `{}`.
+ */
+export declare function extractApplePayBillingContact(payment: unknown): ApplePayContact | null;
+/** Builds POST /v3/users/{userId}/payment-methods body from Apple authorization. */
+export declare function buildApplePayPaymentMethodCreatePayload(payment: unknown): ApplePayPaymentMethodCreatePayload | null;
+/** Safe fields for logs; omit encrypted paymentData unless dev logging is enabled separately. */
+export declare function summarizeApplePayAuthorizedPayment(payment: unknown): Record<string, unknown>;

package/dist/utils/applePay/propAccess.d.ts

@@ -0,0 +1,23 @@
+import { ApplePayConfig } from './types';
+/** Returns true when the host enabled Apple Pay via `applePay: true` or a config object. */
+export declare function isApplePayPropEnabled(applePay: boolean | ApplePayConfig | undefined): boolean;
+/** Normalizes the `applePay` prop to a config object. */
+export declare function toApplePayConfig(applePay: boolean | ApplePayConfig | undefined): ApplePayConfig;
+/**
+ * Authvia partner merchant ref from the `applePay` prop, or `fallbackMerchantId` when omitted.
+ * Used for backend merchant-validation and payment-method APIs (not Apple's merchant.com ID).
+ */
+export declare function getApplePayPartnerInternalMerchantIdentifier(applePay: boolean | ApplePayConfig | undefined, fallbackMerchantId?: string): string;
+/** Domain registered with Apple for merchant validation; defaults to the page hostname. */
+export declare function getApplePayDomain(applePay: boolean | ApplePayConfig | undefined): string;
+/** Card networks for the Apple Pay payment request; host override or {@link DEFAULT_APPLE_PAY_SUPPORTED_NETWORKS}. */
+export declare function getApplePaySupportedNetworks(applePay: boolean | ApplePayConfig | undefined): string[];
+/**
+ * Merchant capabilities for the Apple Pay payment request.
+ *
+ * An explicit `merchantCapabilities` list always wins - it is the escape hatch for anything this
+ * helper does not model, such as `supportsEMV` for China Union Pay. Otherwise `acceptedCardTypes`
+ * composes the list: naming `supportsCredit` or `supportsDebit` alone makes Apple grey out the
+ * other category on the sheet, while naming both or neither allows both.
+ */
+export declare function getApplePayMerchantCapabilities(applePay: boolean | ApplePayConfig | undefined): string[];

package/dist/utils/applePay/recurringFlow.d.ts

@@ -0,0 +1,20 @@
+import { ApplePayRecurringPaymentRequest } from '../../types/applePay/sdk';
+import { ApplePayConfig } from './types';
+/** True when the host asked for the recurring stored-credential flow. */
+export declare function isApplePayRecurringRequested(applePay: boolean | ApplePayConfig | undefined): boolean;
+/** True when either stored-credential flow was requested. */
+export declare function isApplePayStoredCredentialRequested(applePay: boolean | ApplePayConfig | undefined): boolean;
+/**
+ * Validates the `recurring` block, and that only one stored-credential flow was requested.
+ *
+ * @param applePay - The `applePay` prop
+ * @returns A host-facing message describing the first problem, or `null` when valid
+ */
+export declare function validateApplePayRecurringConfig(applePay: boolean | ApplePayConfig | undefined): string | null;
+/**
+ * Builds Apple's `recurringPaymentRequest` from the `recurring` block.
+ *
+ * @param applePay - The `applePay` prop
+ * @returns The request block, or `null` when the host did not ask for this flow
+ */
+export declare function buildApplePayRecurringPaymentRequest(applePay: boolean | ApplePayConfig | undefined): ApplePayRecurringPaymentRequest | null;

package/dist/utils/applePay/sessionToken.d.ts

@@ -0,0 +1,5 @@
+import { ApplePayConfig, ApplePaySessionTokenRequest } from './types';
+/** Builds the Apple Pay session token request from form props. */
+export declare function buildApplePaySessionTokenRequest(applePay: boolean | ApplePayConfig | undefined, merchantId: string | undefined): ApplePaySessionTokenRequest | null;
+/** Normalizes Authvia API responses to the object passed to completeMerchantValidation(). */
+export declare function extractApplePayMerchantSession(body: unknown): unknown;

package/dist/utils/applePay/strings.d.ts

@@ -0,0 +1,3 @@
+/** Trims optional strings used across Apple Pay config builders. */
+export declare function trimmed(value: string | undefined): string;
+export declare function normalizeApplePayStringList(values: string[] | undefined, fallback: readonly string[]): string[];

package/dist/utils/applePay/surcharge.d.ts

@@ -0,0 +1,33 @@
+import { ApplePayPaymentMethodUpdate, ApplePaySelectedPaymentMethod } from '../../types/applePay/sdk';
+import { ApplePayCardType, ApplePayConfig } from './types';
+/** True when the host configured a surcharge that could change the total. */
+export declare function isApplePaySurchargeConfigured(applePay: boolean | ApplePayConfig | undefined): boolean;
+/** Money is handled in integer cents throughout; floats lose pennies at some values. */
+export declare function toApplePayCents(amount: string | number | undefined): number;
+/** Formats cents back to Apple's required `-?[0-9]+(\.[0-9][0-9])?`. */
+export declare function fromApplePayCents(cents: number): string;
+/**
+ * Surcharge in cents for the selected card, or 0 when none applies.
+ *
+ * @param applePay - The `applePay` prop
+ * @param baseCents - The pre-surcharge total, in cents
+ * @param cardType - `type` from the selected payment method; may be absent
+ * @returns Surcharge in cents
+ */
+export declare function resolveApplePaySurchargeCents(applePay: boolean | ApplePayConfig | undefined, baseCents: number, cardType: ApplePayCardType | undefined): number;
+/**
+ * Revised totals to hand to `completePaymentMethodSelection` when a card is selected.
+ *
+ * Apple requires a response within 30 seconds, so this is pure and synchronous - no lookups.
+ *
+ * @param applePay - The `applePay` prop
+ * @param baseAmount - The pre-surcharge total
+ * @param totalLabel - Label for the total row (the merchant's statement name)
+ * @param paymentMethod - The card the person selected
+ * @returns The update, and the surcharged total for the host to reconcile against
+ */
+export declare function buildApplePayPaymentMethodUpdate(applePay: boolean | ApplePayConfig | undefined, baseAmount: string, totalLabel: string, paymentMethod: ApplePaySelectedPaymentMethod | undefined): {
+    update: ApplePayPaymentMethodUpdate;
+    totalAmount: string;
+    surchargeAmount: string;
+};

package/dist/utils/applePay/types.d.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from `@/types/applePay` instead. Re-exported for internal utils modules. */
+export type { ApplePayAuthorizedPayment, ApplePayConfig, ApplePayContact, ApplePayDeferredConfig, ApplePayMerchantSession, ApplePayPaymentMethodCreatePayload, ApplePayPaymentToken, ApplePayRecurringConfig, ApplePaySessionFailureDiagnostics, ApplePaySessionTokenRequest, ApplePaySurchargeConfig, ApplePayCardType, } from '../../types/applePay';

package/dist/utils/applePayConfig.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Apple Pay configuration helpers. Types live in `@/types/applePay`; this module re-exports
+ * the public API so existing `@/utils/applePayConfig` imports stay stable.
+ */
+export { DEFAULT_APPLE_PAY_MERCHANT_CAPABILITIES, DEFAULT_APPLE_PAY_SUPPORTED_NETWORKS, } from './applePay/constants';
+export type { ApplePayAuthorizedPayment, ApplePayCardType, ApplePayConfig, ApplePayContact, ApplePayDeferredConfig, ApplePayMerchantSession, ApplePayPaymentMethodCreatePayload, ApplePayPaymentToken, ApplePayRecurringConfig, ApplePaySessionFailureDiagnostics, ApplePaySessionTokenRequest, ApplePaySurchargeConfig, } from '../types/applePay';
+export { buildApplePayDeferredPaymentRequest, isApplePayDeferredRequested, validateApplePayDeferredConfig, } from './applePay/deferredFlow';
+export { buildApplePayAuthorizationFailureMessage, diagnoseApplePaySessionFailure, summarizeApplePayCancelEvent, summarizeApplePayMerchantSessionForLog, } from './applePay/diagnostics';
+export { isIOSApplePayDevice, isSafariBrowser, shouldAutoStartApplePayQr, } from './applePay/device';
+export { buildApplePayPaymentMethodCreatePayload, extractApplePayBillingContact, extractApplePayTokenForCreate, summarizeApplePayAuthorizedPayment, } from './applePay/paymentPayload';
+export { getApplePayDomain, getApplePayMerchantCapabilities, getApplePayPartnerInternalMerchantIdentifier, getApplePaySupportedNetworks, isApplePayPropEnabled, toApplePayConfig, } from './applePay/propAccess';
+export { buildApplePayRecurringPaymentRequest, isApplePayRecurringRequested, isApplePayStoredCredentialRequested, validateApplePayRecurringConfig, } from './applePay/recurringFlow';
+export { buildApplePaySessionTokenRequest, extractApplePayMerchantSession, } from './applePay/sessionToken';
+export { buildApplePayPaymentMethodUpdate, fromApplePayCents, isApplePaySurchargeConfigured, resolveApplePaySurchargeCents, toApplePayCents, } from './applePay/surcharge';

package/dist/utils/applePaySdkConfig.d.ts

@@ -0,0 +1,14 @@
+/** Apple's CDN when `VITE_APPLE_PAY_SDK_URL` and host `applePaySDKURL` are unset. */
+export declare const DEFAULT_APPLE_PAY_SDK_URL: string;
+/** Apple Pay JS SDK script URL from host config or `VITE_APPLE_PAY_SDK_URL`. */
+export declare function getApplePaySdkUrlFromEnv(): string;
+/** Resolved Apple Pay SDK script URL; falls back to {@link DEFAULT_APPLE_PAY_SDK_URL}. */
+export declare function getApplePaySdkUrl(): string;
+/** Lowest Apple Pay JS API version this component will use. Override with `VITE_APPLE_PAY_MIN_API_VERSION`. */
+export declare function getApplePayMinApiVersion(): number;
+/** First version allowing a zero total. Override with `VITE_APPLE_PAY_ZERO_TOTAL_API_VERSION`. */
+export declare function getApplePayZeroTotalApiVersion(): number;
+/** Preferred session version for charge-now flows. Override with `VITE_APPLE_PAY_PREFERRED_API_VERSION`. */
+export declare function getApplePayPreferredApiVersion(): number;
+/** Version for deferred/recurring flows. Override with `VITE_APPLE_PAY_DEFERRED_API_VERSION`. */
+export declare function getApplePayDeferredApiVersion(): number;

package/dist/utils/runtimeConfig.d.ts

@@ -2,5 +2,6 @@ export declare function resolvePaypalClientId(): string;
 export declare function resolveGoogleMapsApiKey(): string;
 export declare function resolvePaypalSdkUrl(): string;
 export declare function resolvePazeSdkUrl(): string;
+export declare function resolveApplePaySdkUrl(): string;
 export declare function resolvePaypalEnvironment(): string;
 export declare function resolvePlaidEnv(): string;