@paypercut/checkout-js 1.0.23 → 1.1.7
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 +1043 -6
- package/dist/index.cjs +1511 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.ts +261 -3
- package/dist/index.mjs +1511 -2
- 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/package.json +3 -1
package/README.md
CHANGED
|
@@ -11,13 +11,21 @@ A lightweight, framework-agnostic JavaScript SDK for embedding Paypercut Checkou
|
|
|
11
11
|
|
|
12
12
|
## Table of Contents
|
|
13
13
|
|
|
14
|
-
- [Features](#features)
|
|
15
|
-
- [How It Works](#how-it-works)
|
|
16
14
|
- [Installation](#installation)
|
|
17
|
-
- [Quick Start](#quick-start)
|
|
18
|
-
- [API Reference](#api-reference)
|
|
19
|
-
- [Events](#events)
|
|
15
|
+
- [Quick Start — Embedded Checkout](#quick-start)
|
|
16
|
+
- [API Reference — Embedded Checkout](#api-reference)
|
|
17
|
+
- [Events — Embedded Checkout](#events)
|
|
20
18
|
- [Form Validation for Wallet Payments](#form-validation-for-wallet-payments)
|
|
19
|
+
- [**Express Checkout (Apple Pay / Google Pay)**](#express-checkout-apple-pay--google-pay)
|
|
20
|
+
- [How It Works](#how-it-works)
|
|
21
|
+
- [Initialization](#initialization)
|
|
22
|
+
- [Button Options](#button-options)
|
|
23
|
+
- [Options](#express-checkout-options)
|
|
24
|
+
- [Methods](#express-checkout-methods)
|
|
25
|
+
- [Events](#express-checkout-events)
|
|
26
|
+
- [Shipping address & option changes](#shipping-address--option-changes)
|
|
27
|
+
- [Full Example](#express-checkout-full-example)
|
|
28
|
+
- [React Example](#express-checkout-react-example)
|
|
21
29
|
- [Types](#types)
|
|
22
30
|
- [Usage Examples](#usage-examples)
|
|
23
31
|
- [Vanilla JavaScript](#vanilla-javascript-cdn)
|
|
@@ -28,7 +36,6 @@ A lightweight, framework-agnostic JavaScript SDK for embedding Paypercut Checkou
|
|
|
28
36
|
- [Performance Optimization](#performance-optimization)
|
|
29
37
|
- [Best Practices](#best-practices)
|
|
30
38
|
- [FAQ](#faq)
|
|
31
|
-
- [Support](#support)
|
|
32
39
|
|
|
33
40
|
---
|
|
34
41
|
|
|
@@ -1150,6 +1157,1036 @@ useEffect(() => {
|
|
|
1150
1157
|
}, []);
|
|
1151
1158
|
```
|
|
1152
1159
|
|
|
1160
|
+
---
|
|
1161
|
+
|
|
1162
|
+
## Express Checkout (Apple Pay / Google Pay)
|
|
1163
|
+
|
|
1164
|
+
Express Checkout lets you embed standalone Apple Pay and Google Pay buttons anywhere on your page — product pages, cart pages, or a dedicated checkout step — without a full checkout form. The SDK handles wallet sheet presentation, shipping address/option collection, tokenization, and payment method creation automatically.
|
|
1165
|
+
|
|
1166
|
+
### How It Works
|
|
1167
|
+
|
|
1168
|
+
1. Merchant calls `PaypercutExpressCheckout(options)` and mounts it into a container
|
|
1169
|
+
2. SDK renders Apple Pay and/or Google Pay buttons inside a secure hosted iframe
|
|
1170
|
+
3. User clicks a button → wallet payment sheet opens, collecting billing address, shipping address, and shipping option
|
|
1171
|
+
4. User changes shipping address or option → SDK fires `shipping_address_change` / `shipping_option_change` event → **merchant calls `updateWith()` with updated totals** → wallet sheet updates
|
|
1172
|
+
5. User confirms payment → SDK tokenizes the wallet token via Basis Theory, creates a Paypercut payment method, and auto-closes the wallet sheet
|
|
1173
|
+
6. SDK fires `payment_method_created` with `paymentMethodId` — use this server-side to create and confirm a payment intent
|
|
1174
|
+
|
|
1175
|
+
> **Shipping is always required.** Express Checkout always collects both shipping address and shipping option. You must listen for `shipping_address_change` and `shipping_option_change` and call `updateWith()` to unblock the wallet sheet.
|
|
1176
|
+
|
|
1177
|
+
---
|
|
1178
|
+
|
|
1179
|
+
### Step-by-step flow (annotated example)
|
|
1180
|
+
|
|
1181
|
+
The following shows the **exact call/receive sequence** for a complete Express Checkout payment, from initialization to payment confirmation.
|
|
1182
|
+
|
|
1183
|
+
```typescript
|
|
1184
|
+
// ─── Step 1: Initialize ───────────────────────────────────────────────────────
|
|
1185
|
+
// You call PaypercutExpressCheckout() with your config.
|
|
1186
|
+
// Nothing is shown yet — buttons render after mount().
|
|
1187
|
+
|
|
1188
|
+
const express = PaypercutExpressCheckout({
|
|
1189
|
+
publishableKey: 'pk_test_...',
|
|
1190
|
+
amount: 2500, // €25.00 — the initial total (before shipping is chosen)
|
|
1191
|
+
currency: 'EUR',
|
|
1192
|
+
countryCode: 'DE',
|
|
1193
|
+
shippingOptions: [
|
|
1194
|
+
{ id: 'standard', label: 'Standard Shipping', detail: '3–5 days', amount: 499 },
|
|
1195
|
+
{ id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
|
|
1196
|
+
],
|
|
1197
|
+
});
|
|
1198
|
+
|
|
1199
|
+
|
|
1200
|
+
// ─── Step 2: Subscribe to events (before mount) ───────────────────────────────
|
|
1201
|
+
// Always subscribe before calling mount().
|
|
1202
|
+
|
|
1203
|
+
// You RECEIVE: 'ready' — buttons are rendered and visible
|
|
1204
|
+
express.on('ready', () => {
|
|
1205
|
+
console.log('Wallet buttons ready');
|
|
1206
|
+
});
|
|
1207
|
+
|
|
1208
|
+
// You RECEIVE: 'click' — user tapped Apple Pay or Google Pay button
|
|
1209
|
+
express.on('click', () => {
|
|
1210
|
+
console.log('Wallet sheet opening...');
|
|
1211
|
+
});
|
|
1212
|
+
|
|
1213
|
+
|
|
1214
|
+
// ─── Step 3: Wallet sheet opens — provide initial shipping options ─────────────
|
|
1215
|
+
// You RECEIVE: 'session_start' when the wallet sheet opens, BEFORE any address
|
|
1216
|
+
// or option is shown. The wallet sheet is PAUSED — you must call updateWith()
|
|
1217
|
+
// to provide the initial shipping options and unblock the sheet.
|
|
1218
|
+
//
|
|
1219
|
+
// This is your chance to dynamically load options from your backend.
|
|
1220
|
+
// event.wallet tells you which wallet opened: 'apple_pay' | 'google_pay'
|
|
1221
|
+
|
|
1222
|
+
express.on('session_start', async ({ wallet, updateWith }) => {
|
|
1223
|
+
console.log('Wallet sheet opened:', wallet);
|
|
1224
|
+
|
|
1225
|
+
// Optionally fetch shipping options from your backend
|
|
1226
|
+
// const options = await fetch('/api/shipping-options').then(r => r.json());
|
|
1227
|
+
|
|
1228
|
+
// You CALL: updateWith() — this unblocks the wallet sheet with initial options
|
|
1229
|
+
updateWith({
|
|
1230
|
+
amount: 2500 + 499, // subtotal + default shipping cost
|
|
1231
|
+
shippingOptions: [
|
|
1232
|
+
{ id: 'standard', label: 'Standard Shipping', detail: '3–5 days', amount: 499 },
|
|
1233
|
+
{ id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
|
|
1234
|
+
],
|
|
1235
|
+
lineItems: [ // Apple Pay only — line item breakdown
|
|
1236
|
+
{ label: 'Subtotal', amount: 2500 },
|
|
1237
|
+
{ label: 'Standard Shipping', amount: 499 },
|
|
1238
|
+
],
|
|
1239
|
+
});
|
|
1240
|
+
// → Wallet sheet now renders with these options
|
|
1241
|
+
});
|
|
1242
|
+
|
|
1243
|
+
|
|
1244
|
+
// ─── Step 4: User changes shipping address ────────────────────────────────────
|
|
1245
|
+
// You RECEIVE: 'shipping_address_change' with a partial address
|
|
1246
|
+
// (country, state, city, postalCode — no street at this stage)
|
|
1247
|
+
// The wallet sheet is PAUSED — you must call updateWith() to unblock it.
|
|
1248
|
+
|
|
1249
|
+
express.on('shipping_address_change', ({ address, updateWith }) => {
|
|
1250
|
+
console.log('User shipping to:', address.country, address.postalCode);
|
|
1251
|
+
// address = { country: 'DE', state: 'BY', city: 'Munich', postalCode: '80331' }
|
|
1252
|
+
|
|
1253
|
+
// Calculate shipping cost for this address on your end
|
|
1254
|
+
const shippingCost = address.country === 'DE' ? 499 : 999;
|
|
1255
|
+
const newTotal = 2500 + shippingCost;
|
|
1256
|
+
|
|
1257
|
+
// You CALL: updateWith() — this unblocks the wallet sheet and updates the displayed total
|
|
1258
|
+
updateWith({
|
|
1259
|
+
amount: newTotal, // new total including shipping
|
|
1260
|
+
shippingOptions: [ // updated options for this region
|
|
1261
|
+
{ id: 'standard', label: 'Standard Shipping', amount: shippingCost },
|
|
1262
|
+
{ id: 'express', label: 'Express Shipping', amount: shippingCost + 500 },
|
|
1263
|
+
],
|
|
1264
|
+
lineItems: [ // Apple Pay only — line item breakdown
|
|
1265
|
+
{ label: 'Subtotal', amount: 2500 },
|
|
1266
|
+
{ label: 'Standard Shipping', amount: shippingCost },
|
|
1267
|
+
],
|
|
1268
|
+
// To reject an unsupported address instead:
|
|
1269
|
+
// status: 'invalid_shipping_address',
|
|
1270
|
+
});
|
|
1271
|
+
// → Wallet sheet now shows the updated total and shipping options
|
|
1272
|
+
});
|
|
1273
|
+
|
|
1274
|
+
|
|
1275
|
+
// ─── Step 5: User selects a shipping option ───────────────────────────────────
|
|
1276
|
+
// You RECEIVE: 'shipping_option_change' when the user switches e.g. Standard → Express
|
|
1277
|
+
// The wallet sheet is PAUSED again — you must call updateWith() again.
|
|
1278
|
+
|
|
1279
|
+
express.on('shipping_option_change', ({ shippingOption, updateWith }) => {
|
|
1280
|
+
console.log('User picked:', shippingOption.label, shippingOption.amount);
|
|
1281
|
+
// shippingOption = { id: 'express', label: 'Express Shipping', amount: 999 }
|
|
1282
|
+
|
|
1283
|
+
const newTotal = 2500 + shippingOption.amount;
|
|
1284
|
+
|
|
1285
|
+
// You CALL: updateWith() — unblocks the sheet with the new total
|
|
1286
|
+
updateWith({
|
|
1287
|
+
amount: newTotal,
|
|
1288
|
+
lineItems: [ // Apple Pay only
|
|
1289
|
+
{ label: 'Subtotal', amount: 2500 },
|
|
1290
|
+
{ label: shippingOption.label, amount: shippingOption.amount },
|
|
1291
|
+
],
|
|
1292
|
+
});
|
|
1293
|
+
// → Wallet sheet updates to show the new total
|
|
1294
|
+
});
|
|
1295
|
+
|
|
1296
|
+
|
|
1297
|
+
// ─── Step 6: User confirms payment ───────────────────────────────────────────
|
|
1298
|
+
// User taps "Pay" in the wallet sheet.
|
|
1299
|
+
// SDK tokenizes the card via Basis Theory, creates a Paypercut payment method,
|
|
1300
|
+
// and auto-closes the wallet sheet. No action needed from you to close the sheet.
|
|
1301
|
+
|
|
1302
|
+
// You RECEIVE: 'payment_method_created' with the payment method ID
|
|
1303
|
+
express.on('payment_method_created', async ({ paymentMethodId, idempotencyKey, billingDetails, shippingDetails, selectedShippingOption }) => {
|
|
1304
|
+
console.log('Payment method created:', paymentMethodId);
|
|
1305
|
+
// paymentMethodId = 'pm_01J...'
|
|
1306
|
+
// billingDetails = { name: 'John Doe', address: { line1: '...', country: 'DE', ... } }
|
|
1307
|
+
// shippingDetails = { name: 'John Doe', address: { line1: '48 Example St', ... } }
|
|
1308
|
+
// selectedShippingOption = { id: 'express', label: 'Express Shipping', amount: 999 }
|
|
1309
|
+
|
|
1310
|
+
// You CALL: your backend to create and confirm the payment intent
|
|
1311
|
+
const res = await fetch('/api/confirm-payment', {
|
|
1312
|
+
method: 'POST',
|
|
1313
|
+
headers: { 'Content-Type': 'application/json' },
|
|
1314
|
+
body: JSON.stringify({ paymentMethodId, idempotencyKey }),
|
|
1315
|
+
});
|
|
1316
|
+
|
|
1317
|
+
if (res.ok) {
|
|
1318
|
+
window.location.href = '/success';
|
|
1319
|
+
}
|
|
1320
|
+
});
|
|
1321
|
+
|
|
1322
|
+
|
|
1323
|
+
// ─── Step 7: Handle failure or cancellation ───────────────────────────────────
|
|
1324
|
+
// You RECEIVE: 'payment_method_failed' if tokenization or PM creation fails
|
|
1325
|
+
express.on('payment_method_failed', ({ error }) => {
|
|
1326
|
+
console.error('Payment failed:', error);
|
|
1327
|
+
showErrorMessage('Payment could not be processed. Please try again.');
|
|
1328
|
+
});
|
|
1329
|
+
|
|
1330
|
+
// You RECEIVE: 'cancel' if the user dismisses the wallet sheet
|
|
1331
|
+
express.on('cancel', () => {
|
|
1332
|
+
console.log('User closed the wallet sheet');
|
|
1333
|
+
});
|
|
1334
|
+
|
|
1335
|
+
|
|
1336
|
+
// ─── Step 8: Mount ────────────────────────────────────────────────────────────
|
|
1337
|
+
// You CALL: mount() — renders the wallet buttons into the container
|
|
1338
|
+
express.mount('#express-checkout');
|
|
1339
|
+
// → 'ready' fires once buttons are visible
|
|
1340
|
+
|
|
1341
|
+
|
|
1342
|
+
// ─── Step 9: Cleanup ─────────────────────────────────────────────────────────
|
|
1343
|
+
// You CALL: destroy() when the component unmounts to prevent memory leaks
|
|
1344
|
+
// express.destroy();
|
|
1345
|
+
```
|
|
1346
|
+
|
|
1347
|
+
---
|
|
1348
|
+
|
|
1349
|
+
### Initialization
|
|
1350
|
+
|
|
1351
|
+
```typescript
|
|
1352
|
+
import { PaypercutExpressCheckout, ExpressSdkEvent } from '@paypercut/checkout-js';
|
|
1353
|
+
|
|
1354
|
+
const express = PaypercutExpressCheckout({
|
|
1355
|
+
publishableKey: 'pk_test_...',
|
|
1356
|
+
amount: 2999, // in minor units (€29.99)
|
|
1357
|
+
currency: 'EUR',
|
|
1358
|
+
countryCode: 'DE',
|
|
1359
|
+
shippingOptions: [
|
|
1360
|
+
{ id: 'standard', label: 'Standard Shipping', detail: '3–5 business days', amount: 499 },
|
|
1361
|
+
{ id: 'express', label: 'Express Shipping', detail: '1–2 business days', amount: 999 },
|
|
1362
|
+
],
|
|
1363
|
+
});
|
|
1364
|
+
|
|
1365
|
+
express.mount('#express-checkout');
|
|
1366
|
+
```
|
|
1367
|
+
|
|
1368
|
+
---
|
|
1369
|
+
|
|
1370
|
+
### Express Checkout Options
|
|
1371
|
+
|
|
1372
|
+
| Option | Type | Required | Description |
|
|
1373
|
+
|--------|------|----------|-------------|
|
|
1374
|
+
| `publishableKey` | `string` | Yes | Your Paypercut publishable API key (`pk_test_…` or `pk_live_…`) |
|
|
1375
|
+
| `amount` | `number` | Yes | Total amount in **minor units** (e.g. `1200` = €12.00) |
|
|
1376
|
+
| `currency` | `string` | Yes | ISO 4217 currency code (e.g. `'EUR'`, `'USD'`) |
|
|
1377
|
+
| `countryCode` | `string` | Yes | ISO 3166-1 alpha-2 merchant country code (e.g. `'DE'`). Required for Google Pay in production. |
|
|
1378
|
+
| `shippingOptions` | `ExpressCheckoutShippingOption[]` | Yes | Initial shipping options shown in the wallet sheet. Must include at least one. |
|
|
1379
|
+
| `lineItems` | `LineItem[]` | No | Line item breakdown shown in the **Apple Pay** sheet (subtotal, tax, etc.). Ignored by Google Pay. |
|
|
1380
|
+
| `walletOptions` | `('apple_pay' \| 'google_pay')[]` | No | Which wallets to show. Defaults to both. |
|
|
1381
|
+
| `layout` | `'column' \| 'row'` | No | `'row'` (default) places buttons side by side. `'column'` stacks them vertically. |
|
|
1382
|
+
| `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'`. |
|
|
1383
|
+
| `buttonOptions` | `ExpressButtonOptions` | No | Customize the label type and color/style of the wallet buttons. See [Button Options](#button-options) below. |
|
|
1384
|
+
|
|
1385
|
+
---
|
|
1386
|
+
|
|
1387
|
+
### Button Options
|
|
1388
|
+
|
|
1389
|
+
Control the label and appearance of the Apple Pay and Google Pay buttons via the `buttonOptions` object.
|
|
1390
|
+
|
|
1391
|
+
```typescript
|
|
1392
|
+
PaypercutExpressCheckout({
|
|
1393
|
+
// ...
|
|
1394
|
+
buttonOptions: {
|
|
1395
|
+
type: 'pay', // label shown on both buttons — defaults to 'buy'
|
|
1396
|
+
applePayStyle: 'black', // Apple Pay button color — defaults to 'black'
|
|
1397
|
+
googlePayColor: 'default', // Google Pay button color — defaults to 'default'
|
|
1398
|
+
borderRadius: '0.5rem', // border radius for both buttons — defaults to '0.5rem'
|
|
1399
|
+
},
|
|
1400
|
+
});
|
|
1401
|
+
```
|
|
1402
|
+
|
|
1403
|
+
#### `type` — applies to both Apple Pay and Google Pay
|
|
1404
|
+
|
|
1405
|
+
| Value | Button label |
|
|
1406
|
+
|-------|-------------|
|
|
1407
|
+
| `'plain'` *(default)* | Logo only (no text) |
|
|
1408
|
+
| `'pay'` | Pay with Apple Pay / Pay with Google Pay |
|
|
1409
|
+
| `'buy'` | Buy with Apple Pay / Buy with Google Pay |
|
|
1410
|
+
| `'donate'` | Donate with … |
|
|
1411
|
+
| `'checkout'` | Checkout with … |
|
|
1412
|
+
| `'subscribe'` | Subscribe with … |
|
|
1413
|
+
| `'book'` | Book with … |
|
|
1414
|
+
| `'order'` | Order with … |
|
|
1415
|
+
| `'tip'` | Tip with … |
|
|
1416
|
+
| `'contribute'` | Contribute with … |
|
|
1417
|
+
|
|
1418
|
+
#### `applePayStyle` — Apple Pay only
|
|
1419
|
+
|
|
1420
|
+
| Value | Appearance |
|
|
1421
|
+
|-------|-----------|
|
|
1422
|
+
| `'black'` *(default)* | Black background, white logo |
|
|
1423
|
+
| `'white'` | White background, black logo |
|
|
1424
|
+
| `'white-outline'` | White background with a black border, black logo |
|
|
1425
|
+
|
|
1426
|
+
#### `borderRadius` — applies to both
|
|
1427
|
+
|
|
1428
|
+
Any valid CSS value (e.g. `'0.5rem'`, `'8px'`, `'50%'`). Defaults to `'0.5rem'`.
|
|
1429
|
+
|
|
1430
|
+
#### `googlePayColor` — Google Pay only
|
|
1431
|
+
|
|
1432
|
+
| Value | Appearance |
|
|
1433
|
+
|-------|-----------|
|
|
1434
|
+
| `'default'` *(default)* | White background on light themes, dark on dark themes |
|
|
1435
|
+
| `'black'` | Black background |
|
|
1436
|
+
| `'white'` | White background |
|
|
1437
|
+
|
|
1438
|
+
```typescript
|
|
1439
|
+
interface ExpressCheckoutShippingOption {
|
|
1440
|
+
id: string; // unique identifier, e.g. 'standard'
|
|
1441
|
+
label: string; // display label, e.g. 'Standard Shipping'
|
|
1442
|
+
detail?: string; // subtitle, e.g. '3–5 business days'
|
|
1443
|
+
amount: number; // cost in minor units
|
|
1444
|
+
}
|
|
1445
|
+
|
|
1446
|
+
interface LineItem {
|
|
1447
|
+
label: string;
|
|
1448
|
+
amount: number; // minor units
|
|
1449
|
+
type?: 'final' | 'pending';
|
|
1450
|
+
}
|
|
1451
|
+
```
|
|
1452
|
+
|
|
1453
|
+
---
|
|
1454
|
+
|
|
1455
|
+
### Express Checkout Methods
|
|
1456
|
+
|
|
1457
|
+
#### `mount(container)`
|
|
1458
|
+
|
|
1459
|
+
Mounts the wallet buttons into the given container.
|
|
1460
|
+
|
|
1461
|
+
```typescript
|
|
1462
|
+
express.mount('#express-checkout');
|
|
1463
|
+
// or pass an HTMLElement
|
|
1464
|
+
express.mount(document.getElementById('express-checkout')!);
|
|
1465
|
+
```
|
|
1466
|
+
|
|
1467
|
+
#### `on(event, handler)`
|
|
1468
|
+
|
|
1469
|
+
Subscribes to an event. Returns an unsubscribe function.
|
|
1470
|
+
|
|
1471
|
+
```typescript
|
|
1472
|
+
const unsub = express.on('payment_method_created', (e) => { ... });
|
|
1473
|
+
unsub(); // unsubscribe
|
|
1474
|
+
```
|
|
1475
|
+
|
|
1476
|
+
#### `update(options)`
|
|
1477
|
+
|
|
1478
|
+
Updates the wallet sheet with new totals or shipping options. Call this from `shipping_address_change` / `shipping_option_change` handlers via the provided `updateWith()` helper.
|
|
1479
|
+
|
|
1480
|
+
```typescript
|
|
1481
|
+
express.update({
|
|
1482
|
+
amount: 3998,
|
|
1483
|
+
shippingOptions: [
|
|
1484
|
+
{ id: 'standard', label: 'Standard Shipping', amount: 499 },
|
|
1485
|
+
{ id: 'express', label: 'Express Shipping', amount: 999 },
|
|
1486
|
+
],
|
|
1487
|
+
});
|
|
1488
|
+
```
|
|
1489
|
+
|
|
1490
|
+
#### `destroy()`
|
|
1491
|
+
|
|
1492
|
+
Removes iframes and all event listeners.
|
|
1493
|
+
|
|
1494
|
+
```typescript
|
|
1495
|
+
express.destroy();
|
|
1496
|
+
```
|
|
1497
|
+
|
|
1498
|
+
---
|
|
1499
|
+
|
|
1500
|
+
### Express Checkout Events
|
|
1501
|
+
|
|
1502
|
+
| Event | Enum | Payload | Description |
|
|
1503
|
+
|-------|------|---------|-------------|
|
|
1504
|
+
| `ready` | `ExpressSdkEvent.Ready` | — | Wallet buttons are rendered and ready |
|
|
1505
|
+
| `click` | `ExpressSdkEvent.Click` | — | User tapped a wallet button |
|
|
1506
|
+
| `session_start` | `ExpressSdkEvent.SessionStart` | `ExpressSessionStartEvent` | Wallet sheet opened — **must call `updateWith()`** with initial options to unblock |
|
|
1507
|
+
| `shipping_address_change` | `ExpressSdkEvent.ShippingAddressChange` | `ShippingAddressChangeEvent` | User changed shipping address — must call `updateWith()` |
|
|
1508
|
+
| `shipping_option_change` | `ExpressSdkEvent.ShippingOptionChange` | `ShippingOptionChangeEvent` | User selected a different shipping option — must call `updateWith()` |
|
|
1509
|
+
| `payment_method_created` | `ExpressSdkEvent.PaymentMethodCreated` | `ExpressPaymentMethodCreatedEvent` | Payment method created — use `paymentMethodId` to confirm on backend |
|
|
1510
|
+
| `payment_method_failed` | `ExpressSdkEvent.PaymentMethodFailed` | `ExpressPaymentMethodFailedEvent` | Tokenization or payment method creation failed |
|
|
1511
|
+
| `cancel` | `ExpressSdkEvent.Cancel` | — | User dismissed the wallet sheet |
|
|
1512
|
+
| `error` | `ExpressSdkEvent.Error` | `Error` | Unrecoverable SDK error |
|
|
1513
|
+
|
|
1514
|
+
---
|
|
1515
|
+
|
|
1516
|
+
### Shipping Address & Option Changes
|
|
1517
|
+
|
|
1518
|
+
Shipping is **always collected** in Express Checkout. When the user selects or changes their address or shipping option inside the wallet sheet, the sheet is paused and waits for you to respond with updated totals. **You must call `updateWith()` within 30 seconds or the wallet sheet will show an error.**
|
|
1519
|
+
|
|
1520
|
+
#### `shipping_address_change`
|
|
1521
|
+
|
|
1522
|
+
Fires when the user picks or changes their shipping address. The address is partially anonymized at this stage (no street — only country, state, city, postal code).
|
|
1523
|
+
|
|
1524
|
+
```typescript
|
|
1525
|
+
express.on('shipping_address_change', ({ address, updateWith }) => {
|
|
1526
|
+
// address: { country, state?, city?, postalCode? }
|
|
1527
|
+
console.log('Shipping to:', address.country, address.postalCode);
|
|
1528
|
+
|
|
1529
|
+
// Calculate shipping cost for this address
|
|
1530
|
+
const shippingCost = address.country === 'DE' ? 299 : 599;
|
|
1531
|
+
const newTotal = 2500 + shippingCost;
|
|
1532
|
+
|
|
1533
|
+
// REQUIRED: call updateWith() to unblock the wallet sheet
|
|
1534
|
+
updateWith({
|
|
1535
|
+
amount: newTotal,
|
|
1536
|
+
shippingOptions: [
|
|
1537
|
+
{ id: 'standard', label: 'Standard Shipping', amount: shippingCost },
|
|
1538
|
+
{ id: 'express', label: 'Express Shipping', amount: shippingCost + 500 },
|
|
1539
|
+
],
|
|
1540
|
+
// Use 'invalid_shipping_address' if you don't ship to this address:
|
|
1541
|
+
// status: 'invalid_shipping_address',
|
|
1542
|
+
});
|
|
1543
|
+
});
|
|
1544
|
+
```
|
|
1545
|
+
|
|
1546
|
+
#### `shipping_option_change`
|
|
1547
|
+
|
|
1548
|
+
Fires when the user picks a different shipping option (e.g. switches from Standard to Express).
|
|
1549
|
+
|
|
1550
|
+
```typescript
|
|
1551
|
+
express.on('shipping_option_change', ({ shippingOption, updateWith }) => {
|
|
1552
|
+
// shippingOption: { id, label, detail?, amount }
|
|
1553
|
+
console.log('Shipping option changed to:', shippingOption.label, shippingOption.amount);
|
|
1554
|
+
|
|
1555
|
+
const newTotal = 2500 + shippingOption.amount;
|
|
1556
|
+
|
|
1557
|
+
// REQUIRED: call updateWith() to unblock the wallet sheet
|
|
1558
|
+
updateWith({
|
|
1559
|
+
amount: newTotal,
|
|
1560
|
+
// Optionally update Apple Pay line items to reflect the new shipping row:
|
|
1561
|
+
lineItems: [
|
|
1562
|
+
{ label: 'Subtotal', amount: 2500 },
|
|
1563
|
+
{ label: shippingOption.label, amount: shippingOption.amount },
|
|
1564
|
+
],
|
|
1565
|
+
});
|
|
1566
|
+
});
|
|
1567
|
+
```
|
|
1568
|
+
|
|
1569
|
+
#### `updateWith()` options
|
|
1570
|
+
|
|
1571
|
+
| Field | Type | Description |
|
|
1572
|
+
|-------|------|-------------|
|
|
1573
|
+
| `amount` | `number` | New total in minor units |
|
|
1574
|
+
| `shippingOptions` | `ExpressCheckoutShippingOption[]` | Updated shipping options list |
|
|
1575
|
+
| `lineItems` | `LineItem[]` | Updated Apple Pay line items (ignored by Google Pay) |
|
|
1576
|
+
| `status` | `'success' \| 'invalid_shipping_address' \| 'invalid_shipping_option'` | Use an invalid status to show an error inside the sheet without closing it |
|
|
1577
|
+
|
|
1578
|
+
---
|
|
1579
|
+
|
|
1580
|
+
### Restricting Shipping to Specific Countries / Addresses
|
|
1581
|
+
|
|
1582
|
+
Wallets don't accept a pre-defined list of allowed addresses — but you have two tools to control where you ship.
|
|
1583
|
+
|
|
1584
|
+
---
|
|
1585
|
+
|
|
1586
|
+
#### Option 1 — Country restriction (Google Pay only)
|
|
1587
|
+
|
|
1588
|
+
Google Pay lets you restrict which countries are selectable in the address picker. Users from other countries simply cannot choose an address. This is the cleanest UX — the restriction is enforced before the user even types anything.
|
|
1589
|
+
|
|
1590
|
+
This is controlled by passing `allowedCountries` in the SDK options:
|
|
1591
|
+
|
|
1592
|
+
```js
|
|
1593
|
+
const express = PaypercutExpressCheckout({
|
|
1594
|
+
publishableKey: 'pk_test_...',
|
|
1595
|
+
amount: 2999,
|
|
1596
|
+
currency: 'EUR',
|
|
1597
|
+
countryCode: 'DE',
|
|
1598
|
+
allowedCountries: ['DE', 'AT', 'CH'], // Google Pay only — user cannot select other countries
|
|
1599
|
+
shippingOptions: [ ... ],
|
|
1600
|
+
});
|
|
1601
|
+
```
|
|
1602
|
+
|
|
1603
|
+
> Apple Pay does not support pre-filtering by country. Users always see their saved addresses regardless of origin country.
|
|
1604
|
+
|
|
1605
|
+
---
|
|
1606
|
+
|
|
1607
|
+
#### Option 2 — Reject unsupported addresses at runtime (both wallets)
|
|
1608
|
+
|
|
1609
|
+
This works for both Apple Pay and Google Pay. When `shipping_address_change` fires, check the address against your supported regions. If you don't ship there, call `updateWith()` with `status: 'invalid_shipping_address'` — the sheet stays open and shows an error to the user without closing.
|
|
1610
|
+
|
|
1611
|
+
```js
|
|
1612
|
+
const SUPPORTED_COUNTRIES = ['DE', 'AT', 'CH', 'NL'];
|
|
1613
|
+
|
|
1614
|
+
express.on('shipping_address_change', ({ address, updateWith }) => {
|
|
1615
|
+
if (!SUPPORTED_COUNTRIES.includes(address.country)) {
|
|
1616
|
+
// Reject — sheet shows an error, stays open
|
|
1617
|
+
updateWith({ status: 'invalid_shipping_address' });
|
|
1618
|
+
return;
|
|
1619
|
+
}
|
|
1620
|
+
|
|
1621
|
+
// Country is supported — calculate shipping and respond
|
|
1622
|
+
const shippingCost = address.country === 'DE' ? 299 : 599;
|
|
1623
|
+
updateWith({
|
|
1624
|
+
amount: subtotal + shippingCost,
|
|
1625
|
+
shippingOptions: [
|
|
1626
|
+
{ id: 'standard', label: 'Standard Shipping', amount: shippingCost },
|
|
1627
|
+
{ id: 'express', label: 'Express Shipping', amount: shippingCost + 500 },
|
|
1628
|
+
],
|
|
1629
|
+
});
|
|
1630
|
+
});
|
|
1631
|
+
```
|
|
1632
|
+
|
|
1633
|
+
---
|
|
1634
|
+
|
|
1635
|
+
#### Option 3 — Combine both (recommended for Google Pay)
|
|
1636
|
+
|
|
1637
|
+
Use `allowedCountries` to prevent unsupported countries from being selectable upfront, **and** validate in `shipping_address_change` as a safety net:
|
|
1638
|
+
|
|
1639
|
+
```js
|
|
1640
|
+
const SUPPORTED_COUNTRIES = ['DE', 'AT', 'CH'];
|
|
1641
|
+
|
|
1642
|
+
const express = PaypercutExpressCheckout({
|
|
1643
|
+
publishableKey: 'pk_test_...',
|
|
1644
|
+
amount: 2999,
|
|
1645
|
+
currency: 'EUR',
|
|
1646
|
+
countryCode: 'DE',
|
|
1647
|
+
allowedCountries: SUPPORTED_COUNTRIES, // Google Pay: restricts picker
|
|
1648
|
+
shippingOptions: [ ... ],
|
|
1649
|
+
});
|
|
1650
|
+
|
|
1651
|
+
express.on('shipping_address_change', ({ address, updateWith }) => {
|
|
1652
|
+
// Apple Pay safety net — also catches any edge cases for Google Pay
|
|
1653
|
+
if (!SUPPORTED_COUNTRIES.includes(address.country)) {
|
|
1654
|
+
updateWith({ status: 'invalid_shipping_address' });
|
|
1655
|
+
return;
|
|
1656
|
+
}
|
|
1657
|
+
|
|
1658
|
+
const shippingCost = address.country === 'DE' ? 299 : 599;
|
|
1659
|
+
updateWith({
|
|
1660
|
+
amount: 2999 + shippingCost,
|
|
1661
|
+
shippingOptions: [
|
|
1662
|
+
{ id: 'standard', label: 'Standard Shipping', amount: shippingCost },
|
|
1663
|
+
],
|
|
1664
|
+
});
|
|
1665
|
+
});
|
|
1666
|
+
```
|
|
1667
|
+
|
|
1668
|
+
---
|
|
1669
|
+
|
|
1670
|
+
#### Summary
|
|
1671
|
+
|
|
1672
|
+
| Approach | Apple Pay | Google Pay | UX |
|
|
1673
|
+
|----------|-----------|------------|-----|
|
|
1674
|
+
| `allowedCountries` in options | ✗ not supported | ✅ restricts picker | Best — error before user interacts |
|
|
1675
|
+
| `status: 'invalid_shipping_address'` in `shipping_address_change` | ✅ | ✅ | Sheet shows inline error, stays open |
|
|
1676
|
+
| Both combined | ✅ (runtime only) | ✅ (picker + runtime) | Recommended |
|
|
1677
|
+
|
|
1678
|
+
---
|
|
1679
|
+
|
|
1680
|
+
## Express Checkout — Integration Examples
|
|
1681
|
+
|
|
1682
|
+
Three real-world scenarios showing the complete integration from init to payment confirmation.
|
|
1683
|
+
|
|
1684
|
+
---
|
|
1685
|
+
|
|
1686
|
+
### Example 1 — Simple: static shipping options, EU-only (Google Pay + Apple Pay)
|
|
1687
|
+
|
|
1688
|
+
Best for merchants with fixed shipping rates that don't change by address. Google Pay restricts the picker to EU countries. Apple Pay rejects other countries at runtime. Both wallets share the same event handlers.
|
|
1689
|
+
|
|
1690
|
+
```js
|
|
1691
|
+
const SUPPORTED_COUNTRIES = ['DE', 'AT', 'CH', 'NL', 'FR'];
|
|
1692
|
+
const SUBTOTAL = 4900; // €49.00
|
|
1693
|
+
|
|
1694
|
+
const express = PaypercutExpressCheckout({
|
|
1695
|
+
publishableKey: 'pk_live_...',
|
|
1696
|
+
amount: SUBTOTAL + 499, // subtotal + default shipping
|
|
1697
|
+
currency: 'EUR',
|
|
1698
|
+
countryCode: 'DE',
|
|
1699
|
+
allowedCountries: SUPPORTED_COUNTRIES, // Google Pay: restricts picker to these countries
|
|
1700
|
+
});
|
|
1701
|
+
|
|
1702
|
+
// Step 1 — Provide initial shipping options when wallet sheet opens
|
|
1703
|
+
express.on('session_start', ({ wallet, updateWith }) => {
|
|
1704
|
+
updateWith({
|
|
1705
|
+
amount: SUBTOTAL + 499,
|
|
1706
|
+
shippingOptions: [
|
|
1707
|
+
{ id: 'standard', label: 'Standard Shipping', detail: '3–5 days', amount: 499 },
|
|
1708
|
+
{ id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
|
|
1709
|
+
],
|
|
1710
|
+
lineItems: [
|
|
1711
|
+
{ label: 'Subtotal', amount: SUBTOTAL },
|
|
1712
|
+
{ label: 'Standard Shipping', amount: 499 },
|
|
1713
|
+
],
|
|
1714
|
+
});
|
|
1715
|
+
});
|
|
1716
|
+
|
|
1717
|
+
// Step 2 — Validate address (Apple Pay: only way to restrict countries)
|
|
1718
|
+
express.on('shipping_address_change', ({ address, updateWith }) => {
|
|
1719
|
+
if (!SUPPORTED_COUNTRIES.includes(address.country)) {
|
|
1720
|
+
updateWith({ status: 'invalid_shipping_address' });
|
|
1721
|
+
return;
|
|
1722
|
+
}
|
|
1723
|
+
|
|
1724
|
+
updateWith({
|
|
1725
|
+
amount: SUBTOTAL + 499,
|
|
1726
|
+
shippingOptions: [
|
|
1727
|
+
{ id: 'standard', label: 'Standard Shipping', detail: '3–5 days', amount: 499 },
|
|
1728
|
+
{ id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
|
|
1729
|
+
],
|
|
1730
|
+
lineItems: [
|
|
1731
|
+
{ label: 'Subtotal', amount: SUBTOTAL },
|
|
1732
|
+
{ label: 'Standard Shipping', amount: 499 },
|
|
1733
|
+
],
|
|
1734
|
+
});
|
|
1735
|
+
});
|
|
1736
|
+
|
|
1737
|
+
// Step 3 — Update total when user picks a different shipping option
|
|
1738
|
+
express.on('shipping_option_change', ({ shippingOption, updateWith }) => {
|
|
1739
|
+
updateWith({
|
|
1740
|
+
amount: SUBTOTAL + shippingOption.amount,
|
|
1741
|
+
lineItems: [
|
|
1742
|
+
{ label: 'Subtotal', amount: SUBTOTAL },
|
|
1743
|
+
{ label: shippingOption.label, amount: shippingOption.amount },
|
|
1744
|
+
],
|
|
1745
|
+
});
|
|
1746
|
+
});
|
|
1747
|
+
|
|
1748
|
+
// Step 4 — Payment method created, confirm on your backend
|
|
1749
|
+
express.on('payment_method_created', async ({ paymentMethodId, idempotencyKey, shippingDetails, selectedShippingOption }) => {
|
|
1750
|
+
await fetch('/api/orders', {
|
|
1751
|
+
method: 'POST',
|
|
1752
|
+
headers: { 'Content-Type': 'application/json' },
|
|
1753
|
+
body: JSON.stringify({
|
|
1754
|
+
paymentMethodId,
|
|
1755
|
+
idempotencyKey,
|
|
1756
|
+
shippingAddress: shippingDetails?.address,
|
|
1757
|
+
shippingOption: selectedShippingOption?.id,
|
|
1758
|
+
}),
|
|
1759
|
+
});
|
|
1760
|
+
window.location.href = '/order/confirmation';
|
|
1761
|
+
});
|
|
1762
|
+
|
|
1763
|
+
express.on('shipping_options_required', ({ wallet }) => {
|
|
1764
|
+
console.error(`${wallet}: session_start timed out — shipping options were not provided`);
|
|
1765
|
+
});
|
|
1766
|
+
|
|
1767
|
+
express.on('payment_method_failed', ({ error }) => console.error('Payment failed:', error));
|
|
1768
|
+
express.on('cancel', () => console.log('User cancelled'));
|
|
1769
|
+
|
|
1770
|
+
express.mount('#express-checkout');
|
|
1771
|
+
```
|
|
1772
|
+
|
|
1773
|
+
---
|
|
1774
|
+
|
|
1775
|
+
### Example 2 — Dynamic: shipping cost calculated from address via backend (Google Pay + Apple Pay)
|
|
1776
|
+
|
|
1777
|
+
Best for merchants with zone-based pricing loaded from their own API. Shipping cost is unknown until the user's country/postal code is available.
|
|
1778
|
+
|
|
1779
|
+
```js
|
|
1780
|
+
const SUBTOTAL = 7500; // €75.00
|
|
1781
|
+
|
|
1782
|
+
const express = PaypercutExpressCheckout({
|
|
1783
|
+
publishableKey: 'pk_live_...',
|
|
1784
|
+
amount: SUBTOTAL, // no shipping added yet — will be set in session_start
|
|
1785
|
+
currency: 'EUR',
|
|
1786
|
+
countryCode: 'DE',
|
|
1787
|
+
allowedCountries: ['DE', 'AT', 'CH', 'NL', 'BE', 'FR', 'IT', 'ES'],
|
|
1788
|
+
});
|
|
1789
|
+
|
|
1790
|
+
// Step 1 — Fetch initial options from your API before the sheet opens
|
|
1791
|
+
express.on('session_start', async ({ wallet, updateWith }) => {
|
|
1792
|
+
// Call your backend — you have 3 seconds
|
|
1793
|
+
const { options, defaultAmount } = await fetch('/api/shipping/default').then(r => r.json());
|
|
1794
|
+
// e.g. { options: [{ id: 'standard', label: 'Standard', amount: 599 }], defaultAmount: 8099 }
|
|
1795
|
+
|
|
1796
|
+
updateWith({
|
|
1797
|
+
amount: defaultAmount,
|
|
1798
|
+
shippingOptions: options,
|
|
1799
|
+
lineItems: [
|
|
1800
|
+
{ label: 'Subtotal', amount: SUBTOTAL },
|
|
1801
|
+
{ label: options[0].label, amount: options[0].amount },
|
|
1802
|
+
],
|
|
1803
|
+
});
|
|
1804
|
+
});
|
|
1805
|
+
|
|
1806
|
+
// Step 2 — Recalculate when user changes address
|
|
1807
|
+
express.on('shipping_address_change', async ({ address, updateWith }) => {
|
|
1808
|
+
const res = await fetch('/api/shipping/calculate', {
|
|
1809
|
+
method: 'POST',
|
|
1810
|
+
headers: { 'Content-Type': 'application/json' },
|
|
1811
|
+
body: JSON.stringify({ country: address.country, postalCode: address.postalCode }),
|
|
1812
|
+
});
|
|
1813
|
+
|
|
1814
|
+
if (!res.ok) {
|
|
1815
|
+
// Country not supported or no shipping available
|
|
1816
|
+
updateWith({ status: 'invalid_shipping_address' });
|
|
1817
|
+
return;
|
|
1818
|
+
}
|
|
1819
|
+
|
|
1820
|
+
const { options, total } = await res.json();
|
|
1821
|
+
// e.g. { options: [{ id: 'standard', amount: 699 }, { id: 'express', amount: 1199 }], total: 8199 }
|
|
1822
|
+
|
|
1823
|
+
updateWith({
|
|
1824
|
+
amount: total,
|
|
1825
|
+
shippingOptions: options,
|
|
1826
|
+
lineItems: [
|
|
1827
|
+
{ label: 'Subtotal', amount: SUBTOTAL },
|
|
1828
|
+
{ label: options[0].label, amount: options[0].amount },
|
|
1829
|
+
],
|
|
1830
|
+
});
|
|
1831
|
+
});
|
|
1832
|
+
|
|
1833
|
+
// Step 3 — User switches shipping option
|
|
1834
|
+
express.on('shipping_option_change', ({ shippingOption, updateWith }) => {
|
|
1835
|
+
updateWith({
|
|
1836
|
+
amount: SUBTOTAL + shippingOption.amount,
|
|
1837
|
+
lineItems: [
|
|
1838
|
+
{ label: 'Subtotal', amount: SUBTOTAL },
|
|
1839
|
+
{ label: shippingOption.label, amount: shippingOption.amount },
|
|
1840
|
+
],
|
|
1841
|
+
});
|
|
1842
|
+
});
|
|
1843
|
+
|
|
1844
|
+
// Step 4 — Create order on backend
|
|
1845
|
+
express.on('payment_method_created', async ({ paymentMethodId, idempotencyKey, billingDetails, shippingDetails, selectedShippingOption }) => {
|
|
1846
|
+
const res = await fetch('/api/orders', {
|
|
1847
|
+
method: 'POST',
|
|
1848
|
+
headers: { 'Content-Type': 'application/json' },
|
|
1849
|
+
body: JSON.stringify({
|
|
1850
|
+
paymentMethodId,
|
|
1851
|
+
idempotencyKey,
|
|
1852
|
+
billing: billingDetails,
|
|
1853
|
+
shipping: shippingDetails,
|
|
1854
|
+
shippingOptionId: selectedShippingOption?.id,
|
|
1855
|
+
}),
|
|
1856
|
+
});
|
|
1857
|
+
const { orderId } = await res.json();
|
|
1858
|
+
window.location.href = `/orders/${orderId}/confirmation`;
|
|
1859
|
+
});
|
|
1860
|
+
|
|
1861
|
+
express.on('shipping_options_required', ({ wallet }) => {
|
|
1862
|
+
alert(`Could not load shipping options for ${wallet}. Please try again.`);
|
|
1863
|
+
});
|
|
1864
|
+
|
|
1865
|
+
express.on('payment_method_failed', ({ error }) => alert('Payment failed: ' + error));
|
|
1866
|
+
express.on('cancel', () => console.log('User cancelled'));
|
|
1867
|
+
|
|
1868
|
+
express.mount('#express-checkout');
|
|
1869
|
+
```
|
|
1870
|
+
|
|
1871
|
+
---
|
|
1872
|
+
|
|
1873
|
+
### Example 3 — React: Express Checkout as a component with dynamic options
|
|
1874
|
+
|
|
1875
|
+
```tsx
|
|
1876
|
+
import { useEffect, useRef } from 'react';
|
|
1877
|
+
import {
|
|
1878
|
+
PaypercutExpressCheckout,
|
|
1879
|
+
ExpressSdkEvent,
|
|
1880
|
+
type ExpressCheckoutInstance,
|
|
1881
|
+
} from '@paypercut/checkout-js';
|
|
1882
|
+
|
|
1883
|
+
interface Props {
|
|
1884
|
+
subtotal: number; // minor units
|
|
1885
|
+
onSuccess: (orderId: string) => void;
|
|
1886
|
+
onCancel: () => void;
|
|
1887
|
+
}
|
|
1888
|
+
|
|
1889
|
+
const SUPPORTED_COUNTRIES = ['DE', 'AT', 'CH', 'NL'];
|
|
1890
|
+
|
|
1891
|
+
export function ExpressCheckout({ subtotal, onSuccess, onCancel }: Props) {
|
|
1892
|
+
const containerRef = useRef<HTMLDivElement>(null);
|
|
1893
|
+
const instanceRef = useRef<ExpressCheckoutInstance | null>(null);
|
|
1894
|
+
|
|
1895
|
+
useEffect(() => {
|
|
1896
|
+
if (!containerRef.current) return;
|
|
1897
|
+
|
|
1898
|
+
const express = PaypercutExpressCheckout({
|
|
1899
|
+
publishableKey: process.env.NEXT_PUBLIC_PAYPERCUT_KEY!,
|
|
1900
|
+
amount: subtotal,
|
|
1901
|
+
currency: 'EUR',
|
|
1902
|
+
countryCode: 'DE',
|
|
1903
|
+
allowedCountries: SUPPORTED_COUNTRIES,
|
|
1904
|
+
});
|
|
1905
|
+
|
|
1906
|
+
// Provide initial options before sheet opens
|
|
1907
|
+
express.on(ExpressSdkEvent.SessionStart, async ({ wallet, updateWith }) => {
|
|
1908
|
+
const { options } = await fetch('/api/shipping/default').then(r => r.json());
|
|
1909
|
+
updateWith({
|
|
1910
|
+
amount: subtotal + options[0].amount,
|
|
1911
|
+
shippingOptions: options,
|
|
1912
|
+
lineItems: [
|
|
1913
|
+
{ label: 'Subtotal', amount: subtotal },
|
|
1914
|
+
{ label: options[0].label, amount: options[0].amount },
|
|
1915
|
+
],
|
|
1916
|
+
});
|
|
1917
|
+
});
|
|
1918
|
+
|
|
1919
|
+
// Recalculate when address changes
|
|
1920
|
+
express.on(ExpressSdkEvent.ShippingAddressChange, async ({ address, updateWith }) => {
|
|
1921
|
+
if (!SUPPORTED_COUNTRIES.includes(address.country)) {
|
|
1922
|
+
updateWith({ status: 'invalid_shipping_address' });
|
|
1923
|
+
return;
|
|
1924
|
+
}
|
|
1925
|
+
const { options, total } = await fetch('/api/shipping/calculate', {
|
|
1926
|
+
method: 'POST',
|
|
1927
|
+
headers: { 'Content-Type': 'application/json' },
|
|
1928
|
+
body: JSON.stringify({ country: address.country, postalCode: address.postalCode }),
|
|
1929
|
+
}).then(r => r.json());
|
|
1930
|
+
|
|
1931
|
+
updateWith({
|
|
1932
|
+
amount: total,
|
|
1933
|
+
shippingOptions: options,
|
|
1934
|
+
lineItems: [
|
|
1935
|
+
{ label: 'Subtotal', amount: subtotal },
|
|
1936
|
+
{ label: options[0].label, amount: options[0].amount },
|
|
1937
|
+
],
|
|
1938
|
+
});
|
|
1939
|
+
});
|
|
1940
|
+
|
|
1941
|
+
// Update total when shipping option changes
|
|
1942
|
+
express.on(ExpressSdkEvent.ShippingOptionChange, ({ shippingOption, updateWith }) => {
|
|
1943
|
+
updateWith({
|
|
1944
|
+
amount: subtotal + shippingOption.amount,
|
|
1945
|
+
lineItems: [
|
|
1946
|
+
{ label: 'Subtotal', amount: subtotal },
|
|
1947
|
+
{ label: shippingOption.label, amount: shippingOption.amount },
|
|
1948
|
+
],
|
|
1949
|
+
});
|
|
1950
|
+
});
|
|
1951
|
+
|
|
1952
|
+
// Payment method ready — confirm on backend
|
|
1953
|
+
express.on(ExpressSdkEvent.PaymentMethodCreated, async ({ paymentMethodId, idempotencyKey, shippingDetails, selectedShippingOption }) => {
|
|
1954
|
+
const { orderId } = await fetch('/api/orders', {
|
|
1955
|
+
method: 'POST',
|
|
1956
|
+
headers: { 'Content-Type': 'application/json' },
|
|
1957
|
+
body: JSON.stringify({
|
|
1958
|
+
paymentMethodId,
|
|
1959
|
+
idempotencyKey,
|
|
1960
|
+
shipping: shippingDetails,
|
|
1961
|
+
shippingOptionId: selectedShippingOption?.id,
|
|
1962
|
+
}),
|
|
1963
|
+
}).then(r => r.json());
|
|
1964
|
+
|
|
1965
|
+
onSuccess(orderId);
|
|
1966
|
+
});
|
|
1967
|
+
|
|
1968
|
+
express.on(ExpressSdkEvent.ShippingOptionsRequired, ({ wallet }) => {
|
|
1969
|
+
console.error(`${wallet}: session_start timed out — implement the session_start handler`);
|
|
1970
|
+
});
|
|
1971
|
+
|
|
1972
|
+
express.on(ExpressSdkEvent.PaymentMethodFailed, ({ error }) => console.error('Payment failed:', error));
|
|
1973
|
+
express.on(ExpressSdkEvent.Cancel, onCancel);
|
|
1974
|
+
|
|
1975
|
+
express.mount(containerRef.current);
|
|
1976
|
+
instanceRef.current = express;
|
|
1977
|
+
|
|
1978
|
+
return () => {
|
|
1979
|
+
instanceRef.current?.destroy();
|
|
1980
|
+
instanceRef.current = null;
|
|
1981
|
+
};
|
|
1982
|
+
}, [subtotal, onSuccess, onCancel]);
|
|
1983
|
+
|
|
1984
|
+
return <div ref={containerRef} style={{ width: '100%' }} />;
|
|
1985
|
+
}
|
|
1986
|
+
```
|
|
1987
|
+
|
|
1988
|
+
---
|
|
1989
|
+
|
|
1990
|
+
### `payment_method_created` Event
|
|
1991
|
+
|
|
1992
|
+
Fires after the user authorizes payment and the SDK has successfully created a Paypercut payment method. Use the `paymentMethodId` to create and confirm a payment intent on your backend.
|
|
1993
|
+
|
|
1994
|
+
```typescript
|
|
1995
|
+
express.on('payment_method_created', (event) => {
|
|
1996
|
+
// event.paymentMethodId — Paypercut PM ID (pm_xxx), use this to confirm payment on your backend
|
|
1997
|
+
// event.token — { id: string, type: 'apple_pay' | 'google_pay' }
|
|
1998
|
+
// event.idempotencyKey — unique key for this payment attempt (pass to your backend)
|
|
1999
|
+
// event.billingDetails — { name?, email?, address? }
|
|
2000
|
+
// event.shippingDetails — { name?, address? }
|
|
2001
|
+
// event.selectedShippingOption — { id, label, amount }
|
|
2002
|
+
|
|
2003
|
+
console.log('Payment method created:', event.paymentMethodId);
|
|
2004
|
+
console.log('Shipping to:', event.shippingDetails?.address);
|
|
2005
|
+
console.log('Selected option:', event.selectedShippingOption?.label);
|
|
2006
|
+
|
|
2007
|
+
// Call your backend to create + confirm the payment intent
|
|
2008
|
+
await fetch('/api/confirm-payment', {
|
|
2009
|
+
method: 'POST',
|
|
2010
|
+
body: JSON.stringify({
|
|
2011
|
+
paymentMethodId: event.paymentMethodId,
|
|
2012
|
+
idempotencyKey: event.idempotencyKey,
|
|
2013
|
+
}),
|
|
2014
|
+
});
|
|
2015
|
+
});
|
|
2016
|
+
```
|
|
2017
|
+
|
|
2018
|
+
```typescript
|
|
2019
|
+
interface ExpressPaymentMethodCreatedEvent {
|
|
2020
|
+
paymentMethodId: string; // Paypercut PM ID (pm_xxx)
|
|
2021
|
+
token: { id: string; type: 'apple_pay' | 'google_pay' };
|
|
2022
|
+
idempotencyKey: string;
|
|
2023
|
+
billingDetails?: {
|
|
2024
|
+
name?: string;
|
|
2025
|
+
email?: string;
|
|
2026
|
+
phone?: string;
|
|
2027
|
+
address?: { line1?: string; line2?: string; city?: string; state?: string; postalCode?: string; country?: string };
|
|
2028
|
+
};
|
|
2029
|
+
shippingDetails?: {
|
|
2030
|
+
name?: string;
|
|
2031
|
+
address?: { line1?: string; line2?: string; city?: string; state?: string; postalCode?: string; country?: string };
|
|
2032
|
+
};
|
|
2033
|
+
selectedShippingOption?: { id: string; label: string; detail?: string; amount: number };
|
|
2034
|
+
}
|
|
2035
|
+
```
|
|
2036
|
+
|
|
2037
|
+
---
|
|
2038
|
+
|
|
2039
|
+
### Express Checkout Full Example
|
|
2040
|
+
|
|
2041
|
+
```html
|
|
2042
|
+
<!DOCTYPE html>
|
|
2043
|
+
<html>
|
|
2044
|
+
<head><title>Express Checkout</title></head>
|
|
2045
|
+
<body>
|
|
2046
|
+
<div id="express-checkout" style="max-width: 400px;"></div>
|
|
2047
|
+
|
|
2048
|
+
<script src="https://cdn.jsdelivr.net/npm/@paypercut/checkout-js/dist/paypercut-checkout.iife.min.js"></script>
|
|
2049
|
+
<script>
|
|
2050
|
+
const express = PaypercutExpressCheckout({
|
|
2051
|
+
publishableKey: 'pk_test_...',
|
|
2052
|
+
amount: 2500,
|
|
2053
|
+
currency: 'EUR',
|
|
2054
|
+
countryCode: 'DE',
|
|
2055
|
+
shippingOptions: [
|
|
2056
|
+
{ id: 'standard', label: 'Standard Shipping', detail: '3–5 days', amount: 499 },
|
|
2057
|
+
{ id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
|
|
2058
|
+
],
|
|
2059
|
+
lineItems: [
|
|
2060
|
+
{ label: 'Subtotal', amount: 2500 },
|
|
2061
|
+
{ label: 'Standard Shipping', amount: 499 },
|
|
2062
|
+
],
|
|
2063
|
+
});
|
|
2064
|
+
|
|
2065
|
+
// Wallet buttons ready
|
|
2066
|
+
express.on('ready', () => console.log('Express Checkout ready'));
|
|
2067
|
+
|
|
2068
|
+
// Shipping address changed — recalculate and respond
|
|
2069
|
+
express.on('shipping_address_change', ({ address, updateWith }) => {
|
|
2070
|
+
const shippingCost = address.country === 'DE' ? 499 : 799;
|
|
2071
|
+
updateWith({
|
|
2072
|
+
amount: 2500 + shippingCost,
|
|
2073
|
+
shippingOptions: [
|
|
2074
|
+
{ id: 'standard', label: 'Standard Shipping', amount: shippingCost },
|
|
2075
|
+
{ id: 'express', label: 'Express Shipping', amount: shippingCost + 500 },
|
|
2076
|
+
],
|
|
2077
|
+
lineItems: [
|
|
2078
|
+
{ label: 'Subtotal', amount: 2500 },
|
|
2079
|
+
{ label: 'Standard Shipping', amount: shippingCost },
|
|
2080
|
+
],
|
|
2081
|
+
});
|
|
2082
|
+
});
|
|
2083
|
+
|
|
2084
|
+
// Shipping option changed — update total
|
|
2085
|
+
express.on('shipping_option_change', ({ shippingOption, updateWith }) => {
|
|
2086
|
+
updateWith({
|
|
2087
|
+
amount: 2500 + shippingOption.amount,
|
|
2088
|
+
lineItems: [
|
|
2089
|
+
{ label: 'Subtotal', amount: 2500 },
|
|
2090
|
+
{ label: shippingOption.label, amount: shippingOption.amount },
|
|
2091
|
+
],
|
|
2092
|
+
});
|
|
2093
|
+
});
|
|
2094
|
+
|
|
2095
|
+
// Payment method created — confirm on backend
|
|
2096
|
+
express.on('payment_method_created', async (event) => {
|
|
2097
|
+
console.log('Payment method:', event.paymentMethodId);
|
|
2098
|
+
console.log('Shipping option:', event.selectedShippingOption?.label);
|
|
2099
|
+
await fetch('/api/confirm-payment', {
|
|
2100
|
+
method: 'POST',
|
|
2101
|
+
headers: { 'Content-Type': 'application/json' },
|
|
2102
|
+
body: JSON.stringify({ paymentMethodId: event.paymentMethodId }),
|
|
2103
|
+
});
|
|
2104
|
+
window.location.href = '/success';
|
|
2105
|
+
});
|
|
2106
|
+
|
|
2107
|
+
express.on('payment_method_failed', ({ error }) => {
|
|
2108
|
+
console.error('Payment failed:', error);
|
|
2109
|
+
});
|
|
2110
|
+
|
|
2111
|
+
express.on('cancel', () => {
|
|
2112
|
+
console.log('User dismissed the wallet sheet');
|
|
2113
|
+
});
|
|
2114
|
+
|
|
2115
|
+
express.mount('#express-checkout');
|
|
2116
|
+
</script>
|
|
2117
|
+
</body>
|
|
2118
|
+
</html>
|
|
2119
|
+
```
|
|
2120
|
+
|
|
2121
|
+
---
|
|
2122
|
+
|
|
2123
|
+
### Express Checkout React Example
|
|
2124
|
+
|
|
2125
|
+
```tsx
|
|
2126
|
+
import { useEffect, useRef } from 'react';
|
|
2127
|
+
import { PaypercutExpressCheckout, ExpressSdkEvent, ExpressCheckoutInstance } from '@paypercut/checkout-js';
|
|
2128
|
+
|
|
2129
|
+
interface Props {
|
|
2130
|
+
subtotal: number; // minor units
|
|
2131
|
+
onSuccess: (paymentMethodId: string) => void;
|
|
2132
|
+
}
|
|
2133
|
+
|
|
2134
|
+
export function ExpressCheckoutButton({ subtotal, onSuccess }: Props) {
|
|
2135
|
+
const containerRef = useRef<HTMLDivElement>(null);
|
|
2136
|
+
const instanceRef = useRef<ExpressCheckoutInstance | null>(null);
|
|
2137
|
+
|
|
2138
|
+
useEffect(() => {
|
|
2139
|
+
if (!containerRef.current) return;
|
|
2140
|
+
|
|
2141
|
+
const express = PaypercutExpressCheckout({
|
|
2142
|
+
publishableKey: process.env.NEXT_PUBLIC_PAYPERCUT_KEY!,
|
|
2143
|
+
amount: subtotal + 499, // subtotal + default shipping
|
|
2144
|
+
currency: 'EUR',
|
|
2145
|
+
countryCode: 'DE',
|
|
2146
|
+
shippingOptions: [
|
|
2147
|
+
{ id: 'standard', label: 'Standard Shipping', detail: '3–5 days', amount: 499 },
|
|
2148
|
+
{ id: 'express', label: 'Express Shipping', detail: '1–2 days', amount: 999 },
|
|
2149
|
+
],
|
|
2150
|
+
});
|
|
2151
|
+
|
|
2152
|
+
express.on(ExpressSdkEvent.ShippingAddressChange, ({ address, updateWith }) => {
|
|
2153
|
+
const shipping = address.country === 'DE' ? 499 : 799;
|
|
2154
|
+
updateWith({
|
|
2155
|
+
amount: subtotal + shipping,
|
|
2156
|
+
shippingOptions: [
|
|
2157
|
+
{ id: 'standard', label: 'Standard Shipping', amount: shipping },
|
|
2158
|
+
{ id: 'express', label: 'Express Shipping', amount: shipping + 500 },
|
|
2159
|
+
],
|
|
2160
|
+
});
|
|
2161
|
+
});
|
|
2162
|
+
|
|
2163
|
+
express.on(ExpressSdkEvent.ShippingOptionChange, ({ shippingOption, updateWith }) => {
|
|
2164
|
+
updateWith({ amount: subtotal + shippingOption.amount });
|
|
2165
|
+
});
|
|
2166
|
+
|
|
2167
|
+
express.on(ExpressSdkEvent.PaymentMethodCreated, (event) => {
|
|
2168
|
+
onSuccess(event.paymentMethodId);
|
|
2169
|
+
});
|
|
2170
|
+
|
|
2171
|
+
express.on(ExpressSdkEvent.PaymentMethodFailed, ({ error }) => {
|
|
2172
|
+
console.error('Express payment failed:', error);
|
|
2173
|
+
});
|
|
2174
|
+
|
|
2175
|
+
express.mount(containerRef.current);
|
|
2176
|
+
instanceRef.current = express;
|
|
2177
|
+
|
|
2178
|
+
return () => {
|
|
2179
|
+
instanceRef.current?.destroy();
|
|
2180
|
+
instanceRef.current = null;
|
|
2181
|
+
};
|
|
2182
|
+
}, [subtotal, onSuccess]);
|
|
2183
|
+
|
|
2184
|
+
return <div ref={containerRef} style={{ width: '100%' }} />;
|
|
2185
|
+
}
|
|
2186
|
+
```
|
|
2187
|
+
|
|
2188
|
+
---
|
|
2189
|
+
|
|
1153
2190
|
## FAQ For Internal Validation
|
|
1154
2191
|
|
|
1155
2192
|
**Q: How do I handle successful payments?**
|