@paypercut/checkout-js 1.2.18 → 1.2.19
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/README.md +669 -396
- package/dist/index.cjs +4733 -185
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.ts +300 -2
- package/dist/index.mjs +4733 -186
- package/dist/index.mjs.map +1 -1
- package/dist/paypercut-checkout.iife.min.js +1 -1
- package/dist/paypercut-checkout.iife.min.js.map +1 -1
- package/licenses/Geist-OFL-1.1.txt +92 -0
- package/package.json +14 -4
package/README.md
CHANGED
|
@@ -12,6 +12,9 @@ A lightweight, framework-agnostic JavaScript SDK for embedding Paypercut Checkou
|
|
|
12
12
|
## Table of Contents
|
|
13
13
|
|
|
14
14
|
- [Installation](#installation)
|
|
15
|
+
- [Elements](#elements)
|
|
16
|
+
- [Payment Element](#payment-element)
|
|
17
|
+
- [Express Checkout Element](#express-checkout-element)
|
|
15
18
|
- [Quick Start — Embedded Checkout](#quick-start)
|
|
16
19
|
- [API Reference — Embedded Checkout](#api-reference)
|
|
17
20
|
- [**Customisation**](#customisation)
|
|
@@ -67,16 +70,161 @@ pnpm add @paypercut/checkout-js
|
|
|
67
70
|
|
|
68
71
|
```html
|
|
69
72
|
<!-- jsDelivr (recommended with SRI) -->
|
|
70
|
-
<script
|
|
71
|
-
|
|
72
|
-
|
|
73
|
+
<script
|
|
74
|
+
src="https://cdn.jsdelivr.net/npm/@paypercut/checkout-js@1.2.19/dist/paypercut-checkout.iife.min.js"
|
|
75
|
+
integrity="sha384-..."
|
|
76
|
+
crossorigin="anonymous"
|
|
77
|
+
></script>
|
|
73
78
|
|
|
74
79
|
<!-- or UNPKG -->
|
|
75
|
-
<script src="https://unpkg.com/@paypercut/checkout-js@1.2.
|
|
80
|
+
<script src="https://unpkg.com/@paypercut/checkout-js@1.2.19/dist/paypercut-checkout.iife.min.js"></script>
|
|
76
81
|
```
|
|
77
82
|
|
|
78
83
|
---
|
|
79
84
|
|
|
85
|
+
## Elements
|
|
86
|
+
|
|
87
|
+
The Elements API is the composable integration surface for merchant-owned payment
|
|
88
|
+
pages. One `elements()` object owns one shared controller and configuration
|
|
89
|
+
session. Every Element created from it is an independently mounted, remotely
|
|
90
|
+
hosted component; merchant and platform code decide where those components are
|
|
91
|
+
placed.
|
|
92
|
+
|
|
93
|
+
```ts
|
|
94
|
+
import { Paypercut } from '@paypercut/checkout-js';
|
|
95
|
+
|
|
96
|
+
const paypercut = Paypercut({ publishableKey: 'pk_...' });
|
|
97
|
+
const elements = paypercut.elements({
|
|
98
|
+
mode: 'payment',
|
|
99
|
+
amount: 4999,
|
|
100
|
+
currency: 'USD',
|
|
101
|
+
});
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Creating the group does not create a Checkout Session or Payment Intent. The
|
|
105
|
+
merchant server remains authoritative for the final amount, currency, order, and
|
|
106
|
+
payment confirmation.
|
|
107
|
+
|
|
108
|
+
### Payment Element
|
|
109
|
+
|
|
110
|
+
```ts
|
|
111
|
+
const payment = elements.create('payment');
|
|
112
|
+
payment.mount('#payment-element');
|
|
113
|
+
|
|
114
|
+
const paymentMethod = await payment.submit();
|
|
115
|
+
// Send paymentMethod.id to your server. Do not confirm a payment from browser input.
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### Express Checkout Element
|
|
119
|
+
|
|
120
|
+
The Express Checkout Element is one component. It checks wallet availability and
|
|
121
|
+
renders the available Apple Pay and Google Pay buttons inside its hosted frame.
|
|
122
|
+
It is not one Paypercut iframe per wallet and it is not a WooCommerce-specific
|
|
123
|
+
widget.
|
|
124
|
+
|
|
125
|
+
```ts
|
|
126
|
+
const expressCheckout = elements.create('expressCheckout', {
|
|
127
|
+
paymentMethods: {
|
|
128
|
+
applePay: 'auto',
|
|
129
|
+
googlePay: 'auto',
|
|
130
|
+
},
|
|
131
|
+
layout: {
|
|
132
|
+
maxColumns: 2,
|
|
133
|
+
maxRows: 1,
|
|
134
|
+
},
|
|
135
|
+
buttonHeight: 48,
|
|
136
|
+
emailRequired: true,
|
|
137
|
+
billingAddressRequired: true,
|
|
138
|
+
});
|
|
139
|
+
|
|
140
|
+
expressCheckout.on('ready', ({ availablePaymentMethods }) => {
|
|
141
|
+
// Hide your placement if every value is false.
|
|
142
|
+
document
|
|
143
|
+
.querySelector('#express-checkout')
|
|
144
|
+
?.toggleAttribute(
|
|
145
|
+
'hidden',
|
|
146
|
+
!availablePaymentMethods.applePay && !availablePaymentMethods.googlePay,
|
|
147
|
+
);
|
|
148
|
+
});
|
|
149
|
+
|
|
150
|
+
expressCheckout.on('click', async (event) => {
|
|
151
|
+
// Recalculate the cart presented by your UI before the Element accepts and
|
|
152
|
+
// tokenizes the wallet result. Settle the event promptly (within one second).
|
|
153
|
+
// A provider's native sheet may begin opening on the original user gesture.
|
|
154
|
+
const cart = await readCurrentCart();
|
|
155
|
+
if (!cart.isValid) {
|
|
156
|
+
event.reject();
|
|
157
|
+
return;
|
|
158
|
+
}
|
|
159
|
+
elements.update({ amount: cart.amount });
|
|
160
|
+
event.resolve({
|
|
161
|
+
lineItems: cart.lineItems,
|
|
162
|
+
shippingAddressRequired: cart.needsShipping,
|
|
163
|
+
shippingRates: cart.needsShipping ? cart.shippingRates : undefined,
|
|
164
|
+
});
|
|
165
|
+
});
|
|
166
|
+
|
|
167
|
+
expressCheckout.on('shippingaddresschange', async (event) => {
|
|
168
|
+
try {
|
|
169
|
+
const update = await quoteShipping(event.address);
|
|
170
|
+
event.resolve(update); // { amount, lineItems, shippingRates }
|
|
171
|
+
} catch {
|
|
172
|
+
event.reject();
|
|
173
|
+
}
|
|
174
|
+
});
|
|
175
|
+
|
|
176
|
+
expressCheckout.on('shippingratechange', async (event) => {
|
|
177
|
+
try {
|
|
178
|
+
const update = await selectShippingRate(event.shippingRate.id);
|
|
179
|
+
event.resolve(update); // { amount, lineItems, shippingRates? }
|
|
180
|
+
} catch {
|
|
181
|
+
event.reject();
|
|
182
|
+
}
|
|
183
|
+
});
|
|
184
|
+
|
|
185
|
+
expressCheckout.on('confirm', async (event) => {
|
|
186
|
+
try {
|
|
187
|
+
// Send the opaque Payment Method ID and final provider-neutral contact data
|
|
188
|
+
// to your server. The server remains authoritative for the order and payment.
|
|
189
|
+
await submitPaymentMethodToYourServer({
|
|
190
|
+
wallet: event.wallet,
|
|
191
|
+
payment_method: event.paymentMethod.id,
|
|
192
|
+
billing_details: event.billingDetails,
|
|
193
|
+
shipping_address: event.shippingAddress,
|
|
194
|
+
shipping_rate: event.shippingRate,
|
|
195
|
+
});
|
|
196
|
+
event.complete();
|
|
197
|
+
} catch (error) {
|
|
198
|
+
event.paymentFailed({
|
|
199
|
+
code: 'merchant_checkout_failed',
|
|
200
|
+
message: error instanceof Error ? error.message : 'Payment failed.',
|
|
201
|
+
});
|
|
202
|
+
}
|
|
203
|
+
});
|
|
204
|
+
|
|
205
|
+
expressCheckout.on('error', ({ code, message, recoverable }) => {
|
|
206
|
+
reportPaymentError({ code, message, recoverable });
|
|
207
|
+
});
|
|
208
|
+
|
|
209
|
+
expressCheckout.mount('#express-checkout');
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
The component owns wallet SDK loading, capability detection, provider button
|
|
213
|
+
rendering, loading states, resizing, tokenization, and the shared provider-verified
|
|
214
|
+
3DS lifecycle. The merchant adapter owns product/cart placement, shipping quotes,
|
|
215
|
+
provider-neutral address conversion, and server-side order/payment confirmation.
|
|
216
|
+
The native wallet stays pending until the adapter calls `complete()` or
|
|
217
|
+
`paymentFailed()`.
|
|
218
|
+
|
|
219
|
+
Shipping is opt-in. Set `shippingAddressRequired` and provide `shippingRates` only
|
|
220
|
+
for physical fulfillment. When enabled, the Element emits address and rate change
|
|
221
|
+
events and requires each event to be resolved or rejected promptly. The final
|
|
222
|
+
`confirm` event returns the unredacted `shippingAddress` and selected
|
|
223
|
+
`shippingRate`. Integrations without shipping (for example, an EV charging
|
|
224
|
+
payment) should leave those options unset and receive no shipping callbacks.
|
|
225
|
+
|
|
226
|
+
---
|
|
227
|
+
|
|
80
228
|
## Quick Start
|
|
81
229
|
|
|
82
230
|
This returns a checkout session ID like `01KB23M9EC960C50G3AH14FTTT`.
|
|
@@ -90,8 +238,8 @@ import { PaypercutCheckout } from '@paypercut/checkout-js';
|
|
|
90
238
|
|
|
91
239
|
// Initialize the checkout
|
|
92
240
|
const checkout = PaypercutCheckout({
|
|
93
|
-
id: '01KB23M9EC960C50G3AH14FTTT',
|
|
94
|
-
containerId: '#checkout'
|
|
241
|
+
id: '01KB23M9EC960C50G3AH14FTTT', // Your checkout session ID from step 1
|
|
242
|
+
containerId: '#checkout', // CSS selector or HTMLElement
|
|
95
243
|
});
|
|
96
244
|
|
|
97
245
|
// Listen for payment events
|
|
@@ -118,9 +266,10 @@ That's it! The checkout is now embedded in your page.
|
|
|
118
266
|
|
|
119
267
|
The SDK supports one display mode:
|
|
120
268
|
|
|
121
|
-
| Mode
|
|
122
|
-
|
|
269
|
+
| Mode | When to Use | Configuration |
|
|
270
|
+
| ------------ | ------------------------------------ | --------------------- |
|
|
123
271
|
| **Embedded** | Checkout is part of your page layout | Provide `containerId` |
|
|
272
|
+
|
|
124
273
|
---
|
|
125
274
|
|
|
126
275
|
## API Reference
|
|
@@ -131,18 +280,18 @@ Creates a new checkout instance.
|
|
|
131
280
|
|
|
132
281
|
#### Options
|
|
133
282
|
|
|
134
|
-
| Option
|
|
135
|
-
|
|
136
|
-
| `id`
|
|
137
|
-
| `containerId`
|
|
138
|
-
| `locale`
|
|
139
|
-
| `lang`
|
|
140
|
-
| `ui_mode`
|
|
141
|
-
| `wallet_options`
|
|
142
|
-
| `form_only`
|
|
143
|
-
| `validate_form`
|
|
144
|
-
| `appearance`
|
|
145
|
-
| `appearance.preset` | `'modal' \| 'inline'`
|
|
283
|
+
| Option | Type | Required | Default | Description |
|
|
284
|
+
| ------------------- | ------------------------ | -------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
285
|
+
| `id` | `string` | Yes | — | Checkout session identifier (e.g., `01KB23M9EC960C50G3AH14FTTT`) |
|
|
286
|
+
| `containerId` | `string \| HTMLElement` | Yes | — | CSS selector or element where iframe mounts |
|
|
287
|
+
| `locale` | `string` | No | `'auto'` | Locale for checkout UI. Options: `'auto'`, `'en'`, `'en-GB'`, `'bg'`, `'bg-BG'` |
|
|
288
|
+
| `lang` | `string` | No | `'auto'` | Locale for checkout UI. Options: `'auto'`, `'en'`, `'en-GB'`, `'bg'`, `'bg-BG'` |
|
|
289
|
+
| `ui_mode` | `'hosted' \| 'embedded'` | No | `'embedded'` | UI mode for checkout display |
|
|
290
|
+
| `wallet_options` | `string[]` | No | `['apple_pay', 'google_pay']` | Digital wallet options. Pass `[]` to disable all wallets |
|
|
291
|
+
| `form_only` | `boolean` | No | `false` | Show only payment form (no Pay Now button - use external button with `submit()`) |
|
|
292
|
+
| `validate_form` | `boolean` | No | `false` | This indicates that Google Pay/Apple Pay flow to proceed you need to confirm form validation. For EMBEDDED checkouts only) |
|
|
293
|
+
| `appearance` | `object` | No | `undefined` | Appearance configuration for the checkout UI |
|
|
294
|
+
| `appearance.preset` | `'modal' \| 'inline'` | No | `undefined` | Controls checkout layout preset. `'modal'` shows the order summary (TotalCard) and header inside the iframe — use when rendering in a modal/dialog. `'inline'` hides the TotalCard — use when the merchant renders their own order summary outside the checkout. |
|
|
146
295
|
|
|
147
296
|
#### Examples
|
|
148
297
|
|
|
@@ -151,7 +300,7 @@ Creates a new checkout instance.
|
|
|
151
300
|
```typescript
|
|
152
301
|
const checkout = PaypercutCheckout({
|
|
153
302
|
id: '01KB23M9EC960C50G3AH14FTTT',
|
|
154
|
-
containerId: '#checkout-container'
|
|
303
|
+
containerId: '#checkout-container',
|
|
155
304
|
});
|
|
156
305
|
```
|
|
157
306
|
|
|
@@ -161,14 +310,14 @@ const checkout = PaypercutCheckout({
|
|
|
161
310
|
const checkout = PaypercutCheckout({
|
|
162
311
|
id: '01KB23M9EC960C50G3AH14FTTT',
|
|
163
312
|
containerId: '#checkout-container',
|
|
164
|
-
locale: 'en',
|
|
165
|
-
lang: 'en',
|
|
166
|
-
ui_mode: 'embedded',
|
|
313
|
+
locale: 'en', // 'auto' | 'en' | 'en-GB' | 'bg' | 'bg-BG'
|
|
314
|
+
lang: 'en', // 'auto' | 'en' | 'en-GB' | 'bg' | 'bg-BG'
|
|
315
|
+
ui_mode: 'embedded', // 'hosted' | 'embedded'
|
|
167
316
|
wallet_options: ['apple_pay', 'google_pay'], // Can be empty array [] or contain one/both options
|
|
168
|
-
form_only: false,
|
|
169
|
-
validate_form: true,
|
|
317
|
+
form_only: false, // Set true to hide Pay Now button (use external button),
|
|
318
|
+
validate_form: true, // Set true to require form validation before wallet payment
|
|
170
319
|
appearance: {
|
|
171
|
-
preset: 'modal',
|
|
320
|
+
preset: 'modal', // 'modal' | 'inline' — 'modal' shows TotalCard + header, 'inline' hides them
|
|
172
321
|
},
|
|
173
322
|
});
|
|
174
323
|
```
|
|
@@ -179,7 +328,7 @@ const checkout = PaypercutCheckout({
|
|
|
179
328
|
const checkout = PaypercutCheckout({
|
|
180
329
|
id: '01KB23M9EC960C50G3AH14FTTT',
|
|
181
330
|
containerId: '#checkout-container',
|
|
182
|
-
wallet_options: []
|
|
331
|
+
wallet_options: [], // No Apple Pay or Google Pay buttons
|
|
183
332
|
});
|
|
184
333
|
```
|
|
185
334
|
|
|
@@ -189,7 +338,7 @@ const checkout = PaypercutCheckout({
|
|
|
189
338
|
const checkout = PaypercutCheckout({
|
|
190
339
|
id: '01KB23M9EC960C50G3AH14FTTT',
|
|
191
340
|
containerId: '#checkout-container',
|
|
192
|
-
wallet_options: ['apple_pay']
|
|
341
|
+
wallet_options: ['apple_pay'], // Only Apple Pay, no Google Pay
|
|
193
342
|
});
|
|
194
343
|
```
|
|
195
344
|
|
|
@@ -199,7 +348,7 @@ const checkout = PaypercutCheckout({
|
|
|
199
348
|
const checkout = PaypercutCheckout({
|
|
200
349
|
id: '01KB23M9EC960C50G3AH14FTTT',
|
|
201
350
|
containerId: '#checkout-container',
|
|
202
|
-
form_only: true
|
|
351
|
+
form_only: true, // No Pay Now button inside checkout
|
|
203
352
|
});
|
|
204
353
|
|
|
205
354
|
// Use your own button to trigger payment
|
|
@@ -277,10 +426,10 @@ if (checkout.isMounted()) {
|
|
|
277
426
|
|
|
278
427
|
Paypercut Checkout supports full visual customisation — you can match your brand colors, typography, corner radius, and even inject your logo. Customisation works in two complementary ways:
|
|
279
428
|
|
|
280
|
-
| Approach
|
|
281
|
-
|
|
282
|
-
| `appearance` init option
|
|
283
|
-
| `checkout.updateAppearance()` | After mount (dynamic, e.g. dark-mode toggle) | Call at any time post-`render()`
|
|
429
|
+
| Approach | When it applies | How |
|
|
430
|
+
| ----------------------------- | -------------------------------------------- | -------------------------------------------------- |
|
|
431
|
+
| `appearance` init option | At iframe creation (zero flash) | Pass in `PaypercutCheckout({ appearance: { … } })` |
|
|
432
|
+
| `checkout.updateAppearance()` | After mount (dynamic, e.g. dark-mode toggle) | Call at any time post-`render()` |
|
|
284
433
|
|
|
285
434
|
---
|
|
286
435
|
|
|
@@ -293,13 +442,13 @@ const checkout = PaypercutCheckout({
|
|
|
293
442
|
id: 'CHK_xxx',
|
|
294
443
|
containerId: '#checkout',
|
|
295
444
|
appearance: {
|
|
296
|
-
theme: 'dark',
|
|
297
|
-
preset: 'modal',
|
|
445
|
+
theme: 'dark', // 'light' | 'dark'
|
|
446
|
+
preset: 'modal', // 'inline' | 'modal'
|
|
298
447
|
variables: {
|
|
299
|
-
brandColor:
|
|
300
|
-
fontFamily:
|
|
448
|
+
brandColor: '#ff5500', // CTA button background
|
|
449
|
+
fontFamily: 'Inter, sans-serif',
|
|
301
450
|
borderRadius: '12px',
|
|
302
|
-
logoUrl:
|
|
451
|
+
logoUrl: 'https://cdn.example.com/logo.png',
|
|
303
452
|
},
|
|
304
453
|
},
|
|
305
454
|
});
|
|
@@ -309,10 +458,10 @@ checkout.render();
|
|
|
309
458
|
|
|
310
459
|
**`preset`**
|
|
311
460
|
|
|
312
|
-
| Value
|
|
313
|
-
|
|
314
|
-
| `'inline'` | Compact form without the order summary card
|
|
315
|
-
| `'modal'`
|
|
461
|
+
| Value | Effect |
|
|
462
|
+
| ---------- | ------------------------------------------------------------ |
|
|
463
|
+
| `'inline'` | Compact form without the order summary card |
|
|
464
|
+
| `'modal'` | Full form with order summary card + logo rendered at the top |
|
|
316
465
|
|
|
317
466
|
---
|
|
318
467
|
|
|
@@ -348,12 +497,12 @@ Updates are **merged** — you only need to pass the fields you want to change.
|
|
|
348
497
|
|
|
349
498
|
### `AppearanceVariables` reference
|
|
350
499
|
|
|
351
|
-
| Field
|
|
352
|
-
|
|
353
|
-
| `brandColor`
|
|
354
|
-
| `fontFamily`
|
|
355
|
-
| `borderRadius` | `string`
|
|
356
|
-
| `logoUrl`
|
|
500
|
+
| Field | Type | Description |
|
|
501
|
+
| -------------- | -------------------- | -------------------------------------------------------------------------------------------- |
|
|
502
|
+
| `brandColor` | `` `#${string}` `` | Background color of the primary CTA (Pay Now) button. Must be a hex value, e.g. `'#ff5500'`. |
|
|
503
|
+
| `fontFamily` | `string` | CSS font-family value. Applied globally inside the checkout. E.g. `'Inter, sans-serif'`. |
|
|
504
|
+
| `borderRadius` | `string` | CSS length value for element corner radii. Accepts `px`, `rem`, or `em`. E.g. `'8px'`. |
|
|
505
|
+
| `logoUrl` | `string` (https URL) | Your logo shown above the checkout header when `preset: 'modal'`. Must be `https://`. |
|
|
357
506
|
|
|
358
507
|
`brandColor` must be a 3- or 6-digit hex value (e.g. `'#fff'` or `'#ffffff'`). Invalid values log a warning and are silently dropped — the existing color is preserved.
|
|
359
508
|
|
|
@@ -384,17 +533,17 @@ Subscribe to events using the `on()` method. You can use string event names or t
|
|
|
384
533
|
|
|
385
534
|
### Event Reference
|
|
386
535
|
|
|
387
|
-
| Event
|
|
388
|
-
|
|
389
|
-
| `loaded`
|
|
390
|
-
| `processing`
|
|
391
|
-
| `success`
|
|
392
|
-
| `error`
|
|
393
|
-
| `expired`
|
|
394
|
-
| `threeds_started`
|
|
395
|
-
| `threeds_complete` | `SdkEvent.ThreeDSComplete` | 3DS challenge completed
|
|
396
|
-
| `threeds_canceled` | `SdkEvent.ThreeDSCanceled` | 3DS challenge canceled by user
|
|
397
|
-
| `threeds_error`
|
|
536
|
+
| Event | Enum | Description | Payload |
|
|
537
|
+
| ------------------ | -------------------------- | --------------------------------------------------------- | ----------------------------- |
|
|
538
|
+
| `loaded` | `SdkEvent.Loaded` | Checkout iframe has finished loading | `void` |
|
|
539
|
+
| `processing` | `SdkEvent.Processing` | Payment processing has started inside the hosted checkout | `{ checkoutId: string }` |
|
|
540
|
+
| `success` | `SdkEvent.Success` | Payment completed successfully | `PaymentSuccessPayload` |
|
|
541
|
+
| `error` | `SdkEvent.Error` | Terminal failure (tokenize, confirm, or 3DS) | `ApiErrorPayload` |
|
|
542
|
+
| `expired` | `SdkEvent.Expired` | Checkout session expired | `void` |
|
|
543
|
+
| `threeds_started` | `SdkEvent.ThreeDSStarted` | 3DS challenge flow started | `object` |
|
|
544
|
+
| `threeds_complete` | `SdkEvent.ThreeDSComplete` | 3DS challenge completed | `object` |
|
|
545
|
+
| `threeds_canceled` | `SdkEvent.ThreeDSCanceled` | 3DS challenge canceled by user | `object` |
|
|
546
|
+
| `threeds_error` | `SdkEvent.ThreeDSError` | 3DS challenge error | `ApiErrorPayload` or `object` |
|
|
398
547
|
|
|
399
548
|
### Usage Examples
|
|
400
549
|
|
|
@@ -480,10 +629,10 @@ The `success` event returns a `PaymentSuccessPayload` with the payment method de
|
|
|
480
629
|
```ts
|
|
481
630
|
type PaymentSuccessPayload = {
|
|
482
631
|
payment_method: {
|
|
483
|
-
brand: string;
|
|
484
|
-
last4: string;
|
|
485
|
-
exp_month: number;
|
|
486
|
-
exp_year: number;
|
|
632
|
+
brand: string; // e.g., 'visa', 'mastercard', 'amex'
|
|
633
|
+
last4: string; // Last 4 digits of card number
|
|
634
|
+
exp_month: number; // Expiration month (1-12)
|
|
635
|
+
exp_year: number; // Expiration year (e.g., 2030)
|
|
487
636
|
};
|
|
488
637
|
};
|
|
489
638
|
```
|
|
@@ -502,7 +651,9 @@ checkout.on('success', (payload) => {
|
|
|
502
651
|
// }
|
|
503
652
|
// }
|
|
504
653
|
|
|
505
|
-
console.log(
|
|
654
|
+
console.log(
|
|
655
|
+
`Paid with ${payload.payment_method.brand} ending in ${payload.payment_method.last4}`,
|
|
656
|
+
);
|
|
506
657
|
// Output: "Paid with visa ending in 4242"
|
|
507
658
|
});
|
|
508
659
|
```
|
|
@@ -541,7 +692,6 @@ checkout.on('error', (err) => {
|
|
|
541
692
|
|
|
542
693
|
## Form Validation for Wallet Payments
|
|
543
694
|
|
|
544
|
-
|
|
545
695
|
### How It Works
|
|
546
696
|
|
|
547
697
|
1. User clicks Apple Pay or Google Pay button in the checkout
|
|
@@ -553,10 +703,10 @@ checkout.on('error', (err) => {
|
|
|
553
703
|
|
|
554
704
|
### Event: `form_validation`
|
|
555
705
|
|
|
556
|
-
| Property
|
|
557
|
-
|
|
558
|
-
| `checkoutId` | `string`
|
|
559
|
-
| `wallet`
|
|
706
|
+
| Property | Type | Description |
|
|
707
|
+
| ------------ | ----------------------------- | ------------------------------- |
|
|
708
|
+
| `checkoutId` | `string` | The checkout session ID |
|
|
709
|
+
| `wallet` | `'apple_pay' \| 'google_pay'` | Which wallet button was clicked |
|
|
560
710
|
|
|
561
711
|
### Methods
|
|
562
712
|
|
|
@@ -575,7 +725,7 @@ Call this when your form has errors. The wallet will not open, and you should di
|
|
|
575
725
|
```typescript
|
|
576
726
|
checkout.failFormValidation('apple_pay', [
|
|
577
727
|
{ code: 'invalid_email', message: 'Please enter a valid email address' },
|
|
578
|
-
{ code: 'missing_address', message: 'Shipping address is required' }
|
|
728
|
+
{ code: 'missing_address', message: 'Shipping address is required' },
|
|
579
729
|
]);
|
|
580
730
|
```
|
|
581
731
|
|
|
@@ -587,7 +737,7 @@ import { PaypercutCheckout, SdkEvent } from '@paypercut/checkout-js';
|
|
|
587
737
|
const checkout = PaypercutCheckout({
|
|
588
738
|
id: '01KB23M9EC960C50G3AH14FTTT',
|
|
589
739
|
containerId: '#checkout',
|
|
590
|
-
wallet_options: ['apple_pay', 'google_pay']
|
|
740
|
+
wallet_options: ['apple_pay', 'google_pay'],
|
|
591
741
|
});
|
|
592
742
|
|
|
593
743
|
// Handle form validation for wallet payments
|
|
@@ -603,7 +753,7 @@ checkout.on(SdkEvent.FormValidation, ({ wallet, checkoutId }) => {
|
|
|
603
753
|
// Form has errors - block wallet and show your errors
|
|
604
754
|
document.getElementById('email-error').textContent = 'Please enter a valid email';
|
|
605
755
|
checkout.failFormValidation(wallet, [
|
|
606
|
-
{ code: 'invalid_email', message: 'Please enter a valid email' }
|
|
756
|
+
{ code: 'invalid_email', message: 'Please enter a valid email' },
|
|
607
757
|
]);
|
|
608
758
|
}
|
|
609
759
|
});
|
|
@@ -631,7 +781,7 @@ export function CheckoutWithForm({ checkoutId }: { checkoutId: string }) {
|
|
|
631
781
|
containerId: containerRef.current,
|
|
632
782
|
ui_mode: 'embedded',
|
|
633
783
|
wallet_options: ['apple_pay', 'google_pay'],
|
|
634
|
-
validate_form: true
|
|
784
|
+
validate_form: true,
|
|
635
785
|
});
|
|
636
786
|
|
|
637
787
|
// Handle wallet form validation
|
|
@@ -643,9 +793,7 @@ export function CheckoutWithForm({ checkoutId }: { checkoutId: string }) {
|
|
|
643
793
|
checkout.completeFormValidation(wallet);
|
|
644
794
|
} else {
|
|
645
795
|
setEmailError('Please enter a valid email address');
|
|
646
|
-
checkout.failFormValidation(wallet, [
|
|
647
|
-
{ code: 'invalid_email', message: 'Invalid email' }
|
|
648
|
-
]);
|
|
796
|
+
checkout.failFormValidation(wallet, [{ code: 'invalid_email', message: 'Invalid email' }]);
|
|
649
797
|
}
|
|
650
798
|
});
|
|
651
799
|
|
|
@@ -663,13 +811,13 @@ export function CheckoutWithForm({ checkoutId }: { checkoutId: string }) {
|
|
|
663
811
|
<div>
|
|
664
812
|
{/* Your custom form fields */}
|
|
665
813
|
<div>
|
|
666
|
-
<label htmlFor=
|
|
814
|
+
<label htmlFor='email'>Email</label>
|
|
667
815
|
<input
|
|
668
|
-
id=
|
|
669
|
-
type=
|
|
816
|
+
id='email'
|
|
817
|
+
type='email'
|
|
670
818
|
value={email}
|
|
671
819
|
onChange={(e) => setEmail(e.target.value)}
|
|
672
|
-
placeholder=
|
|
820
|
+
placeholder='your@email.com'
|
|
673
821
|
/>
|
|
674
822
|
{emailError && <span style={{ color: 'red' }}>{emailError}</span>}
|
|
675
823
|
</div>
|
|
@@ -684,6 +832,7 @@ export function CheckoutWithForm({ checkoutId }: { checkoutId: string }) {
|
|
|
684
832
|
### Timeout Behavior
|
|
685
833
|
|
|
686
834
|
If you don't respond to the `form_validation` event within 10 seconds, the SDK will:
|
|
835
|
+
|
|
687
836
|
1. Emit an `error` event with code `form_validation_timeout`
|
|
688
837
|
2. Block the wallet payment from starting
|
|
689
838
|
|
|
@@ -692,6 +841,7 @@ This ensures the checkout doesn't hang indefinitely if the handler is not implem
|
|
|
692
841
|
### When to Use
|
|
693
842
|
|
|
694
843
|
Use form validation when you have:
|
|
844
|
+
|
|
695
845
|
- Custom email/phone fields outside the checkout iframe
|
|
696
846
|
- Shipping address forms that must be filled before payment
|
|
697
847
|
- Terms & conditions checkboxes that must be accepted
|
|
@@ -708,6 +858,53 @@ checkout.on('form_validation', ({ wallet }) => {
|
|
|
708
858
|
|
|
709
859
|
---
|
|
710
860
|
|
|
861
|
+
## Paypercut Elements errors
|
|
862
|
+
|
|
863
|
+
`PaymentElement.submit()` and the Element's `error` event expose a stable
|
|
864
|
+
machine-readable `code` and a `recoverable` flag.
|
|
865
|
+
The accompanying `message` is diagnostic English text. Customer-facing copy
|
|
866
|
+
should be owned and localized by the merchant integration by mapping `code` to
|
|
867
|
+
its own translated message.
|
|
868
|
+
|
|
869
|
+
```ts
|
|
870
|
+
try {
|
|
871
|
+
const paymentMethod = await paymentElement.submit();
|
|
872
|
+
await sendPaymentMethodToYourServer(paymentMethod);
|
|
873
|
+
} catch (error) {
|
|
874
|
+
const elementsError = error as PaymentElementSubmitError;
|
|
875
|
+
showLocalizedPaymentError(elementsError.code);
|
|
876
|
+
|
|
877
|
+
if (!elementsError.recoverable) {
|
|
878
|
+
disableThisPaymentMethod();
|
|
879
|
+
}
|
|
880
|
+
}
|
|
881
|
+
```
|
|
882
|
+
|
|
883
|
+
The public `PaymentElementErrorCode` type contains the known codes below and an
|
|
884
|
+
open string member. This lets a newer hosted component introduce a safe code
|
|
885
|
+
without forcing the merchant to upgrade Paypercut.js first. Integrations must
|
|
886
|
+
always keep a generic translated fallback.
|
|
887
|
+
|
|
888
|
+
| Family | Codes | Meaning and integration response |
|
|
889
|
+
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
890
|
+
| Payment details | `elements_payment_details_incomplete` | Required secure fields are empty or incomplete. Keep the form visible, focus or highlight its fields, and ask the customer to complete it. |
|
|
891
|
+
| Payment details | `elements_payment_details_invalid` | One or more completed fields are invalid. Keep the form visible and ask the customer to correct the highlighted fields. |
|
|
892
|
+
| Payment Method creation | `elements_payment_method_creation_failed` | The secure component could not create the server-consumable Payment Method. Keep the form mounted; offer a retry or another payment method according to `recoverable`. |
|
|
893
|
+
| Element lifecycle | `elements_destroyed`, `elements_not_mounted`, `elements_not_ready`, `elements_reinitialized` | The caller submitted against an unavailable or replaced Element instance. Wait for `ready`, remount, or recreate the Element as appropriate. |
|
|
894
|
+
| Controller/component initialization | `elements_initialization_invalid`, `elements_locale_invalid`, `elements_controller_failed`, `elements_component_configuration_invalid`, `elements_component_connect_failed`, `elements_component_attach_failed`, `elements_component_not_ready`, `elements_provider_initialization_failed` | The secure Elements surface could not initialize. Do not expose internal diagnostics; show a translated unavailable message and offer another payment method. |
|
|
895
|
+
| Elements session | `elements_session_expired`, `elements_session_binding_mismatch`, `elements_session_verification_failed` | The form's authoritative configuration is expired or cannot be verified. Recreate or reload the Elements group instead of blindly resubmitting. |
|
|
896
|
+
| Submission concurrency | `elements_submission_in_progress`, `elements_submit_in_progress`, `elements_test_preset_in_progress` | Another operation already owns the Element. Keep the form visible and wait for that operation to settle. |
|
|
897
|
+
| Submission result | `elements_submission_failed`, `elements_submit_failed` | Submission failed with no more specific safe classification. Use the generic translated fallback and `recoverable`. |
|
|
898
|
+
| Ambiguous submission | `elements_submit_indeterminate`, `elements_submit_invalid_response`, `elements_submit_timeout` | The caller cannot safely infer whether the operation completed. Reconcile server state or refresh before another financial attempt. |
|
|
899
|
+
| Action shell | `elements_action_canceled`, `elements_action_channel_unavailable`, `elements_action_shell_timeout` | The detached action was canceled or its trusted channel could not be established. Keep the payment form available and give translated retry/alternative guidance. |
|
|
900
|
+
| 3DS verification | `elements_action_challenge_failed`, `elements_three_ds_authentication_failed`, `elements_three_ds_challenge_failed`, `elements_three_ds_challenge_invalid`, `elements_three_ds_decoupled_not_supported`, `elements_three_ds_provider_session_failed`, `elements_three_ds_scope_mismatch` | Verification did not complete with trusted evidence. Never treat the payment as authenticated; allow a safe retry or another payment method according to server state. |
|
|
901
|
+
|
|
902
|
+
These codes describe client collection and action handling. Once a concrete
|
|
903
|
+
PaymentIntent or Checkout confirmation is attempted, server-owned Paycore
|
|
904
|
+
fields such as `code`, `message_code`, `advice_code`, and `decline_code` remain
|
|
905
|
+
the authority for payment-attempt failures. They are a separate taxonomy and
|
|
906
|
+
should likewise be mapped to localized integration copy.
|
|
907
|
+
|
|
711
908
|
## Types
|
|
712
909
|
|
|
713
910
|
### ApiErrorPayload
|
|
@@ -719,9 +916,12 @@ The SDK forwards the error payload provided by Hosted Checkout. Common shapes in
|
|
|
719
916
|
type CardField = 'card_number' | 'expiration_date' | 'cvc' | 'cardholder_name';
|
|
720
917
|
|
|
721
918
|
type CardValidationErrorCode =
|
|
722
|
-
| 'invalid_number'
|
|
723
|
-
| '
|
|
724
|
-
| '
|
|
919
|
+
| 'invalid_number'
|
|
920
|
+
| 'incomplete_number'
|
|
921
|
+
| 'invalid_expiry'
|
|
922
|
+
| 'incomplete_expiry'
|
|
923
|
+
| 'invalid_cvc'
|
|
924
|
+
| 'incomplete_cvc'
|
|
725
925
|
| 'required';
|
|
726
926
|
|
|
727
927
|
type VendorValidationType = 'invalid' | 'incomplete' | 'required';
|
|
@@ -754,7 +954,7 @@ type ApiErrorPayload =
|
|
|
754
954
|
type?: 'card_error' | string;
|
|
755
955
|
message?: string;
|
|
756
956
|
status_code?: number; // some sources use `status`
|
|
757
|
-
status?: number;
|
|
957
|
+
status?: number; // compatibility with some payloads
|
|
758
958
|
decline_code?: string; // Optional decline reason
|
|
759
959
|
trace_id?: string;
|
|
760
960
|
timestamp?: string; // ISO8601
|
|
@@ -772,8 +972,18 @@ type ApiErrorPayload =
|
|
|
772
972
|
"status_code": 400,
|
|
773
973
|
"timestamp": "2025-01-01T12:00:00.000Z",
|
|
774
974
|
"errors": [
|
|
775
|
-
{
|
|
776
|
-
|
|
975
|
+
{
|
|
976
|
+
"field": "card_number",
|
|
977
|
+
"code": "invalid_number",
|
|
978
|
+
"message": "Card number is invalid",
|
|
979
|
+
"vendor_type": "invalid"
|
|
980
|
+
},
|
|
981
|
+
{
|
|
982
|
+
"field": "expiration_date",
|
|
983
|
+
"code": "incomplete_expiry",
|
|
984
|
+
"message": "Incomplete date",
|
|
985
|
+
"vendor_type": "incomplete"
|
|
986
|
+
}
|
|
777
987
|
]
|
|
778
988
|
}
|
|
779
989
|
```
|
|
@@ -815,8 +1025,8 @@ type ApiErrorPayload =
|
|
|
815
1025
|
- session_expired — Checkout session is no longer valid; create a new session.
|
|
816
1026
|
- permission_denied — Server responded with permission error (e.g., session not allowed). Not enumerated above; SDK forwards unknown codes unchanged.
|
|
817
1027
|
|
|
818
|
-
|
|
819
1028
|
Notes:
|
|
1029
|
+
|
|
820
1030
|
- For 3DS issues, you may receive `threeds_error` with `status_code` 424 and a server-provided message.
|
|
821
1031
|
- For declines, expect `code: 'card_declined'`, optional `decline_code`, and a user-friendly `message`.
|
|
822
1032
|
- The validation error `message` fields are already localized based on the checkout’s locale.
|
|
@@ -857,7 +1067,6 @@ The SDK forwards whatever Hosted Checkout sends for 3DS events. Shapes may evolv
|
|
|
857
1067
|
|
|
858
1068
|
Tip: Prefer subscribing with the SdkEvent enum for stronger typing.
|
|
859
1069
|
|
|
860
|
-
|
|
861
1070
|
## Usage Examples
|
|
862
1071
|
|
|
863
1072
|
### Vanilla JavaScript (CDN)
|
|
@@ -865,34 +1074,39 @@ Tip: Prefer subscribing with the SdkEvent enum for stronger typing.
|
|
|
865
1074
|
```html
|
|
866
1075
|
<!DOCTYPE html>
|
|
867
1076
|
<html>
|
|
868
|
-
<head>
|
|
869
|
-
|
|
870
|
-
</head>
|
|
871
|
-
<body>
|
|
872
|
-
|
|
873
|
-
|
|
874
|
-
|
|
875
|
-
|
|
876
|
-
|
|
877
|
-
|
|
878
|
-
|
|
879
|
-
|
|
880
|
-
|
|
881
|
-
|
|
882
|
-
|
|
1077
|
+
<head>
|
|
1078
|
+
<title>Paypercut Checkout</title>
|
|
1079
|
+
</head>
|
|
1080
|
+
<body>
|
|
1081
|
+
<div id="checkout"></div>
|
|
1082
|
+
|
|
1083
|
+
<script src="https://cdn.jsdelivr.net/npm/@paypercut/checkout-js@1.2.19/dist/paypercut-checkout.iife.min.js"></script>
|
|
1084
|
+
<script>
|
|
1085
|
+
const checkout = PaypercutCheckout({
|
|
1086
|
+
id: '01KB23M9EC960C50G3AH14FTTT',
|
|
1087
|
+
containerId: '#checkout',
|
|
1088
|
+
locale: 'en',
|
|
1089
|
+
ui_mode: 'embedded',
|
|
1090
|
+
wallet_options: ['apple_pay', 'google_pay'],
|
|
1091
|
+
});
|
|
883
1092
|
|
|
884
|
-
|
|
885
|
-
|
|
886
|
-
|
|
887
|
-
|
|
1093
|
+
checkout.on('success', function (payload) {
|
|
1094
|
+
// payload.payment_method: { brand, last4, exp_month, exp_year }
|
|
1095
|
+
alert(
|
|
1096
|
+
'Payment successful with ' +
|
|
1097
|
+
payload.payment_method.brand +
|
|
1098
|
+
' ending in ' +
|
|
1099
|
+
payload.payment_method.last4,
|
|
1100
|
+
);
|
|
1101
|
+
});
|
|
888
1102
|
|
|
889
|
-
|
|
890
|
-
|
|
891
|
-
|
|
1103
|
+
checkout.on('error', function (error) {
|
|
1104
|
+
alert('Payment failed: ' + error.message);
|
|
1105
|
+
});
|
|
892
1106
|
|
|
893
|
-
|
|
894
|
-
|
|
895
|
-
</body>
|
|
1107
|
+
checkout.render();
|
|
1108
|
+
</script>
|
|
1109
|
+
</body>
|
|
896
1110
|
</html>
|
|
897
1111
|
```
|
|
898
1112
|
|
|
@@ -907,7 +1121,7 @@ const checkout = PaypercutCheckout({
|
|
|
907
1121
|
locale: 'auto',
|
|
908
1122
|
ui_mode: 'embedded',
|
|
909
1123
|
wallet_options: ['apple_pay', 'google_pay'],
|
|
910
|
-
form_only: false
|
|
1124
|
+
form_only: false,
|
|
911
1125
|
});
|
|
912
1126
|
|
|
913
1127
|
checkout.on('success', (payload) => {
|
|
@@ -955,7 +1169,7 @@ export function CheckoutComponent({ checkoutId }: { checkoutId: string }) {
|
|
|
955
1169
|
locale: 'auto',
|
|
956
1170
|
ui_mode: 'embedded',
|
|
957
1171
|
wallet_options: ['apple_pay', 'google_pay'],
|
|
958
|
-
form_only: false
|
|
1172
|
+
form_only: false,
|
|
959
1173
|
});
|
|
960
1174
|
|
|
961
1175
|
checkout.on('loaded', () => {
|
|
@@ -987,7 +1201,9 @@ export function CheckoutComponent({ checkoutId }: { checkoutId: string }) {
|
|
|
987
1201
|
<div ref={containerRef} style={{ width: '100%', height: '600px' }} />
|
|
988
1202
|
{status === 'loading' && <p>Processing payment...</p>}
|
|
989
1203
|
{status === 'success' && paymentMethod && (
|
|
990
|
-
<p
|
|
1204
|
+
<p>
|
|
1205
|
+
✅ Payment successful with {paymentMethod.brand} ending in {paymentMethod.last4}!
|
|
1206
|
+
</p>
|
|
991
1207
|
)}
|
|
992
1208
|
{status === 'error' && <p>❌ Payment failed. Please try again.</p>}
|
|
993
1209
|
</div>
|
|
@@ -1003,7 +1219,13 @@ If you want to create a modal-like experience, you can use the `loaded` event to
|
|
|
1003
1219
|
import { useEffect, useRef, useState } from 'react';
|
|
1004
1220
|
import { PaypercutCheckout, CheckoutInstance } from '@paypercut/checkout-js';
|
|
1005
1221
|
|
|
1006
|
-
export function ModalCheckout({
|
|
1222
|
+
export function ModalCheckout({
|
|
1223
|
+
checkoutId,
|
|
1224
|
+
onClose,
|
|
1225
|
+
}: {
|
|
1226
|
+
checkoutId: string;
|
|
1227
|
+
onClose: () => void;
|
|
1228
|
+
}) {
|
|
1007
1229
|
const containerRef = useRef<HTMLDivElement>(null);
|
|
1008
1230
|
const [isLoading, setIsLoading] = useState(true);
|
|
1009
1231
|
|
|
@@ -1012,7 +1234,7 @@ export function ModalCheckout({ checkoutId, onClose }: { checkoutId: string; onC
|
|
|
1012
1234
|
|
|
1013
1235
|
const checkout = PaypercutCheckout({
|
|
1014
1236
|
id: checkoutId,
|
|
1015
|
-
containerId: containerRef.current
|
|
1237
|
+
containerId: containerRef.current,
|
|
1016
1238
|
});
|
|
1017
1239
|
|
|
1018
1240
|
checkout.on('loaded', () => {
|
|
@@ -1036,41 +1258,47 @@ export function ModalCheckout({ checkoutId, onClose }: { checkoutId: string; onC
|
|
|
1036
1258
|
}, [checkoutId, onClose]);
|
|
1037
1259
|
|
|
1038
1260
|
return (
|
|
1039
|
-
<div
|
|
1040
|
-
|
|
1041
|
-
|
|
1042
|
-
|
|
1043
|
-
|
|
1044
|
-
|
|
1045
|
-
|
|
1046
|
-
|
|
1047
|
-
|
|
1048
|
-
|
|
1049
|
-
|
|
1050
|
-
|
|
1051
|
-
|
|
1052
|
-
|
|
1053
|
-
|
|
1054
|
-
|
|
1055
|
-
|
|
1056
|
-
|
|
1057
|
-
|
|
1058
|
-
|
|
1059
|
-
|
|
1060
|
-
|
|
1261
|
+
<div
|
|
1262
|
+
style={{
|
|
1263
|
+
position: 'fixed',
|
|
1264
|
+
top: 0,
|
|
1265
|
+
left: 0,
|
|
1266
|
+
right: 0,
|
|
1267
|
+
bottom: 0,
|
|
1268
|
+
backgroundColor: 'rgba(0, 0, 0, 0.5)',
|
|
1269
|
+
display: 'flex',
|
|
1270
|
+
alignItems: 'center',
|
|
1271
|
+
justifyContent: 'center',
|
|
1272
|
+
zIndex: 9999,
|
|
1273
|
+
}}
|
|
1274
|
+
>
|
|
1275
|
+
<div
|
|
1276
|
+
style={{
|
|
1277
|
+
position: 'relative',
|
|
1278
|
+
width: '90%',
|
|
1279
|
+
maxWidth: '500px',
|
|
1280
|
+
height: '90%',
|
|
1281
|
+
maxHeight: '700px',
|
|
1282
|
+
backgroundColor: '#fff',
|
|
1283
|
+
borderRadius: '12px',
|
|
1284
|
+
overflow: 'hidden',
|
|
1285
|
+
}}
|
|
1286
|
+
>
|
|
1061
1287
|
{isLoading && (
|
|
1062
|
-
<div
|
|
1063
|
-
|
|
1064
|
-
|
|
1065
|
-
|
|
1066
|
-
|
|
1067
|
-
|
|
1068
|
-
|
|
1069
|
-
|
|
1070
|
-
|
|
1071
|
-
|
|
1072
|
-
|
|
1073
|
-
|
|
1288
|
+
<div
|
|
1289
|
+
style={{
|
|
1290
|
+
position: 'absolute',
|
|
1291
|
+
top: 0,
|
|
1292
|
+
left: 0,
|
|
1293
|
+
right: 0,
|
|
1294
|
+
bottom: 0,
|
|
1295
|
+
display: 'flex',
|
|
1296
|
+
alignItems: 'center',
|
|
1297
|
+
justifyContent: 'center',
|
|
1298
|
+
backgroundColor: '#fff',
|
|
1299
|
+
zIndex: 1,
|
|
1300
|
+
}}
|
|
1301
|
+
>
|
|
1074
1302
|
<p>Loading checkout...</p>
|
|
1075
1303
|
</div>
|
|
1076
1304
|
)}
|
|
@@ -1081,7 +1309,7 @@ export function ModalCheckout({ checkoutId, onClose }: { checkoutId: string; onC
|
|
|
1081
1309
|
position: 'absolute',
|
|
1082
1310
|
top: '10px',
|
|
1083
1311
|
right: '10px',
|
|
1084
|
-
zIndex: 2
|
|
1312
|
+
zIndex: 2,
|
|
1085
1313
|
}}
|
|
1086
1314
|
>
|
|
1087
1315
|
✕
|
|
@@ -1135,7 +1363,7 @@ The SDK automatically resizes the iframe to match the checkout content height. T
|
|
|
1135
1363
|
```javascript
|
|
1136
1364
|
const checkout = PaypercutCheckout({
|
|
1137
1365
|
id: '01KB23M9EC960C50G3AH14FTTT',
|
|
1138
|
-
containerId: '#checkout-mount'
|
|
1366
|
+
containerId: '#checkout-mount',
|
|
1139
1367
|
});
|
|
1140
1368
|
checkout.render();
|
|
1141
1369
|
```
|
|
@@ -1170,6 +1398,7 @@ Always use HTTPS in production. The SDK is designed for secure communication ove
|
|
|
1170
1398
|
**Problem:** The iframe doesn't appear after calling `render()`.
|
|
1171
1399
|
|
|
1172
1400
|
**Solutions:**
|
|
1401
|
+
|
|
1173
1402
|
- Ensure the container element exists in the DOM before calling `render()`
|
|
1174
1403
|
- Check that the `id` is a valid checkout session ID
|
|
1175
1404
|
- Verify there are no CSP errors in the browser console
|
|
@@ -1180,6 +1409,7 @@ Always use HTTPS in production. The SDK is designed for secure communication ove
|
|
|
1180
1409
|
**Problem:** Event handlers are not being called.
|
|
1181
1410
|
|
|
1182
1411
|
**Solutions:**
|
|
1412
|
+
|
|
1183
1413
|
- Ensure you subscribe to events before calling `render()`
|
|
1184
1414
|
- Check that the checkout session is active and not expired
|
|
1185
1415
|
- Enable debug mode to see message logs
|
|
@@ -1189,6 +1419,7 @@ Always use HTTPS in production. The SDK is designed for secure communication ove
|
|
|
1189
1419
|
**Problem:** TypeScript shows type errors when using the SDK.
|
|
1190
1420
|
|
|
1191
1421
|
**Solutions:**
|
|
1422
|
+
|
|
1192
1423
|
- Ensure you're importing types: `import { PaypercutCheckout, CheckoutInstance } from '@paypercut/checkout-js'`
|
|
1193
1424
|
- Update to the latest version of the SDK
|
|
1194
1425
|
- Check that your `tsconfig.json` includes the SDK's type definitions
|
|
@@ -1200,8 +1431,8 @@ Always use HTTPS in production. The SDK is designed for secure communication ove
|
|
|
1200
1431
|
Add DNS prefetch and preconnect hints to your HTML for faster loading:
|
|
1201
1432
|
|
|
1202
1433
|
```html
|
|
1203
|
-
<link rel="preconnect" href="https://buy.paypercut.io "
|
|
1204
|
-
<link rel="dns-prefetch" href="https://buy.paypercut.io "
|
|
1434
|
+
<link rel="preconnect" href="https://buy.paypercut.io " />
|
|
1435
|
+
<link rel="dns-prefetch" href="https://buy.paypercut.io " />
|
|
1205
1436
|
```
|
|
1206
1437
|
|
|
1207
1438
|
### Lazy Loading
|
|
@@ -1308,16 +1539,15 @@ The following shows the **exact call/receive sequence** for a complete Express C
|
|
|
1308
1539
|
|
|
1309
1540
|
const express = PaypercutExpressCheckout({
|
|
1310
1541
|
publishableKey: 'pk_test_...',
|
|
1311
|
-
amount: 2500,
|
|
1542
|
+
amount: 2500, // €25.00 — the initial total (before shipping is chosen)
|
|
1312
1543
|
currency: 'EUR',
|
|
1313
1544
|
countryCode: 'DE',
|
|
1314
1545
|
shippingOptions: [
|
|
1315
1546
|
{ id: 'standard', label: 'Standard Shipping', detail: '3–5 days', amount: 499 },
|
|
1316
|
-
{ id: 'express',
|
|
1547
|
+
{ id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
|
|
1317
1548
|
],
|
|
1318
1549
|
});
|
|
1319
1550
|
|
|
1320
|
-
|
|
1321
1551
|
// ─── Step 2: Subscribe to events (before mount) ───────────────────────────────
|
|
1322
1552
|
// Always subscribe before calling mount().
|
|
1323
1553
|
|
|
@@ -1331,7 +1561,6 @@ express.on('click', () => {
|
|
|
1331
1561
|
console.log('Wallet sheet opening...');
|
|
1332
1562
|
});
|
|
1333
1563
|
|
|
1334
|
-
|
|
1335
1564
|
// ─── Step 3: Wallet sheet opens — provide initial shipping options ─────────────
|
|
1336
1565
|
// You RECEIVE: 'session_start' when the wallet sheet opens, BEFORE any address
|
|
1337
1566
|
// or option is shown. The wallet sheet is PAUSED — you must call updateWith()
|
|
@@ -1348,20 +1577,20 @@ express.on('session_start', async ({ wallet, updateWith }) => {
|
|
|
1348
1577
|
|
|
1349
1578
|
// You CALL: updateWith() — this unblocks the wallet sheet with initial options
|
|
1350
1579
|
updateWith({
|
|
1351
|
-
amount: 2500 + 499,
|
|
1580
|
+
amount: 2500 + 499, // subtotal + default shipping cost
|
|
1352
1581
|
shippingOptions: [
|
|
1353
1582
|
{ id: 'standard', label: 'Standard Shipping', detail: '3–5 days', amount: 499 },
|
|
1354
|
-
{ id: 'express',
|
|
1583
|
+
{ id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
|
|
1355
1584
|
],
|
|
1356
|
-
lineItems: [
|
|
1357
|
-
|
|
1585
|
+
lineItems: [
|
|
1586
|
+
// Apple Pay only — line item breakdown
|
|
1587
|
+
{ label: 'Subtotal', amount: 2500 },
|
|
1358
1588
|
{ label: 'Standard Shipping', amount: 499 },
|
|
1359
1589
|
],
|
|
1360
1590
|
});
|
|
1361
1591
|
// → Wallet sheet now renders with these options
|
|
1362
1592
|
});
|
|
1363
1593
|
|
|
1364
|
-
|
|
1365
1594
|
// ─── Step 4: User changes shipping address ────────────────────────────────────
|
|
1366
1595
|
// You RECEIVE: 'shipping_address_change' with a partial address
|
|
1367
1596
|
// (country, state, city, postalCode — no street at this stage)
|
|
@@ -1377,13 +1606,15 @@ express.on('shipping_address_change', ({ address, updateWith }) => {
|
|
|
1377
1606
|
|
|
1378
1607
|
// You CALL: updateWith() — this unblocks the wallet sheet and updates the displayed total
|
|
1379
1608
|
updateWith({
|
|
1380
|
-
amount: newTotal,
|
|
1381
|
-
shippingOptions: [
|
|
1609
|
+
amount: newTotal, // new total including shipping
|
|
1610
|
+
shippingOptions: [
|
|
1611
|
+
// updated options for this region
|
|
1382
1612
|
{ id: 'standard', label: 'Standard Shipping', amount: shippingCost },
|
|
1383
|
-
{ id: 'express',
|
|
1613
|
+
{ id: 'express', label: 'Express Shipping', amount: shippingCost + 500 },
|
|
1384
1614
|
],
|
|
1385
|
-
lineItems: [
|
|
1386
|
-
|
|
1615
|
+
lineItems: [
|
|
1616
|
+
// Apple Pay only — line item breakdown
|
|
1617
|
+
{ label: 'Subtotal', amount: 2500 },
|
|
1387
1618
|
{ label: 'Standard Shipping', amount: shippingCost },
|
|
1388
1619
|
],
|
|
1389
1620
|
// To reject an unsupported address instead:
|
|
@@ -1392,7 +1623,6 @@ express.on('shipping_address_change', ({ address, updateWith }) => {
|
|
|
1392
1623
|
// → Wallet sheet now shows the updated total and shipping options
|
|
1393
1624
|
});
|
|
1394
1625
|
|
|
1395
|
-
|
|
1396
1626
|
// ─── Step 5: User selects a shipping option ───────────────────────────────────
|
|
1397
1627
|
// You RECEIVE: 'shipping_option_change' when the user switches e.g. Standard → Express
|
|
1398
1628
|
// The wallet sheet is PAUSED again — you must call updateWith() again.
|
|
@@ -1406,40 +1636,48 @@ express.on('shipping_option_change', ({ shippingOption, updateWith }) => {
|
|
|
1406
1636
|
// You CALL: updateWith() — unblocks the sheet with the new total
|
|
1407
1637
|
updateWith({
|
|
1408
1638
|
amount: newTotal,
|
|
1409
|
-
lineItems: [
|
|
1410
|
-
|
|
1411
|
-
{ label:
|
|
1639
|
+
lineItems: [
|
|
1640
|
+
// Apple Pay only
|
|
1641
|
+
{ label: 'Subtotal', amount: 2500 },
|
|
1642
|
+
{ label: shippingOption.label, amount: shippingOption.amount },
|
|
1412
1643
|
],
|
|
1413
1644
|
});
|
|
1414
1645
|
// → Wallet sheet updates to show the new total
|
|
1415
1646
|
});
|
|
1416
1647
|
|
|
1417
|
-
|
|
1418
1648
|
// ─── Step 6: User confirms payment ───────────────────────────────────────────
|
|
1419
1649
|
// User taps "Pay" in the wallet sheet.
|
|
1420
1650
|
// SDK tokenizes the card via Basis Theory, creates a Paypercut payment method,
|
|
1421
1651
|
// and auto-closes the wallet sheet. No action needed from you to close the sheet.
|
|
1422
1652
|
|
|
1423
1653
|
// You RECEIVE: 'payment_method_created' with the payment method ID
|
|
1424
|
-
express.on(
|
|
1425
|
-
|
|
1426
|
-
|
|
1427
|
-
|
|
1428
|
-
|
|
1429
|
-
|
|
1430
|
-
|
|
1431
|
-
|
|
1432
|
-
|
|
1433
|
-
method:
|
|
1434
|
-
|
|
1435
|
-
|
|
1436
|
-
|
|
1437
|
-
|
|
1438
|
-
|
|
1439
|
-
|
|
1440
|
-
|
|
1441
|
-
|
|
1654
|
+
express.on(
|
|
1655
|
+
'payment_method_created',
|
|
1656
|
+
async ({
|
|
1657
|
+
paymentMethodId,
|
|
1658
|
+
idempotencyKey,
|
|
1659
|
+
billingDetails,
|
|
1660
|
+
shippingDetails,
|
|
1661
|
+
selectedShippingOption,
|
|
1662
|
+
}) => {
|
|
1663
|
+
console.log('Payment method created:', paymentMethodId);
|
|
1664
|
+
// paymentMethodId = 'pm_01J...'
|
|
1665
|
+
// billingDetails = { name: 'John Doe', address: { line1: '...', country: 'DE', ... } }
|
|
1666
|
+
// shippingDetails = { name: 'John Doe', address: { line1: '48 Example St', ... } }
|
|
1667
|
+
// selectedShippingOption = { id: 'express', label: 'Express Shipping', amount: 999 }
|
|
1668
|
+
|
|
1669
|
+
// You CALL: your backend to create and confirm the payment intent
|
|
1670
|
+
const res = await fetch('/api/confirm-payment', {
|
|
1671
|
+
method: 'POST',
|
|
1672
|
+
headers: { 'Content-Type': 'application/json' },
|
|
1673
|
+
body: JSON.stringify({ paymentMethodId, idempotencyKey }),
|
|
1674
|
+
});
|
|
1442
1675
|
|
|
1676
|
+
if (res.ok) {
|
|
1677
|
+
window.location.href = '/success';
|
|
1678
|
+
}
|
|
1679
|
+
},
|
|
1680
|
+
);
|
|
1443
1681
|
|
|
1444
1682
|
// ─── Step 7: Handle failure or cancellation ───────────────────────────────────
|
|
1445
1683
|
// You RECEIVE: 'payment_method_failed' if tokenization or PM creation fails
|
|
@@ -1453,13 +1691,11 @@ express.on('cancel', () => {
|
|
|
1453
1691
|
console.log('User closed the wallet sheet');
|
|
1454
1692
|
});
|
|
1455
1693
|
|
|
1456
|
-
|
|
1457
1694
|
// ─── Step 8: Mount ────────────────────────────────────────────────────────────
|
|
1458
1695
|
// You CALL: mount() — renders the wallet buttons into the container
|
|
1459
1696
|
express.mount('#express-checkout');
|
|
1460
1697
|
// → 'ready' fires once buttons are visible
|
|
1461
1698
|
|
|
1462
|
-
|
|
1463
1699
|
// ─── Step 9: Cleanup ─────────────────────────────────────────────────────────
|
|
1464
1700
|
// You CALL: destroy() when the component unmounts to prevent memory leaks
|
|
1465
1701
|
// express.destroy();
|
|
@@ -1474,12 +1710,12 @@ import { PaypercutExpressCheckout, ExpressSdkEvent } from '@paypercut/checkout-j
|
|
|
1474
1710
|
|
|
1475
1711
|
const express = PaypercutExpressCheckout({
|
|
1476
1712
|
publishableKey: 'pk_test_...',
|
|
1477
|
-
amount: 2999,
|
|
1713
|
+
amount: 2999, // in minor units (€29.99)
|
|
1478
1714
|
currency: 'EUR',
|
|
1479
1715
|
countryCode: 'DE',
|
|
1480
1716
|
shippingOptions: [
|
|
1481
1717
|
{ id: 'standard', label: 'Standard Shipping', detail: '3–5 business days', amount: 499 },
|
|
1482
|
-
{ id: 'express',
|
|
1718
|
+
{ id: 'express', label: 'Express Shipping', detail: '1–2 business days', amount: 999 },
|
|
1483
1719
|
],
|
|
1484
1720
|
});
|
|
1485
1721
|
|
|
@@ -1490,18 +1726,18 @@ express.mount('#express-checkout');
|
|
|
1490
1726
|
|
|
1491
1727
|
### Express Checkout Options
|
|
1492
1728
|
|
|
1493
|
-
| Option
|
|
1494
|
-
|
|
1495
|
-
| `publishableKey`
|
|
1496
|
-
| `amount`
|
|
1497
|
-
| `currency`
|
|
1498
|
-
| `countryCode`
|
|
1499
|
-
| `shippingOptions` | `ExpressCheckoutShippingOption[]` | Yes
|
|
1500
|
-
| `lineItems`
|
|
1501
|
-
| `walletOptions`
|
|
1502
|
-
| `layout`
|
|
1503
|
-
| `locale`
|
|
1504
|
-
| `buttonOptions`
|
|
1729
|
+
| Option | Type | Required | Description |
|
|
1730
|
+
| ----------------- | --------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
1731
|
+
| `publishableKey` | `string` | Yes | Your Paypercut publishable API key (`pk_test_…` or `pk_live_…`) |
|
|
1732
|
+
| `amount` | `number` | Yes | Total amount in **minor units** (e.g. `1200` = €12.00) |
|
|
1733
|
+
| `currency` | `string` | Yes | ISO 4217 currency code (e.g. `'EUR'`, `'USD'`) |
|
|
1734
|
+
| `countryCode` | `string` | Yes | ISO 3166-1 alpha-2 merchant country code (e.g. `'DE'`). Required for Google Pay in production. |
|
|
1735
|
+
| `shippingOptions` | `ExpressCheckoutShippingOption[]` | Yes | Initial shipping options shown in the wallet sheet. Must include at least one. |
|
|
1736
|
+
| `lineItems` | `LineItem[]` | No | Line item breakdown shown in the **Apple Pay** sheet (subtotal, tax, etc.). Ignored by Google Pay. |
|
|
1737
|
+
| `walletOptions` | `('apple_pay' \| 'google_pay')[]` | No | Which wallets to show. Defaults to both. |
|
|
1738
|
+
| `layout` | `'auto' \| 'row' \| 'column'` | No | Button layout. `'auto'` _(default)_ uses a ResizeObserver to switch between row (>540 px) and column (≤540 px) automatically. `'row'` is always side by side. `'column'` always stacks vertically. |
|
|
1739
|
+
| `locale` | `string` | No | ISO 639-1 two-letter language code (e.g. `'en'`, `'bg'`, `'pl'`). Controls the language of the wallet button labels. Each wallet applies this independently — not all languages are supported by every wallet; unsupported values fall back to `'en'`. |
|
|
1740
|
+
| `buttonOptions` | `ExpressButtonOptions` | No | Customize the label type and color/style of the wallet buttons. See [Button Options](#button-options) below. |
|
|
1505
1741
|
|
|
1506
1742
|
---
|
|
1507
1743
|
|
|
@@ -1513,36 +1749,36 @@ Control the label and appearance of the Apple Pay and Google Pay buttons via the
|
|
|
1513
1749
|
PaypercutExpressCheckout({
|
|
1514
1750
|
// ...
|
|
1515
1751
|
buttonOptions: {
|
|
1516
|
-
type: 'pay',
|
|
1517
|
-
applePayStyle: 'black',
|
|
1752
|
+
type: 'pay', // label shown on both buttons — defaults to 'buy'
|
|
1753
|
+
applePayStyle: 'black', // Apple Pay button color — defaults to 'black'
|
|
1518
1754
|
googlePayColor: 'default', // Google Pay button color — defaults to 'default'
|
|
1519
|
-
borderRadius: '0.5rem',
|
|
1755
|
+
borderRadius: '0.5rem', // border radius for both buttons — defaults to '0.5rem'
|
|
1520
1756
|
},
|
|
1521
1757
|
});
|
|
1522
1758
|
```
|
|
1523
1759
|
|
|
1524
1760
|
#### `type` — applies to both Apple Pay and Google Pay
|
|
1525
1761
|
|
|
1526
|
-
| Value
|
|
1527
|
-
|
|
1528
|
-
| `'plain'`
|
|
1529
|
-
| `'pay'`
|
|
1530
|
-
| `'buy'`
|
|
1531
|
-
| `'donate'`
|
|
1532
|
-
| `'checkout'`
|
|
1533
|
-
| `'subscribe'`
|
|
1534
|
-
| `'book'`
|
|
1535
|
-
| `'order'`
|
|
1536
|
-
| `'tip'`
|
|
1537
|
-
| `'contribute'`
|
|
1762
|
+
| Value | Button label |
|
|
1763
|
+
| --------------------- | ---------------------------------------- |
|
|
1764
|
+
| `'plain'` _(default)_ | Logo only (no text) |
|
|
1765
|
+
| `'pay'` | Pay with Apple Pay / Pay with Google Pay |
|
|
1766
|
+
| `'buy'` | Buy with Apple Pay / Buy with Google Pay |
|
|
1767
|
+
| `'donate'` | Donate with … |
|
|
1768
|
+
| `'checkout'` | Checkout with … |
|
|
1769
|
+
| `'subscribe'` | Subscribe with … |
|
|
1770
|
+
| `'book'` | Book with … |
|
|
1771
|
+
| `'order'` | Order with … |
|
|
1772
|
+
| `'tip'` | Tip with … |
|
|
1773
|
+
| `'contribute'` | Contribute with … |
|
|
1538
1774
|
|
|
1539
1775
|
#### `applePayStyle` — Apple Pay only
|
|
1540
1776
|
|
|
1541
|
-
| Value
|
|
1542
|
-
|
|
1543
|
-
| `'black'`
|
|
1544
|
-
| `'white'`
|
|
1545
|
-
| `'white-outline'`
|
|
1777
|
+
| Value | Appearance |
|
|
1778
|
+
| --------------------- | ------------------------------------------------ |
|
|
1779
|
+
| `'black'` _(default)_ | Black background, white logo |
|
|
1780
|
+
| `'white'` | White background, black logo |
|
|
1781
|
+
| `'white-outline'` | White background with a black border, black logo |
|
|
1546
1782
|
|
|
1547
1783
|
#### `borderRadius` — applies to both
|
|
1548
1784
|
|
|
@@ -1550,23 +1786,23 @@ Any valid CSS value (e.g. `'0.5rem'`, `'8px'`, `'50%'`). Defaults to `'0.5rem'`.
|
|
|
1550
1786
|
|
|
1551
1787
|
#### `googlePayColor` — Google Pay only
|
|
1552
1788
|
|
|
1553
|
-
| Value
|
|
1554
|
-
|
|
1555
|
-
| `'default'`
|
|
1556
|
-
| `'black'`
|
|
1557
|
-
| `'white'`
|
|
1789
|
+
| Value | Appearance |
|
|
1790
|
+
| ----------------------- | ----------------------------------------------------- |
|
|
1791
|
+
| `'default'` _(default)_ | White background on light themes, dark on dark themes |
|
|
1792
|
+
| `'black'` | Black background |
|
|
1793
|
+
| `'white'` | White background |
|
|
1558
1794
|
|
|
1559
1795
|
```typescript
|
|
1560
1796
|
interface ExpressCheckoutShippingOption {
|
|
1561
|
-
id: string;
|
|
1562
|
-
label: string;
|
|
1563
|
-
detail?: string;
|
|
1564
|
-
amount: number;
|
|
1797
|
+
id: string; // unique identifier, e.g. 'standard'
|
|
1798
|
+
label: string; // display label, e.g. 'Standard Shipping'
|
|
1799
|
+
detail?: string; // subtitle, e.g. '3–5 business days'
|
|
1800
|
+
amount: number; // cost in minor units
|
|
1565
1801
|
}
|
|
1566
1802
|
|
|
1567
1803
|
interface LineItem {
|
|
1568
1804
|
label: string;
|
|
1569
|
-
amount: number;
|
|
1805
|
+
amount: number; // minor units
|
|
1570
1806
|
type?: 'final' | 'pending';
|
|
1571
1807
|
}
|
|
1572
1808
|
```
|
|
@@ -1603,7 +1839,7 @@ express.update({
|
|
|
1603
1839
|
amount: 3998,
|
|
1604
1840
|
shippingOptions: [
|
|
1605
1841
|
{ id: 'standard', label: 'Standard Shipping', amount: 499 },
|
|
1606
|
-
{ id: 'express',
|
|
1842
|
+
{ id: 'express', label: 'Express Shipping', amount: 999 },
|
|
1607
1843
|
],
|
|
1608
1844
|
});
|
|
1609
1845
|
```
|
|
@@ -1620,17 +1856,17 @@ express.destroy();
|
|
|
1620
1856
|
|
|
1621
1857
|
### Express Checkout Events
|
|
1622
1858
|
|
|
1623
|
-
| Event
|
|
1624
|
-
|
|
1625
|
-
| `ready`
|
|
1626
|
-
| `click`
|
|
1627
|
-
| `session_start`
|
|
1628
|
-
| `shipping_address_change` | `ExpressSdkEvent.ShippingAddressChange` | `ShippingAddressChangeEvent`
|
|
1629
|
-
| `shipping_option_change`
|
|
1630
|
-
| `payment_method_created`
|
|
1631
|
-
| `payment_method_failed`
|
|
1632
|
-
| `cancel`
|
|
1633
|
-
| `error`
|
|
1859
|
+
| Event | Enum | Payload | Description |
|
|
1860
|
+
| ------------------------- | --------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------- |
|
|
1861
|
+
| `ready` | `ExpressSdkEvent.Ready` | — | Wallet buttons are rendered and ready |
|
|
1862
|
+
| `click` | `ExpressSdkEvent.Click` | — | User tapped a wallet button |
|
|
1863
|
+
| `session_start` | `ExpressSdkEvent.SessionStart` | `ExpressSessionStartEvent` | Wallet sheet opened — **must call `updateWith()`** with initial options to unblock |
|
|
1864
|
+
| `shipping_address_change` | `ExpressSdkEvent.ShippingAddressChange` | `ShippingAddressChangeEvent` | User changed shipping address — must call `updateWith()` |
|
|
1865
|
+
| `shipping_option_change` | `ExpressSdkEvent.ShippingOptionChange` | `ShippingOptionChangeEvent` | User selected a different shipping option — must call `updateWith()` |
|
|
1866
|
+
| `payment_method_created` | `ExpressSdkEvent.PaymentMethodCreated` | `ExpressPaymentMethodCreatedEvent` | Payment method created — use `paymentMethodId` to confirm on backend |
|
|
1867
|
+
| `payment_method_failed` | `ExpressSdkEvent.PaymentMethodFailed` | `ExpressPaymentMethodFailedEvent` | Tokenization or payment method creation failed |
|
|
1868
|
+
| `cancel` | `ExpressSdkEvent.Cancel` | — | User dismissed the wallet sheet |
|
|
1869
|
+
| `error` | `ExpressSdkEvent.Error` | `Error` | Unrecoverable SDK error |
|
|
1634
1870
|
|
|
1635
1871
|
---
|
|
1636
1872
|
|
|
@@ -1656,7 +1892,7 @@ express.on('shipping_address_change', ({ address, updateWith }) => {
|
|
|
1656
1892
|
amount: newTotal,
|
|
1657
1893
|
shippingOptions: [
|
|
1658
1894
|
{ id: 'standard', label: 'Standard Shipping', amount: shippingCost },
|
|
1659
|
-
{ id: 'express',
|
|
1895
|
+
{ id: 'express', label: 'Express Shipping', amount: shippingCost + 500 },
|
|
1660
1896
|
],
|
|
1661
1897
|
// Use 'invalid_shipping_address' if you don't ship to this address:
|
|
1662
1898
|
// status: 'invalid_shipping_address',
|
|
@@ -1689,12 +1925,12 @@ express.on('shipping_option_change', ({ shippingOption, updateWith }) => {
|
|
|
1689
1925
|
|
|
1690
1926
|
#### `updateWith()` options
|
|
1691
1927
|
|
|
1692
|
-
| Field
|
|
1693
|
-
|
|
1694
|
-
| `amount`
|
|
1695
|
-
| `shippingOptions` | `ExpressCheckoutShippingOption[]`
|
|
1696
|
-
| `lineItems`
|
|
1697
|
-
| `status`
|
|
1928
|
+
| Field | Type | Description |
|
|
1929
|
+
| ----------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
1930
|
+
| `amount` | `number` | New total in minor units |
|
|
1931
|
+
| `shippingOptions` | `ExpressCheckoutShippingOption[]` | Updated shipping options list |
|
|
1932
|
+
| `lineItems` | `LineItem[]` | Updated Apple Pay line items (ignored by Google Pay) |
|
|
1933
|
+
| `status` | `'success' \| 'invalid_shipping_address' \| 'invalid_shipping_option'` | Use an invalid status to show an error inside the sheet without closing it |
|
|
1698
1934
|
|
|
1699
1935
|
---
|
|
1700
1936
|
|
|
@@ -1745,7 +1981,7 @@ express.on('shipping_address_change', ({ address, updateWith }) => {
|
|
|
1745
1981
|
amount: subtotal + shippingCost,
|
|
1746
1982
|
shippingOptions: [
|
|
1747
1983
|
{ id: 'standard', label: 'Standard Shipping', amount: shippingCost },
|
|
1748
|
-
{ id: 'express',
|
|
1984
|
+
{ id: 'express', label: 'Express Shipping', amount: shippingCost + 500 },
|
|
1749
1985
|
],
|
|
1750
1986
|
});
|
|
1751
1987
|
});
|
|
@@ -1790,11 +2026,11 @@ express.on('shipping_address_change', ({ address, updateWith }) => {
|
|
|
1790
2026
|
|
|
1791
2027
|
#### Summary
|
|
1792
2028
|
|
|
1793
|
-
| Approach
|
|
1794
|
-
|
|
1795
|
-
| `allowedCountries` in options
|
|
1796
|
-
| `status: 'invalid_shipping_address'` in `shipping_address_change` | ✅
|
|
1797
|
-
| Both combined
|
|
2029
|
+
| Approach | Apple Pay | Google Pay | UX |
|
|
2030
|
+
| ----------------------------------------------------------------- | ----------------- | --------------------- | ------------------------------------ |
|
|
2031
|
+
| `allowedCountries` in options | ✗ not supported | ✅ restricts picker | Best — error before user interacts |
|
|
2032
|
+
| `status: 'invalid_shipping_address'` in `shipping_address_change` | ✅ | ✅ | Sheet shows inline error, stays open |
|
|
2033
|
+
| Both combined | ✅ (runtime only) | ✅ (picker + runtime) | Recommended |
|
|
1798
2034
|
|
|
1799
2035
|
---
|
|
1800
2036
|
|
|
@@ -1814,10 +2050,10 @@ const SUBTOTAL = 4900; // €49.00
|
|
|
1814
2050
|
|
|
1815
2051
|
const express = PaypercutExpressCheckout({
|
|
1816
2052
|
publishableKey: 'pk_live_...',
|
|
1817
|
-
amount: SUBTOTAL + 499,
|
|
2053
|
+
amount: SUBTOTAL + 499, // subtotal + default shipping
|
|
1818
2054
|
currency: 'EUR',
|
|
1819
2055
|
countryCode: 'DE',
|
|
1820
|
-
allowedCountries: SUPPORTED_COUNTRIES,
|
|
2056
|
+
allowedCountries: SUPPORTED_COUNTRIES, // Google Pay: restricts picker to these countries
|
|
1821
2057
|
});
|
|
1822
2058
|
|
|
1823
2059
|
// Step 1 — Provide initial shipping options when wallet sheet opens
|
|
@@ -1826,10 +2062,10 @@ express.on('session_start', ({ wallet, updateWith }) => {
|
|
|
1826
2062
|
amount: SUBTOTAL + 499,
|
|
1827
2063
|
shippingOptions: [
|
|
1828
2064
|
{ id: 'standard', label: 'Standard Shipping', detail: '3–5 days', amount: 499 },
|
|
1829
|
-
{ id: 'express',
|
|
2065
|
+
{ id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
|
|
1830
2066
|
],
|
|
1831
2067
|
lineItems: [
|
|
1832
|
-
{ label: 'Subtotal',
|
|
2068
|
+
{ label: 'Subtotal', amount: SUBTOTAL },
|
|
1833
2069
|
{ label: 'Standard Shipping', amount: 499 },
|
|
1834
2070
|
],
|
|
1835
2071
|
});
|
|
@@ -1846,10 +2082,10 @@ express.on('shipping_address_change', ({ address, updateWith }) => {
|
|
|
1846
2082
|
amount: SUBTOTAL + 499,
|
|
1847
2083
|
shippingOptions: [
|
|
1848
2084
|
{ id: 'standard', label: 'Standard Shipping', detail: '3–5 days', amount: 499 },
|
|
1849
|
-
{ id: 'express',
|
|
2085
|
+
{ id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
|
|
1850
2086
|
],
|
|
1851
2087
|
lineItems: [
|
|
1852
|
-
{ label: 'Subtotal',
|
|
2088
|
+
{ label: 'Subtotal', amount: SUBTOTAL },
|
|
1853
2089
|
{ label: 'Standard Shipping', amount: 499 },
|
|
1854
2090
|
],
|
|
1855
2091
|
});
|
|
@@ -1860,26 +2096,29 @@ express.on('shipping_option_change', ({ shippingOption, updateWith }) => {
|
|
|
1860
2096
|
updateWith({
|
|
1861
2097
|
amount: SUBTOTAL + shippingOption.amount,
|
|
1862
2098
|
lineItems: [
|
|
1863
|
-
{ label: 'Subtotal',
|
|
2099
|
+
{ label: 'Subtotal', amount: SUBTOTAL },
|
|
1864
2100
|
{ label: shippingOption.label, amount: shippingOption.amount },
|
|
1865
2101
|
],
|
|
1866
2102
|
});
|
|
1867
2103
|
});
|
|
1868
2104
|
|
|
1869
2105
|
// Step 4 — Payment method created, confirm on your backend
|
|
1870
|
-
express.on(
|
|
1871
|
-
|
|
1872
|
-
|
|
1873
|
-
|
|
1874
|
-
|
|
1875
|
-
|
|
1876
|
-
|
|
1877
|
-
|
|
1878
|
-
|
|
1879
|
-
|
|
1880
|
-
|
|
1881
|
-
|
|
1882
|
-
});
|
|
2106
|
+
express.on(
|
|
2107
|
+
'payment_method_created',
|
|
2108
|
+
async ({ paymentMethodId, idempotencyKey, shippingDetails, selectedShippingOption }) => {
|
|
2109
|
+
await fetch('/api/orders', {
|
|
2110
|
+
method: 'POST',
|
|
2111
|
+
headers: { 'Content-Type': 'application/json' },
|
|
2112
|
+
body: JSON.stringify({
|
|
2113
|
+
paymentMethodId,
|
|
2114
|
+
idempotencyKey,
|
|
2115
|
+
shippingAddress: shippingDetails?.address,
|
|
2116
|
+
shippingOption: selectedShippingOption?.id,
|
|
2117
|
+
}),
|
|
2118
|
+
});
|
|
2119
|
+
window.location.href = '/order/confirmation';
|
|
2120
|
+
},
|
|
2121
|
+
);
|
|
1883
2122
|
|
|
1884
2123
|
express.on('shipping_options_required', ({ wallet }) => {
|
|
1885
2124
|
console.error(`${wallet}: session_start timed out — shipping options were not provided`);
|
|
@@ -1902,7 +2141,7 @@ const SUBTOTAL = 7500; // €75.00
|
|
|
1902
2141
|
|
|
1903
2142
|
const express = PaypercutExpressCheckout({
|
|
1904
2143
|
publishableKey: 'pk_live_...',
|
|
1905
|
-
amount: SUBTOTAL,
|
|
2144
|
+
amount: SUBTOTAL, // no shipping added yet — will be set in session_start
|
|
1906
2145
|
currency: 'EUR',
|
|
1907
2146
|
countryCode: 'DE',
|
|
1908
2147
|
allowedCountries: ['DE', 'AT', 'CH', 'NL', 'BE', 'FR', 'IT', 'ES'],
|
|
@@ -1911,15 +2150,15 @@ const express = PaypercutExpressCheckout({
|
|
|
1911
2150
|
// Step 1 — Fetch initial options from your API before the sheet opens
|
|
1912
2151
|
express.on('session_start', async ({ wallet, updateWith }) => {
|
|
1913
2152
|
// Call your backend — you have 3 seconds
|
|
1914
|
-
const { options, defaultAmount } = await fetch('/api/shipping/default').then(r => r.json());
|
|
2153
|
+
const { options, defaultAmount } = await fetch('/api/shipping/default').then((r) => r.json());
|
|
1915
2154
|
// e.g. { options: [{ id: 'standard', label: 'Standard', amount: 599 }], defaultAmount: 8099 }
|
|
1916
2155
|
|
|
1917
2156
|
updateWith({
|
|
1918
2157
|
amount: defaultAmount,
|
|
1919
2158
|
shippingOptions: options,
|
|
1920
2159
|
lineItems: [
|
|
1921
|
-
{ label: 'Subtotal',
|
|
1922
|
-
{ label: options[0].label,
|
|
2160
|
+
{ label: 'Subtotal', amount: SUBTOTAL },
|
|
2161
|
+
{ label: options[0].label, amount: options[0].amount },
|
|
1923
2162
|
],
|
|
1924
2163
|
});
|
|
1925
2164
|
});
|
|
@@ -1945,7 +2184,7 @@ express.on('shipping_address_change', async ({ address, updateWith }) => {
|
|
|
1945
2184
|
amount: total,
|
|
1946
2185
|
shippingOptions: options,
|
|
1947
2186
|
lineItems: [
|
|
1948
|
-
{ label: 'Subtotal',
|
|
2187
|
+
{ label: 'Subtotal', amount: SUBTOTAL },
|
|
1949
2188
|
{ label: options[0].label, amount: options[0].amount },
|
|
1950
2189
|
],
|
|
1951
2190
|
});
|
|
@@ -1956,28 +2195,37 @@ express.on('shipping_option_change', ({ shippingOption, updateWith }) => {
|
|
|
1956
2195
|
updateWith({
|
|
1957
2196
|
amount: SUBTOTAL + shippingOption.amount,
|
|
1958
2197
|
lineItems: [
|
|
1959
|
-
{ label: 'Subtotal',
|
|
2198
|
+
{ label: 'Subtotal', amount: SUBTOTAL },
|
|
1960
2199
|
{ label: shippingOption.label, amount: shippingOption.amount },
|
|
1961
2200
|
],
|
|
1962
2201
|
});
|
|
1963
2202
|
});
|
|
1964
2203
|
|
|
1965
2204
|
// Step 4 — Create order on backend
|
|
1966
|
-
express.on(
|
|
1967
|
-
|
|
1968
|
-
|
|
1969
|
-
|
|
1970
|
-
|
|
1971
|
-
|
|
1972
|
-
|
|
1973
|
-
|
|
1974
|
-
|
|
1975
|
-
|
|
1976
|
-
|
|
1977
|
-
|
|
1978
|
-
|
|
1979
|
-
|
|
1980
|
-
|
|
2205
|
+
express.on(
|
|
2206
|
+
'payment_method_created',
|
|
2207
|
+
async ({
|
|
2208
|
+
paymentMethodId,
|
|
2209
|
+
idempotencyKey,
|
|
2210
|
+
billingDetails,
|
|
2211
|
+
shippingDetails,
|
|
2212
|
+
selectedShippingOption,
|
|
2213
|
+
}) => {
|
|
2214
|
+
const res = await fetch('/api/orders', {
|
|
2215
|
+
method: 'POST',
|
|
2216
|
+
headers: { 'Content-Type': 'application/json' },
|
|
2217
|
+
body: JSON.stringify({
|
|
2218
|
+
paymentMethodId,
|
|
2219
|
+
idempotencyKey,
|
|
2220
|
+
billing: billingDetails,
|
|
2221
|
+
shipping: shippingDetails,
|
|
2222
|
+
shippingOptionId: selectedShippingOption?.id,
|
|
2223
|
+
}),
|
|
2224
|
+
});
|
|
2225
|
+
const { orderId } = await res.json();
|
|
2226
|
+
window.location.href = `/orders/${orderId}/confirmation`;
|
|
2227
|
+
},
|
|
2228
|
+
);
|
|
1981
2229
|
|
|
1982
2230
|
express.on('shipping_options_required', ({ wallet }) => {
|
|
1983
2231
|
alert(`Could not load shipping options for ${wallet}. Please try again.`);
|
|
@@ -2002,7 +2250,7 @@ import {
|
|
|
2002
2250
|
} from '@paypercut/checkout-js';
|
|
2003
2251
|
|
|
2004
2252
|
interface Props {
|
|
2005
|
-
subtotal: number;
|
|
2253
|
+
subtotal: number; // minor units
|
|
2006
2254
|
onSuccess: (orderId: string) => void;
|
|
2007
2255
|
onCancel: () => void;
|
|
2008
2256
|
}
|
|
@@ -2026,12 +2274,12 @@ export function ExpressCheckout({ subtotal, onSuccess, onCancel }: Props) {
|
|
|
2026
2274
|
|
|
2027
2275
|
// Provide initial options before sheet opens
|
|
2028
2276
|
express.on(ExpressSdkEvent.SessionStart, async ({ wallet, updateWith }) => {
|
|
2029
|
-
const { options } = await fetch('/api/shipping/default').then(r => r.json());
|
|
2277
|
+
const { options } = await fetch('/api/shipping/default').then((r) => r.json());
|
|
2030
2278
|
updateWith({
|
|
2031
2279
|
amount: subtotal + options[0].amount,
|
|
2032
2280
|
shippingOptions: options,
|
|
2033
2281
|
lineItems: [
|
|
2034
|
-
{ label: 'Subtotal',
|
|
2282
|
+
{ label: 'Subtotal', amount: subtotal },
|
|
2035
2283
|
{ label: options[0].label, amount: options[0].amount },
|
|
2036
2284
|
],
|
|
2037
2285
|
});
|
|
@@ -2047,13 +2295,13 @@ export function ExpressCheckout({ subtotal, onSuccess, onCancel }: Props) {
|
|
|
2047
2295
|
method: 'POST',
|
|
2048
2296
|
headers: { 'Content-Type': 'application/json' },
|
|
2049
2297
|
body: JSON.stringify({ country: address.country, postalCode: address.postalCode }),
|
|
2050
|
-
}).then(r => r.json());
|
|
2298
|
+
}).then((r) => r.json());
|
|
2051
2299
|
|
|
2052
2300
|
updateWith({
|
|
2053
2301
|
amount: total,
|
|
2054
2302
|
shippingOptions: options,
|
|
2055
2303
|
lineItems: [
|
|
2056
|
-
{ label: 'Subtotal',
|
|
2304
|
+
{ label: 'Subtotal', amount: subtotal },
|
|
2057
2305
|
{ label: options[0].label, amount: options[0].amount },
|
|
2058
2306
|
],
|
|
2059
2307
|
});
|
|
@@ -2064,33 +2312,38 @@ export function ExpressCheckout({ subtotal, onSuccess, onCancel }: Props) {
|
|
|
2064
2312
|
updateWith({
|
|
2065
2313
|
amount: subtotal + shippingOption.amount,
|
|
2066
2314
|
lineItems: [
|
|
2067
|
-
{ label: 'Subtotal',
|
|
2315
|
+
{ label: 'Subtotal', amount: subtotal },
|
|
2068
2316
|
{ label: shippingOption.label, amount: shippingOption.amount },
|
|
2069
2317
|
],
|
|
2070
2318
|
});
|
|
2071
2319
|
});
|
|
2072
2320
|
|
|
2073
2321
|
// Payment method ready — confirm on backend
|
|
2074
|
-
express.on(
|
|
2075
|
-
|
|
2076
|
-
|
|
2077
|
-
|
|
2078
|
-
|
|
2079
|
-
|
|
2080
|
-
|
|
2081
|
-
|
|
2082
|
-
|
|
2083
|
-
|
|
2084
|
-
|
|
2085
|
-
|
|
2086
|
-
|
|
2087
|
-
|
|
2322
|
+
express.on(
|
|
2323
|
+
ExpressSdkEvent.PaymentMethodCreated,
|
|
2324
|
+
async ({ paymentMethodId, idempotencyKey, shippingDetails, selectedShippingOption }) => {
|
|
2325
|
+
const { orderId } = await fetch('/api/orders', {
|
|
2326
|
+
method: 'POST',
|
|
2327
|
+
headers: { 'Content-Type': 'application/json' },
|
|
2328
|
+
body: JSON.stringify({
|
|
2329
|
+
paymentMethodId,
|
|
2330
|
+
idempotencyKey,
|
|
2331
|
+
shipping: shippingDetails,
|
|
2332
|
+
shippingOptionId: selectedShippingOption?.id,
|
|
2333
|
+
}),
|
|
2334
|
+
}).then((r) => r.json());
|
|
2335
|
+
|
|
2336
|
+
onSuccess(orderId);
|
|
2337
|
+
},
|
|
2338
|
+
);
|
|
2088
2339
|
|
|
2089
2340
|
express.on(ExpressSdkEvent.ShippingOptionsRequired, ({ wallet }) => {
|
|
2090
2341
|
console.error(`${wallet}: session_start timed out — implement the session_start handler`);
|
|
2091
2342
|
});
|
|
2092
2343
|
|
|
2093
|
-
express.on(ExpressSdkEvent.PaymentMethodFailed, ({ error }) =>
|
|
2344
|
+
express.on(ExpressSdkEvent.PaymentMethodFailed, ({ error }) =>
|
|
2345
|
+
console.error('Payment failed:', error),
|
|
2346
|
+
);
|
|
2094
2347
|
express.on(ExpressSdkEvent.Cancel, onCancel);
|
|
2095
2348
|
|
|
2096
2349
|
express.mount(containerRef.current);
|
|
@@ -2138,18 +2391,32 @@ express.on('payment_method_created', (event) => {
|
|
|
2138
2391
|
|
|
2139
2392
|
```typescript
|
|
2140
2393
|
interface ExpressPaymentMethodCreatedEvent {
|
|
2141
|
-
paymentMethodId: string;
|
|
2394
|
+
paymentMethodId: string; // Paypercut PM ID (pm_xxx)
|
|
2142
2395
|
token: { id: string; type: 'apple_pay' | 'google_pay' };
|
|
2143
2396
|
idempotencyKey: string;
|
|
2144
2397
|
billingDetails?: {
|
|
2145
2398
|
name?: string;
|
|
2146
2399
|
email?: string;
|
|
2147
2400
|
phone?: string;
|
|
2148
|
-
address?: {
|
|
2401
|
+
address?: {
|
|
2402
|
+
line1?: string;
|
|
2403
|
+
line2?: string;
|
|
2404
|
+
city?: string;
|
|
2405
|
+
state?: string;
|
|
2406
|
+
postalCode?: string;
|
|
2407
|
+
country?: string;
|
|
2408
|
+
};
|
|
2149
2409
|
};
|
|
2150
2410
|
shippingDetails?: {
|
|
2151
2411
|
name?: string;
|
|
2152
|
-
address?: {
|
|
2412
|
+
address?: {
|
|
2413
|
+
line1?: string;
|
|
2414
|
+
line2?: string;
|
|
2415
|
+
city?: string;
|
|
2416
|
+
state?: string;
|
|
2417
|
+
postalCode?: string;
|
|
2418
|
+
country?: string;
|
|
2419
|
+
};
|
|
2153
2420
|
};
|
|
2154
2421
|
selectedShippingOption?: { id: string; label: string; detail?: string; amount: number };
|
|
2155
2422
|
}
|
|
@@ -2162,80 +2429,82 @@ interface ExpressPaymentMethodCreatedEvent {
|
|
|
2162
2429
|
```html
|
|
2163
2430
|
<!DOCTYPE html>
|
|
2164
2431
|
<html>
|
|
2165
|
-
<head
|
|
2166
|
-
<
|
|
2167
|
-
|
|
2168
|
-
|
|
2169
|
-
|
|
2170
|
-
|
|
2171
|
-
|
|
2172
|
-
|
|
2173
|
-
|
|
2174
|
-
|
|
2175
|
-
|
|
2176
|
-
|
|
2177
|
-
|
|
2178
|
-
{ id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
|
|
2179
|
-
],
|
|
2180
|
-
lineItems: [
|
|
2181
|
-
{ label: 'Subtotal', amount: 2500 },
|
|
2182
|
-
{ label: 'Standard Shipping', amount: 499 },
|
|
2183
|
-
],
|
|
2184
|
-
});
|
|
2185
|
-
|
|
2186
|
-
// Wallet buttons ready
|
|
2187
|
-
express.on('ready', () => console.log('Express Checkout ready'));
|
|
2188
|
-
|
|
2189
|
-
// Shipping address changed — recalculate and respond
|
|
2190
|
-
express.on('shipping_address_change', ({ address, updateWith }) => {
|
|
2191
|
-
const shippingCost = address.country === 'DE' ? 499 : 799;
|
|
2192
|
-
updateWith({
|
|
2193
|
-
amount: 2500 + shippingCost,
|
|
2432
|
+
<head>
|
|
2433
|
+
<title>Express Checkout</title>
|
|
2434
|
+
</head>
|
|
2435
|
+
<body>
|
|
2436
|
+
<div id="express-checkout" style="max-width: 400px;"></div>
|
|
2437
|
+
|
|
2438
|
+
<script src="https://cdn.jsdelivr.net/npm/@paypercut/checkout-js/dist/paypercut-checkout.iife.min.js"></script>
|
|
2439
|
+
<script>
|
|
2440
|
+
const express = PaypercutExpressCheckout({
|
|
2441
|
+
publishableKey: 'pk_test_...',
|
|
2442
|
+
amount: 2500,
|
|
2443
|
+
currency: 'EUR',
|
|
2444
|
+
countryCode: 'DE',
|
|
2194
2445
|
shippingOptions: [
|
|
2195
|
-
{ id: 'standard', label: 'Standard Shipping', amount:
|
|
2196
|
-
{ id: 'express',
|
|
2446
|
+
{ id: 'standard', label: 'Standard Shipping', detail: '3–5 days', amount: 499 },
|
|
2447
|
+
{ id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
|
|
2197
2448
|
],
|
|
2198
2449
|
lineItems: [
|
|
2199
2450
|
{ label: 'Subtotal', amount: 2500 },
|
|
2200
|
-
{ label: 'Standard Shipping', amount:
|
|
2451
|
+
{ label: 'Standard Shipping', amount: 499 },
|
|
2201
2452
|
],
|
|
2202
2453
|
});
|
|
2203
|
-
});
|
|
2204
2454
|
|
|
2205
|
-
|
|
2206
|
-
|
|
2207
|
-
|
|
2208
|
-
|
|
2209
|
-
|
|
2210
|
-
|
|
2211
|
-
|
|
2212
|
-
|
|
2455
|
+
// Wallet buttons ready
|
|
2456
|
+
express.on('ready', () => console.log('Express Checkout ready'));
|
|
2457
|
+
|
|
2458
|
+
// Shipping address changed — recalculate and respond
|
|
2459
|
+
express.on('shipping_address_change', ({ address, updateWith }) => {
|
|
2460
|
+
const shippingCost = address.country === 'DE' ? 499 : 799;
|
|
2461
|
+
updateWith({
|
|
2462
|
+
amount: 2500 + shippingCost,
|
|
2463
|
+
shippingOptions: [
|
|
2464
|
+
{ id: 'standard', label: 'Standard Shipping', amount: shippingCost },
|
|
2465
|
+
{ id: 'express', label: 'Express Shipping', amount: shippingCost + 500 },
|
|
2466
|
+
],
|
|
2467
|
+
lineItems: [
|
|
2468
|
+
{ label: 'Subtotal', amount: 2500 },
|
|
2469
|
+
{ label: 'Standard Shipping', amount: shippingCost },
|
|
2470
|
+
],
|
|
2471
|
+
});
|
|
2213
2472
|
});
|
|
2214
|
-
});
|
|
2215
2473
|
|
|
2216
|
-
|
|
2217
|
-
|
|
2218
|
-
|
|
2219
|
-
|
|
2220
|
-
|
|
2221
|
-
|
|
2222
|
-
|
|
2223
|
-
|
|
2474
|
+
// Shipping option changed — update total
|
|
2475
|
+
express.on('shipping_option_change', ({ shippingOption, updateWith }) => {
|
|
2476
|
+
updateWith({
|
|
2477
|
+
amount: 2500 + shippingOption.amount,
|
|
2478
|
+
lineItems: [
|
|
2479
|
+
{ label: 'Subtotal', amount: 2500 },
|
|
2480
|
+
{ label: shippingOption.label, amount: shippingOption.amount },
|
|
2481
|
+
],
|
|
2482
|
+
});
|
|
2224
2483
|
});
|
|
2225
|
-
window.location.href = '/success';
|
|
2226
|
-
});
|
|
2227
2484
|
|
|
2228
|
-
|
|
2229
|
-
|
|
2230
|
-
|
|
2485
|
+
// Payment method created — confirm on backend
|
|
2486
|
+
express.on('payment_method_created', async (event) => {
|
|
2487
|
+
console.log('Payment method:', event.paymentMethodId);
|
|
2488
|
+
console.log('Shipping option:', event.selectedShippingOption?.label);
|
|
2489
|
+
await fetch('/api/confirm-payment', {
|
|
2490
|
+
method: 'POST',
|
|
2491
|
+
headers: { 'Content-Type': 'application/json' },
|
|
2492
|
+
body: JSON.stringify({ paymentMethodId: event.paymentMethodId }),
|
|
2493
|
+
});
|
|
2494
|
+
window.location.href = '/success';
|
|
2495
|
+
});
|
|
2231
2496
|
|
|
2232
|
-
|
|
2233
|
-
|
|
2234
|
-
|
|
2497
|
+
express.on('payment_method_failed', ({ error }) => {
|
|
2498
|
+
console.error('Payment failed:', error);
|
|
2499
|
+
});
|
|
2500
|
+
|
|
2501
|
+
express.on('cancel', () => {
|
|
2502
|
+
console.log('User dismissed the wallet sheet');
|
|
2503
|
+
});
|
|
2235
2504
|
|
|
2236
|
-
|
|
2237
|
-
|
|
2238
|
-
</body>
|
|
2505
|
+
express.mount('#express-checkout');
|
|
2506
|
+
</script>
|
|
2507
|
+
</body>
|
|
2239
2508
|
</html>
|
|
2240
2509
|
```
|
|
2241
2510
|
|
|
@@ -2245,10 +2514,14 @@ interface ExpressPaymentMethodCreatedEvent {
|
|
|
2245
2514
|
|
|
2246
2515
|
```tsx
|
|
2247
2516
|
import { useEffect, useRef } from 'react';
|
|
2248
|
-
import {
|
|
2517
|
+
import {
|
|
2518
|
+
PaypercutExpressCheckout,
|
|
2519
|
+
ExpressSdkEvent,
|
|
2520
|
+
ExpressCheckoutInstance,
|
|
2521
|
+
} from '@paypercut/checkout-js';
|
|
2249
2522
|
|
|
2250
2523
|
interface Props {
|
|
2251
|
-
subtotal: number;
|
|
2524
|
+
subtotal: number; // minor units
|
|
2252
2525
|
onSuccess: (paymentMethodId: string) => void;
|
|
2253
2526
|
}
|
|
2254
2527
|
|
|
@@ -2261,12 +2534,12 @@ export function ExpressCheckoutButton({ subtotal, onSuccess }: Props) {
|
|
|
2261
2534
|
|
|
2262
2535
|
const express = PaypercutExpressCheckout({
|
|
2263
2536
|
publishableKey: process.env.NEXT_PUBLIC_PAYPERCUT_KEY!,
|
|
2264
|
-
amount: subtotal + 499,
|
|
2537
|
+
amount: subtotal + 499, // subtotal + default shipping
|
|
2265
2538
|
currency: 'EUR',
|
|
2266
2539
|
countryCode: 'DE',
|
|
2267
2540
|
shippingOptions: [
|
|
2268
2541
|
{ id: 'standard', label: 'Standard Shipping', detail: '3–5 days', amount: 499 },
|
|
2269
|
-
{ id: 'express',
|
|
2542
|
+
{ id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
|
|
2270
2543
|
],
|
|
2271
2544
|
});
|
|
2272
2545
|
|
|
@@ -2276,7 +2549,7 @@ export function ExpressCheckoutButton({ subtotal, onSuccess }: Props) {
|
|
|
2276
2549
|
amount: subtotal + shipping,
|
|
2277
2550
|
shippingOptions: [
|
|
2278
2551
|
{ id: 'standard', label: 'Standard Shipping', amount: shipping },
|
|
2279
|
-
{ id: 'express',
|
|
2552
|
+
{ id: 'express', label: 'Express Shipping', amount: shipping + 500 },
|
|
2280
2553
|
],
|
|
2281
2554
|
});
|
|
2282
2555
|
});
|