@paypercut/checkout-js 1.0.21 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -22,7 +22,7 @@
22
22
  * });
23
23
  * ```
24
24
  */
25
- declare const LOCALES: readonly ["bg", "bg-BG", "en", "en-GB", "el", "el-GR", "ro", "ro-RO", "hr", "hr-HR", "pl", "pl-PL", "cs", "cs-CZ", "sl", "sl-SI", "sk", "sk-SK"];
25
+ declare const LOCALES: readonly ["bg", "bg-BG", "en", "en-GB", "el", "el-GR", "ro", "ro-RO", "hr", "hr-HR", "pl", "pl-PL", "cs", "cs-CZ", "sl", "sl-SI", "sk", "sk-SK", "hu", "hu-HU"];
26
26
  /**
27
27
  * Locale type - union of all supported locale codes plus 'auto'
28
28
  * @example
@@ -190,11 +190,269 @@ interface PaypercutCheckoutStatic {
190
190
  version: string;
191
191
  }
192
192
 
193
+ /**
194
+ * ISO 639-1 two-letter language codes supported by the Express Checkout wallet buttons.
195
+ *
196
+ * Pass one of these to `locale` in the options or to `setLocale()` after mount.
197
+ * Each wallet applies the locale independently:
198
+ * - Apple Pay supports all values in this list.
199
+ * - Google Pay supports most; unsupported languages (e.g. 'ro', 'hu') fall back to 'en'.
200
+ */
201
+ declare const EXPRESS_LOCALES: readonly ["bg", "cs", "el", "en", "hr", "hu", "pl", "ro", "sk", "sl"];
202
+ type ExpressLocale = typeof EXPRESS_LOCALES[number];
203
+ /** Line item shown in the Apple Pay payment sheet breakdown. Not used by Google Pay. */
204
+ interface LineItem {
205
+ label: string;
206
+ /** Amount in minor units (e.g. 1200 = 12.00) */
207
+ amount: number;
208
+ type?: 'final' | 'pending';
209
+ }
210
+ interface ExpressCheckoutShippingOption {
211
+ id: string;
212
+ label: string;
213
+ detail?: string;
214
+ /** Amount in minor units */
215
+ amount: number;
216
+ }
217
+ type ExpressButtonType = 'buy' | 'pay' | 'plain' | 'donate' | 'checkout' | 'subscribe' | 'book' | 'order' | 'tip' | 'contribute';
218
+ type ApplePayButtonStyle = 'black' | 'white' | 'white-outline';
219
+ type GooglePayButtonColor = 'default' | 'black' | 'white';
220
+ interface ExpressButtonOptions {
221
+ /**
222
+ * Button label type shown on both Apple Pay and Google Pay buttons.
223
+ * @default 'plain'
224
+ */
225
+ type?: ExpressButtonType;
226
+ /**
227
+ * Apple Pay button color style.
228
+ * @default 'black'
229
+ */
230
+ applePayStyle?: ApplePayButtonStyle;
231
+ /**
232
+ * Google Pay button color.
233
+ * @default 'default'
234
+ */
235
+ googlePayColor?: GooglePayButtonColor;
236
+ /**
237
+ * Border radius applied to both Apple Pay and Google Pay buttons.
238
+ * Accepts any valid CSS border-radius value (e.g. '0.5rem', '8px', '50%').
239
+ * @default '0.5rem'
240
+ */
241
+ borderRadius?: string;
242
+ }
243
+ interface ExpressCheckoutOptions {
244
+ /** Publishable API key */
245
+ publishableKey: string;
246
+ /** Amount in minor units (e.g. 1200 = €12.00) */
247
+ amount: number;
248
+ /** ISO 4217 currency code (e.g. 'EUR', 'BGN') */
249
+ currency: string;
250
+ /** @default 'payment' */
251
+ mode?: 'payment';
252
+ /**
253
+ * Line items shown in the payment sheet breakdown (subtotal, tax, etc.).
254
+ * Currently displayed by Apple Pay only — Google Pay shows the total only and ignores this field.
255
+ */
256
+ lineItems?: LineItem[];
257
+ /** Initial shipping options. Can be updated via updateWith() */
258
+ shippingOptions?: ExpressCheckoutShippingOption[];
259
+ /** Request shipping address from the wallet sheet */
260
+ requestShipping?: boolean;
261
+ /** Request email from the wallet sheet */
262
+ requestEmail?: boolean;
263
+ /** Request cardholder name from the wallet sheet */
264
+ requestName?: boolean;
265
+ /** ISO 3166-1 alpha-2 country code (e.g. 'DE'). Used in wallet payment requests. */
266
+ countryCode?: string;
267
+ /**
268
+ * ISO 3166-1 alpha-2 country codes the merchant ships to (e.g. ['DE', 'AT', 'CH']).
269
+ * Google Pay only — restricts the address picker so users cannot select unsupported countries.
270
+ * Apple Pay does not support pre-filtering; use `status: 'invalid_shipping_address'`
271
+ * in your `shipping_address_change` handler to reject unsupported addresses at runtime.
272
+ */
273
+ allowedCountries?: string[];
274
+ /** Wallets to enable. Defaults to both Apple Pay and Google Pay */
275
+ walletOptions?: (WalletOption | `${WalletOption}`)[];
276
+ /**
277
+ * Layout of the wallet buttons.
278
+ * - 'row' (default) — buttons side by side, each equal width
279
+ * - 'column' — buttons stacked vertically, each full width
280
+ * - 'auto' — SDK observes container width: column at ≤540px, row above
281
+ */
282
+ layout?: 'column' | 'row' | 'auto';
283
+ /**
284
+ * ISO 639-1 two-letter language code for the wallet button labels (e.g. `'en'`, `'bg'`, `'pl'`).
285
+ * Can be changed after mount via `setLocale()`. Unsupported values fall back to `'en'`.
286
+ * See `ExpressLocale` for the full list of supported codes.
287
+ */
288
+ locale?: ExpressLocale | string;
289
+ /**
290
+ * Customize the wallet button appearance.
291
+ */
292
+ buttonOptions?: ExpressButtonOptions;
293
+ /**
294
+ * Override hosted checkout URL (only available in internal builds).
295
+ * Ignored in production builds.
296
+ */
297
+ hostedCheckoutUrl?: string;
298
+ /**
299
+ * Override Paypercut API URL (only available in internal builds).
300
+ * Ignored in production builds.
301
+ */
302
+ apiUrl?: string;
303
+ }
304
+ interface ExpressCheckoutUpdateOptions {
305
+ /** Updated total amount in minor units */
306
+ amount?: number;
307
+ /** Updated line items (breakdown rows). Currently used by Apple Pay only — ignored by Google Pay. */
308
+ lineItems?: LineItem[];
309
+ /** Updated shipping options */
310
+ shippingOptions?: ExpressCheckoutShippingOption[];
311
+ /**
312
+ * Result status to report back to the wallet.
313
+ * Use 'invalid_shipping_address' / 'invalid_shipping_option' to show an error
314
+ * in the wallet sheet without closing it.
315
+ * @default 'success'
316
+ */
317
+ status?: 'success' | 'fail' | 'invalid_shipping_address' | 'invalid_shipping_option';
318
+ }
319
+ interface ExpressShippingAddress {
320
+ country: string;
321
+ state?: string;
322
+ city?: string;
323
+ postalCode?: string;
324
+ }
325
+ interface ShippingAddressChangeEvent {
326
+ address: ExpressShippingAddress;
327
+ /**
328
+ * Call this with updated totals and shipping options.
329
+ * Must be called to unblock the wallet sheet.
330
+ */
331
+ updateWith: (options: ExpressCheckoutUpdateOptions) => void;
332
+ }
333
+ interface ShippingOptionChangeEvent {
334
+ shippingOption: ExpressCheckoutShippingOption;
335
+ /**
336
+ * Call this with updated totals.
337
+ * Must be called to unblock the wallet sheet.
338
+ */
339
+ updateWith: (options: ExpressCheckoutUpdateOptions) => void;
340
+ }
341
+ interface ExpressTokenPayload {
342
+ id: string;
343
+ type: 'apple_pay' | 'google_pay';
344
+ }
345
+ interface ExpressBillingDetails {
346
+ name?: string;
347
+ email?: string;
348
+ phone?: string;
349
+ address?: {
350
+ line1?: string;
351
+ line2?: string;
352
+ city?: string;
353
+ state?: string;
354
+ postalCode?: string;
355
+ country?: string;
356
+ };
357
+ }
358
+ interface ExpressShippingDetails {
359
+ name?: string;
360
+ address?: {
361
+ line1?: string;
362
+ line2?: string;
363
+ city?: string;
364
+ state?: string;
365
+ postalCode?: string;
366
+ country?: string;
367
+ };
368
+ }
369
+ interface ExpressSessionStartEvent {
370
+ /** Which wallet opened */
371
+ wallet: 'apple_pay' | 'google_pay';
372
+ /**
373
+ * Call this with your initial shipping options and amount.
374
+ * Must be called to unblock the wallet sheet.
375
+ * Identical signature to the updateWith() in shipping change events.
376
+ */
377
+ updateWith: (options: ExpressCheckoutUpdateOptions) => void;
378
+ }
379
+ interface ExpressPaymentMethodCreatedEvent {
380
+ /** Paypercut payment method ID — use this server-side to confirm the payment */
381
+ paymentMethodId: string;
382
+ /** Which wallet was used */
383
+ wallet: 'apple_pay' | 'google_pay';
384
+ billingDetails?: ExpressBillingDetails;
385
+ shippingDetails?: ExpressShippingDetails;
386
+ selectedShippingOption?: ExpressCheckoutShippingOption;
387
+ }
388
+ interface ExpressPaymentMethodFailedEvent {
389
+ error: string;
390
+ }
391
+ type ExpressEventName = 'ready' | 'click' | 'session_start' | 'shipping_options_required' | 'shipping_address_change' | 'shipping_option_change' | 'payment_method_created' | 'payment_method_failed' | 'cancel' | 'error';
392
+ declare enum ExpressSdkEvent {
393
+ Ready = "ready",
394
+ Click = "click",
395
+ SessionStart = "session_start",
396
+ ShippingOptionsRequired = "shipping_options_required",
397
+ ShippingAddressChange = "shipping_address_change",
398
+ ShippingOptionChange = "shipping_option_change",
399
+ PaymentMethodCreated = "payment_method_created",
400
+ PaymentMethodFailed = "payment_method_failed",
401
+ Cancel = "cancel",
402
+ Error = "error"
403
+ }
404
+ interface ExpressCheckoutInstance {
405
+ /** Mount the wallet button iframe into a container */
406
+ mount(container: HTMLElement | string): void;
407
+ /** Subscribe to events. Returns unsubscribe function */
408
+ on(event: 'ready', handler: () => void): () => void;
409
+ on(event: 'click', handler: () => void): () => void;
410
+ on(event: 'session_start', handler: (e: ExpressSessionStartEvent) => void): () => void;
411
+ on(event: 'shipping_options_required', handler: (e: {
412
+ wallet: 'apple_pay' | 'google_pay';
413
+ }) => void): () => void;
414
+ on(event: 'shipping_address_change', handler: (e: ShippingAddressChangeEvent) => void): () => void;
415
+ on(event: 'shipping_option_change', handler: (e: ShippingOptionChangeEvent) => void): () => void;
416
+ on(event: 'payment_method_created', handler: (e: ExpressPaymentMethodCreatedEvent) => void): () => void;
417
+ on(event: 'payment_method_failed', handler: (e: ExpressPaymentMethodFailedEvent) => void): () => void;
418
+ on(event: 'cancel', handler: () => void): () => void;
419
+ on(event: 'error', handler: (err: Error) => void): () => void;
420
+ on(event: ExpressEventName, handler: (...args: any[]) => void): () => void;
421
+ /**
422
+ * Push updated totals / shipping options into the wallet sheet.
423
+ * Call this after calculating shipping in response to shipping_address_change
424
+ * or shipping_option_change (via the event's updateWith() helper).
425
+ */
426
+ update(options: ExpressCheckoutUpdateOptions): void;
427
+ /**
428
+ * Dynamically change the button layout after mount.
429
+ * 'row' places buttons side by side, 'column' stacks them vertically.
430
+ */
431
+ setLayout(layout: 'row' | 'column'): void;
432
+ /**
433
+ * Dynamically change the locale of the wallet buttons after mount.
434
+ */
435
+ setLocale(locale: string): void;
436
+ /**
437
+ * Dynamically update button appearance after mount.
438
+ * Merges with existing buttonOptions — only the fields you pass are changed.
439
+ */
440
+ setButtonOptions(opts: Partial<ExpressButtonOptions>): void;
441
+ /** Destroy instance and clean up all listeners */
442
+ destroy(): void;
443
+ }
444
+ interface ExpressCheckoutStatic {
445
+ (options: ExpressCheckoutOptions): ExpressCheckoutInstance;
446
+ new (options: ExpressCheckoutOptions): ExpressCheckoutInstance;
447
+ }
448
+
449
+ declare const PaypercutExpressCheckout: ExpressCheckoutStatic;
450
+
193
451
  /**
194
452
  * Factory function that works both as callable and constructable.
195
453
  * Always returns a new CheckoutImpl instance - no prototype manipulation needed.
196
454
  */
197
455
  declare const PaypercutCheckout: PaypercutCheckoutStatic;
198
456
 
199
- export { LOCALES, PaymentMethod, PaypercutCheckout, SdkEvent, UIMode, WalletOption, PaypercutCheckout as default };
200
- export type { CheckoutInstance, EventName, FormValidationError, Locale, PaypercutCheckoutOptions, PaypercutCheckoutStatic, WalletType };
457
+ export { ExpressSdkEvent, LOCALES, PaymentMethod, PaypercutCheckout, PaypercutExpressCheckout, SdkEvent, UIMode, WalletOption, PaypercutCheckout as default };
458
+ export type { ApplePayButtonStyle, CheckoutInstance, EventName, ExpressBillingDetails, ExpressButtonOptions, ExpressButtonType, ExpressCheckoutInstance, ExpressCheckoutOptions, ExpressCheckoutShippingOption, ExpressCheckoutUpdateOptions, ExpressEventName, ExpressPaymentMethodCreatedEvent, ExpressPaymentMethodFailedEvent, ExpressSessionStartEvent, ExpressShippingAddress, ExpressShippingDetails, ExpressTokenPayload, FormValidationError, GooglePayButtonColor, LineItem, Locale, PaypercutCheckoutOptions, PaypercutCheckoutStatic, ShippingAddressChangeEvent, ShippingOptionChangeEvent, WalletType };