vue3-stripe-kit
Version:
Complete Vue 3 Stripe integration with Payment Elements, Checkout, Subscriptions. TypeScript support, composables, components, modular architecture for payments, billing, and e-commerce
645 lines (595 loc) • 23.1 kB
TypeScript
import { Ref } from 'vue';
import { Stripe } from '@stripe/stripe-js';
import { StripeElements } from '@stripe/stripe-js';
export declare function buildLineItems(items: Array<{
name: string;
description?: string;
amount: number;
currency: string;
quantity?: number;
images?: string[];
}>): CheckoutSessionConfig['lineItems'];
export declare interface CheckoutOptions {
apiEndpoint?: string;
timeout?: number;
headers?: Record<string, string>;
retries?: number;
}
export declare interface CheckoutSessionConfig {
mode: 'payment' | 'subscription' | 'setup';
lineItems: Array<{
price?: string;
priceData?: {
currency: string;
productData: {
name: string;
description?: string;
images?: string[];
};
unitAmount?: number;
recurring?: {
interval: 'day' | 'week' | 'month' | 'year';
intervalCount?: number;
};
};
quantity?: number;
}>;
successUrl: string;
cancelUrl: string;
customerEmail?: string;
clientReferenceId?: string;
metadata?: Record<string, string>;
allowPromotionCodes?: boolean;
billingAddressCollection?: 'auto' | 'required';
shippingAddressCollection?: {
allowedCountries: string[];
};
}
export declare interface CreateSubscriptionData {
customer?: string;
items: SubscriptionItem[];
payment_behavior?: 'default_incomplete' | 'error_if_incomplete' | 'allow_incomplete';
payment_settings?: {
payment_method_types?: string[];
save_default_payment_method?: 'on_subscription' | 'off';
};
expand?: string[];
metadata?: Record<string, string>;
description?: string;
trial_period_days?: number;
trial_end?: number;
trial_settings?: TrialSettings;
billing_cycle_anchor?: number;
collection_method?: 'charge_automatically' | 'send_invoice';
days_until_due?: number;
default_payment_method?: string;
proration_behavior?: 'create_prorations' | 'none' | 'always_invoice';
billing_thresholds?: {
amount_gte?: number;
reset_billing_cycle_anchor?: boolean;
};
cancel_at?: number;
cancel_at_period_end?: boolean;
default_source?: string;
default_tax_rates?: string[];
off_session?: boolean;
promotion_code?: string;
transfer_data?: {
destination: string;
amount_percent?: number;
};
}
export declare interface ElementsAppearance {
theme?: 'stripe' | 'night' | 'flat' | 'none';
variables?: ElementsTheme;
rules?: Record<string, any>;
}
export declare interface ElementsOptions {
fonts?: Array<{
family?: string;
src?: string;
style?: string;
weight?: string;
}>;
locale?: string;
appearance?: ElementsAppearance;
clientSecret?: string;
mode?: 'payment' | 'setup' | 'subscription';
currency?: string;
amount?: number;
setupFutureUsage?: 'on_session' | 'off_session';
paymentMethodCreation?: 'manual' | 'automatic';
paymentMethodOptions?: Record<string, any>;
paymentMethodTypes?: string[];
wallets?: {
applePay?: 'auto' | 'always' | 'never';
googlePay?: 'auto' | 'always' | 'never';
link?: 'auto' | 'always' | 'never';
};
}
export declare interface ElementsTheme {
colorPrimary?: string;
colorBackground?: string;
colorText?: string;
colorDanger?: string;
fontFamily?: string;
fontSizeBase?: string;
borderRadius?: string;
fontSmoothing?: 'auto' | 'never' | 'always';
}
export declare interface ExpressCheckoutElementOptions {
paymentMethods?: {
applePay?: 'auto' | 'always' | 'never';
googlePay?: 'auto' | 'always' | 'never';
link?: 'auto' | 'always' | 'never';
paypal?: 'auto' | 'always' | 'never';
};
layout?: {
maxColumns?: number;
maxRows?: number;
overflow?: 'auto' | 'hidden';
};
buttonTheme?: {
applePay?: 'black' | 'white' | 'white-outline';
googlePay?: 'black' | 'white' | 'white-outline';
};
buttonType?: {
applePay?: 'plain' | 'buy' | 'set-up' | 'donate' | 'check-out' | 'book' | 'subscribe';
googlePay?: 'book' | 'buy' | 'checkout' | 'donate' | 'order' | 'pay' | 'plain' | 'subscribe';
};
buttonHeight?: string;
}
export declare function getGlobalConfig(): StripeConfig | null;
export declare function getStripeInstance(): Stripe | null;
export declare function initializeStripe(config: StripeConfig): Promise<Stripe | null>;
export declare interface PaymentElementOptions {
layout?: 'tabs' | 'accordion' | 'auto';
defaultValues?: {
billingDetails?: {
name?: string;
email?: string;
phone?: string;
address?: {
line1?: string;
line2?: string;
city?: string;
state?: string;
postal_code?: string;
country?: string;
};
};
};
business?: {
name?: string;
};
paymentMethodOrder?: string[];
fields?: {
billingDetails?: 'auto' | 'never' | {
name?: 'auto' | 'never';
email?: 'auto' | 'never';
phone?: 'auto' | 'never';
address?: 'auto' | 'never' | {
line1?: 'auto' | 'never';
line2?: 'auto' | 'never';
city?: 'auto' | 'never';
state?: 'auto' | 'never';
postal_code?: 'auto' | 'never';
country?: 'auto' | 'never';
};
};
};
terms?: {
card?: 'auto' | 'always' | 'never';
ideal?: 'auto' | 'always' | 'never';
sepaDebit?: 'auto' | 'always' | 'never';
sofort?: 'auto' | 'always' | 'never';
bancontact?: 'auto' | 'always' | 'never';
};
wallets?: {
applePay?: 'auto' | 'always' | 'never';
googlePay?: 'auto' | 'always' | 'never';
};
}
export declare interface PaymentIntentConfig {
amount: number;
currency: string;
paymentMethodTypes?: string[];
captureMethod?: 'automatic' | 'manual';
confirmationMethod?: 'automatic' | 'manual';
description?: string;
receiptEmail?: string;
shipping?: {
name: string;
address: {
line1: string;
line2?: string;
city: string;
state?: string;
postal_code: string;
country: string;
};
};
metadata?: Record<string, string>;
statementDescriptor?: string;
statementDescriptorSuffix?: string;
setupFutureUsage?: 'on_session' | 'off_session';
transferGroup?: string;
applicationFeeAmount?: number;
onBehalfOf?: string;
}
export declare interface PaymentIntentResponse {
id: string;
clientSecret: string;
status: string;
amount: number;
currency: string;
}
export declare interface PriceData {
currency: string;
product: string | ProductData;
unit_amount?: number;
recurring: {
interval: 'day' | 'week' | 'month' | 'year';
interval_count?: number;
usage_type?: 'licensed' | 'metered';
};
billing_scheme?: 'per_unit' | 'tiered';
tiers?: Array<{
up_to: number | 'inf';
flat_amount?: number;
unit_amount?: number;
}>;
transform_usage?: {
divide_by: number;
round: 'up' | 'down';
};
}
export declare interface ProductData {
name: string;
description?: string;
images?: string[];
metadata?: Record<string, string>;
statement_descriptor?: string;
}
export declare function quickCheckout(options: QuickCheckoutOptions): Promise<void>;
declare interface QuickCheckoutOptions {
publishableKey?: string;
sessionId?: string;
config?: CheckoutSessionConfig;
apiEndpoint?: string;
timeout?: number;
headers?: Record<string, string>;
retries?: number;
}
export declare interface RequestConfig {
apiEndpoint?: string;
timeout?: number;
headers?: Record<string, string>;
retries?: number;
}
export declare function resetStripeInstance(): void;
export declare function setGlobalConfig(config: StripeConfig): void;
export declare interface StripeCheckoutResponse {
id: string;
url: string | null;
}
export declare interface StripeConfig {
publishableKey: string;
apiVersion?: string;
locale?: string;
stripeAccount?: string;
apiBaseUrl?: string;
checkoutEndpoint?: string;
requestTimeout?: number;
headers?: Record<string, string>;
}
export declare interface StripeError {
type: string;
code?: string;
message: string;
param?: string;
}
export declare interface SubscriptionConfig extends RequestConfig {
createEndpoint?: string;
updateEndpoint?: string;
cancelEndpoint?: string;
retrieveEndpoint?: string;
listEndpoint?: string;
pauseEndpoint?: string;
resumeEndpoint?: string;
createCustomerEndpoint?: string;
updateCustomerEndpoint?: string;
retrieveCustomerEndpoint?: string;
createPriceEndpoint?: string;
createProductEndpoint?: string;
listPricesEndpoint?: string;
listProductsEndpoint?: string;
retrievePriceEndpoint?: string;
retrieveProductEndpoint?: string;
retrieveUpcomingInvoiceEndpoint?: string;
retrieveInvoiceEndpoint?: string;
payInvoiceEndpoint?: string;
listInvoicesEndpoint?: string;
attachPaymentMethodEndpoint?: string;
detachPaymentMethodEndpoint?: string;
listPaymentMethodsEndpoint?: string;
retrievePaymentMethodEndpoint?: string;
defaultPaymentBehavior?: 'default_incomplete' | 'error_if_incomplete' | 'allow_incomplete';
defaultCollectionMethod?: 'charge_automatically' | 'send_invoice';
defaultProrationBehavior?: 'create_prorations' | 'none' | 'always_invoice';
defaultTrialDays?: number;
allowTrialExtension?: boolean;
cancelAtPeriodEnd?: boolean;
cancellationReason?: string;
webhookEndpointSecret?: string;
}
export declare interface SubscriptionItem {
id?: string;
price: string | PriceData;
quantity?: number;
metadata?: Record<string, string>;
}
export declare interface SubscriptionStatus {
id: string;
status: 'incomplete' | 'incomplete_expired' | 'trialing' | 'active' | 'past_due' | 'canceled' | 'unpaid';
customer: string;
current_period_start: number;
current_period_end: number;
trial_start?: number;
trial_end?: number;
canceled_at?: number;
cancel_at?: number;
cancel_at_period_end: boolean;
items: {
data: Array<{
id: string;
price: {
id: string;
nickname?: string;
unit_amount: number;
currency: string;
recurring: {
interval: string;
interval_count: number;
};
};
quantity: number;
}>;
};
latest_invoice?: string;
pending_setup_intent?: string;
default_payment_method?: string;
metadata: Record<string, string>;
}
export declare interface TrialSettings {
trial_period_days?: number;
trial_end?: number;
trial_from_plan?: boolean;
}
export declare interface UpdateSubscriptionData {
cancel_at_period_end?: boolean;
default_payment_method?: string;
description?: string;
items?: Array<{
id?: string;
price?: string;
quantity?: number;
deleted?: boolean;
metadata?: Record<string, string>;
}>;
metadata?: Record<string, string>;
payment_behavior?: 'default_incomplete' | 'error_if_incomplete' | 'allow_incomplete';
proration_behavior?: 'create_prorations' | 'none' | 'always_invoice';
proration_date?: number;
billing_cycle_anchor?: 'now' | 'unchanged';
trial_end?: number | 'now';
billing_thresholds?: {
amount_gte?: number;
reset_billing_cycle_anchor?: boolean;
};
cancel_at?: number;
default_source?: string;
default_tax_rates?: string[];
off_session?: boolean;
payment_settings?: {
payment_method_types?: string[];
save_default_payment_method?: 'on_subscription' | 'off';
};
pending_invoice_item_interval?: {
interval: 'day' | 'week' | 'month' | 'year';
interval_count?: number;
};
promotion_code?: string;
transfer_data?: {
destination: string;
amount_percent?: number;
};
}
export declare function usePaymentElements(globalElementsOptions?: ElementsOptions): UsePaymentElementsReturn;
export declare interface UsePaymentElementsReturn {
elements: Ref<StripeElements | null>;
paymentElement: Ref<any | null>;
expressCheckoutElement: Ref<any | null>;
loading: Ref<boolean>;
error: Ref<StripeError | null>;
setupElements: (options?: ElementsOptions) => Promise<void>;
mountPaymentElement: (elementId: string, options?: PaymentElementOptions) => Promise<void>;
mountExpressCheckout: (elementId: string, options?: ExpressCheckoutElementOptions) => Promise<void>;
submitPayment: (options?: {
confirmParams?: any;
}) => Promise<any>;
confirmPayment: (clientSecret: string, options?: any) => Promise<any>;
confirmSetup: (clientSecret: string, options?: any) => Promise<any>;
}
export declare function usePaymentIntents(componentOptions?: {
apiEndpoint?: string;
timeout?: number;
headers?: Record<string, string>;
retries?: number;
}): UsePaymentIntentsReturn;
export declare interface UsePaymentIntentsReturn {
createPaymentIntent: (config: PaymentIntentConfig, options?: CheckoutOptions) => Promise<PaymentIntentResponse>;
confirmPaymentIntent: (clientSecret: string, paymentMethod?: any) => Promise<any>;
retrievePaymentIntent: (clientSecret: string) => Promise<any>;
loading: Ref<boolean>;
error: Ref<StripeError | null>;
}
export declare function useStripe(config?: StripeConfig): UseStripeReturn;
export declare function useStripeCheckout(componentOptions?: UseStripeCheckoutOptions): UseStripeCheckoutReturn;
export declare interface UseStripeCheckoutOptions {
apiEndpoint?: string;
timeout?: number;
headers?: Record<string, string>;
retries?: number;
}
export declare interface UseStripeCheckoutReturn {
createCheckoutSession: (config: CheckoutSessionConfig, options?: CheckoutOptions) => Promise<StripeCheckoutResponse>;
redirectToCheckout: (sessionId: string) => Promise<void>;
loading: Ref<boolean>;
error: Ref<StripeError | null>;
}
export declare interface UseStripeReturn {
stripe: Ref<Stripe | null>;
elements: Ref<StripeElements | null>;
loading: Ref<boolean>;
error: Ref<StripeError | null>;
createElements: (options?: ElementsOptions) => StripeElements | null;
}
export declare function useSubscriptions(config?: Partial<SubscriptionConfig>): UseSubscriptionsReturn;
export declare interface UseSubscriptionsReturn {
loading: Ref<boolean>;
error: Ref<StripeError | null>;
createSubscription: (data: CreateSubscriptionData, config?: Partial<SubscriptionConfig>) => Promise<SubscriptionStatus>;
updateSubscription: (subscriptionId: string, data: UpdateSubscriptionData, config?: Partial<SubscriptionConfig>) => Promise<SubscriptionStatus>;
cancelSubscription: (subscriptionId: string, config?: {
cancelAtPeriodEnd?: boolean;
cancellationReason?: string;
} & Partial<SubscriptionConfig>) => Promise<SubscriptionStatus>;
retrieveSubscription: (subscriptionId: string, config?: Partial<SubscriptionConfig>) => Promise<SubscriptionStatus>;
listSubscriptions: (params?: {
customer?: string;
price?: string;
status?: string;
limit?: number;
}, config?: Partial<SubscriptionConfig>) => Promise<{
data: SubscriptionStatus[];
has_more: boolean;
}>;
startTrial: (subscriptionId: string, trialEnd: number | Date, config?: Partial<SubscriptionConfig>) => Promise<SubscriptionStatus>;
endTrial: (subscriptionId: string, config?: Partial<SubscriptionConfig>) => Promise<SubscriptionStatus>;
extendTrial: (subscriptionId: string, additionalDays: number, config?: Partial<SubscriptionConfig>) => Promise<SubscriptionStatus>;
changePlan: (subscriptionId: string, newPriceId: string, config?: {
prorationBehavior?: 'create_prorations' | 'none' | 'always_invoice';
} & Partial<SubscriptionConfig>) => Promise<SubscriptionStatus>;
addItem: (subscriptionId: string, priceId: string, quantity?: number, config?: Partial<SubscriptionConfig>) => Promise<SubscriptionStatus>;
removeItem: (subscriptionId: string, itemId: string, config?: Partial<SubscriptionConfig>) => Promise<SubscriptionStatus>;
updateQuantity: (subscriptionId: string, itemId: string, quantity: number, config?: Partial<SubscriptionConfig>) => Promise<SubscriptionStatus>;
resumeSubscription: (subscriptionId: string, config?: Partial<SubscriptionConfig>) => Promise<SubscriptionStatus>;
pauseSubscription: (subscriptionId: string, pauseBehavior?: {
behavior: 'mark_uncollectible' | 'keep_as_draft' | 'void';
}, config?: Partial<SubscriptionConfig>) => Promise<SubscriptionStatus>;
getUpcomingInvoice: (customerId: string, subscriptionId?: string, config?: Partial<SubscriptionConfig>) => Promise<any>;
payInvoice: (invoiceId: string, config?: Partial<SubscriptionConfig>) => Promise<any>;
createCustomer: (data: {
email?: string;
name?: string;
payment_method?: string;
metadata?: Record<string, string>;
}, config?: Partial<SubscriptionConfig>) => Promise<any>;
updateCustomer: (customerId: string, data: {
email?: string;
name?: string;
metadata?: Record<string, string>;
}, config?: Partial<SubscriptionConfig>) => Promise<any>;
isTrialing: (subscription: SubscriptionStatus) => boolean;
isActive: (subscription: SubscriptionStatus) => boolean;
isCanceled: (subscription: SubscriptionStatus) => boolean;
isPastDue: (subscription: SubscriptionStatus) => boolean;
daysUntilRenewal: (subscription: SubscriptionStatus) => number;
daysRemainingInTrial: (subscription: SubscriptionStatus) => number;
}
export declare function useWebhooks(config?: Partial<WebhookConfig>): UseWebhooksReturn;
export declare interface UseWebhooksReturn {
loading: Ref<boolean>;
error: Ref<StripeError | null>;
events: Ref<WebhookEvent[]>;
stats: Ref<WebhookStats>;
isMonitoring: Ref<boolean>;
createWebhookEndpoint: (url: string, enabledEvents: WebhookEventType[], config?: Partial<WebhookConfig>) => Promise<WebhookEndpoint>;
updateWebhookEndpoint: (endpointId: string, updates: Partial<WebhookEndpoint>, config?: Partial<WebhookConfig>) => Promise<WebhookEndpoint>;
deleteWebhookEndpoint: (endpointId: string, config?: Partial<WebhookConfig>) => Promise<void>;
listWebhookEndpoints: (config?: Partial<WebhookConfig>) => Promise<WebhookEndpoint[]>;
startMonitoring: (config?: Partial<WebhookConfig>) => void;
stopMonitoring: () => void;
fetchEvents: (limit?: number, config?: Partial<WebhookConfig>) => Promise<WebhookEvent[]>;
fetchEvent: (eventId: string, config?: Partial<WebhookConfig>) => Promise<WebhookEvent>;
resendEvent: (eventId: string, endpointId: string, config?: Partial<WebhookConfig>) => Promise<void>;
registerEventHandler: (handler: WebhookEventHandler) => void;
unregisterEventHandler: (eventType: WebhookEventType) => void;
clearEventHandlers: () => void;
simulateEvent: (eventType: WebhookEventType, testData?: any) => Promise<WebhookEvent>;
testWebhookEndpoint: (endpointId: string, eventType: WebhookEventType) => Promise<boolean>;
validateWebhookSignature: (payload: string, signature: string, secret: string) => boolean;
clearEvents: () => void;
exportEvents: (format: 'json' | 'csv') => string;
filterEvents: (filter: {
type?: WebhookEventType;
dateFrom?: Date;
dateTo?: Date;
}) => WebhookEvent[];
}
export declare interface WebhookConfig extends RequestConfig {
createWebhookEndpoint?: string;
updateWebhookEndpoint?: string;
deleteWebhookEndpoint?: string;
listWebhookEndpoint?: string;
retrieveWebhookEndpoint?: string;
listEventsEndpoint?: string;
retrieveEventEndpoint?: string;
resendEventEndpoint?: string;
webhookSecret?: string;
enabledEvents?: WebhookEventType[];
webhookUrl?: string;
enableRealTimeMonitoring?: boolean;
pollingInterval?: number;
maxEvents?: number;
}
export declare interface WebhookEndpoint {
id: string;
url: string;
enabled_events: WebhookEventType[];
status: 'enabled' | 'disabled';
description?: string;
metadata?: Record<string, string>;
created: number;
}
export declare interface WebhookEvent {
id: string;
object: 'event';
type: WebhookEventType;
created: number;
data: {
object: any;
previous_attributes?: Record<string, any>;
};
livemode: boolean;
pending_webhooks: number;
request?: {
id: string;
idempotency_key?: string;
};
}
export declare interface WebhookEventHandler {
eventType: WebhookEventType;
handler: (event: WebhookEvent) => void | Promise<void>;
description?: string;
}
export declare type WebhookEventType = 'customer.created' | 'customer.updated' | 'customer.deleted' | 'customer.subscription.created' | 'customer.subscription.updated' | 'customer.subscription.deleted' | 'customer.subscription.trial_will_end' | 'customer.subscription.paused' | 'customer.subscription.resumed' | 'invoice.created' | 'invoice.finalized' | 'invoice.payment_succeeded' | 'invoice.payment_failed' | 'invoice.payment_action_required' | 'payment_intent.created' | 'payment_intent.succeeded' | 'payment_intent.payment_failed' | 'payment_method.attached' | 'payment_method.detached' | 'checkout.session.completed' | 'checkout.session.expired' | 'setup_intent.created' | 'setup_intent.succeeded';
export declare interface WebhookStats {
totalEvents: number;
successfulEvents: number;
failedEvents: number;
lastEventTime?: number;
eventsByType: Record<WebhookEventType, number>;
}
export { }