TypeScript escrow checkout wrapper with built-in script loader and session creation, ready for React/Next.js
npm install payluk-escrow-inline-checkoutbash
npm i payluk-escrow-inline-checkout
`
Quick Start (Vanilla JS/TS)
`ts
// app.ts
import { initEscrowCheckout, pay } from 'payluk-escrow-inline-checkout';
// 1) Initialize once at app startup
initEscrowCheckout({
publicKey: '' // publishable key only
});
// 2) Trigger a payment flow (e.g., on a button click)
async function onPayClick() {
try {
await pay({
paymentToken: '',
reference: '',
redirectUrl: 'https://your-app.example.com/checkout/complete',
logoUrl: 'https://mediacloud.me/media/W8HU9TK245QF528ZULCFSJXX2SBBLT.jpg', // optional
brand: 'YourBrand', // optional
customerId: 'YourBrand', // optional only for merchants using customer vaulting
callback: (result) => {
console.log('Checkout result:', result);
},
onClose: () => {
console.log('Widget closed');
}
});
} catch (err) {
console.error('Payment failed:', err);
}
}
`
Inline Usage
`html
Checkout Demo
Checkout Demo
`
React Usage
`tsx
import { initEscrowCheckout } from 'payluk-escrow-inline-checkout';
export default function ClientEscrowInit() {
useEffect(() => {
initEscrowCheckout({
publicKey: 'pk_live_*',
});
}, []);
return null;
}
`
`tsx
export default function RootLayout({ children }: Readonly<{children: React.ReactNode}>) {
return (
${geistSans.variable} ${geistMono.variable} antialiased}>
{children}
);
}
`
`tsx
import React from 'react';
import { useEscrowCheckout } from 'payluk-escrow-inline-checkout/react';
export function CheckoutButton() {
const { pay } = useEscrowCheckout();
const handleClick = async () => {
try {
await pay({
paymentToken: '',
reference: '',
redirectUrl: 'https://your-app.example.com/checkout/complete',
logoUrl: 'https://mediacloud.me/media/W8HU9TK245QF528ZULCFSJXX2SBBLT.jpg',
brand: 'YourBrand',
extra: { theme: 'light' },
customerId: 'YourBrand', // optional only for merchants using customer vaulting
callback: (result) => console.log(result)
});
} catch {
// error is also exposed via error state
}
};
return (
);
}
`
Note: In React apps, call initEscrowCheckout(...) once in your app bootstrap (e.g., in the root component or an app initializer). The hook uses that configuration.
Important:
- Only use publishable keys in the browser. Keep any secret keys on your server.
- Validate inputs on your backend and return the required session payload.
API
$3
Initializes the SDK. Must be called before any pay(...).
Required:
- publicKey: string — publishable key only
Advanced (optional):
- scriptUrlOverride?: string — custom widget script URL
- globalName?: string — custom global widget function name
- crossOrigin?: '' | 'anonymous' | 'use-credentials' — script tag crossOrigin
Example:
`ts
import { initEscrowCheckout } from 'payluk-escrow-inline-checkout';
initEscrowCheckout({
publicKey: ''
});
`
$3
Creates a checkout session via your backend and opens the widget.
Required:
- paymentToken: string
- reference: string
- redirectUrl: string
Optional:
- logoUrl?: string
- customerId?: string — only for merchants using customer vaulting
- brand?: string
- callback?: (result: unknown) => void
- onClose?: () => void
Returns:
- Promise that resolves when the widget is opened (and rejects on errors).
$3
React hook that exposes:
- ready: boolean — becomes true after a successful load/pay attempt
- loading: boolean — true while pay is running
- error: Error | null — last error encountered
- pay: same function as pay(...)
Import:
`ts
import { useEscrowCheckout } from 'payluk-escrow-inline-checkout/react';
`
Framework and SSR Notes
- Browser-only: pay(...) and the widget require window. Avoid calling them during server-side rendering.
- Initialize on the client: If using frameworks like Next.js, call initEscrowCheckout(...) in a client component or in an effect.
- Preloading: The hook marks ready after the first successful pay. If you need earlier preloading, you can trigger a preparatory flow (depending on your setup).
Error Handling
Common issues:
- Not initialized: Ensure
initEscrowCheckout({ publicKey }) is called before pay(...).
- Browser-only: Do not call pay(...) on the server.
- Network/API errors: If the session endpoint fails, pay(...) will reject with an EscrowCheckoutError that includes a code, optional HTTP status, and details.EscrowCheckoutError codes:
- NOT_INITIALIZED
-
-
-
-
-
- You can import the error class if you want stricter checks in TypeScript:
ts
import { EscrowCheckoutError } from 'payluk-escrow-inline-checkout';
`Example:
ts
try {
await pay({ / ... / });
} catch (err) {
if (err instanceof EscrowCheckoutError) {
console.error(err.code, err.status, err.message);
alert(err.message);
} else {
alert('Checkout failed');
}
}
`
Security
- Use only publishable keys in the client.
- Keep any secret or private keys on your server.
- Validate and authorize requests on your backend before creating sessions.
Types
This package ships with TypeScript types. No additional type packages are required.
Contributing
- Install dependencies:
- Build: npm run build`
- Lint/Test: add scripts as needed for your project
License
MIT (or your chosen license)