endozpay-sdk
v1.0.7
Published
The official Endozpay JavaScript/React SDK
Readme
Endozpay Open Banking JS SDK
A universal, framework-agnostic JavaScript SDK for securely embedding the Endozpay checkout and bank-selection flow into any web application.
🏗 Architecture Overview
The Endozpay SDK is built defensively to ensure absolute stability and security on third-party merchant websites.
- Framework Agnostic: While authored in React and Tailwind, the SDK compiles down to pure Vanilla JavaScript. The host application does not need React installed.
- CSS Encapsulation: The entire UI is mounted inside an open Shadow DOM. This guarantees zero CSS bleed—the host's styles will not break the widget, and the widget's Tailwind utility classes will not leak into the host application.
- Idempotent Initialization: Safe against multiple instantiation calls (e.g., React 18 Strict Mode double-renders) preventing memory leaks and DOM duplication.
📦 Installation
Choose your distribution method based on your tech stack.
Option A: NPM / Yarn (Modern Frameworks)
For applications using bundlers (React, Next.js, Vue, Angular, Svelte).
npm install endozpay-sdk
# or
yarn add endozpay-sdk
Option B: CDN (Vanilla HTML / PHP / Webflow)
For direct browser inclusion, utilize the pre-compiled UMD build via unpkg or jsDelivr.
<script src="https://unpkg.com/[email protected]/dist/endozpay-sdk.umd.js"></script>
🚀 Quick Start Guides
1. React / Next.js Integration
Import the SDK class and initialize it within a useEffect. Always call .destroy() in the cleanup function to prevent memory leaks during component unmounting.
import { useEffect, useRef } from 'react';
import { EndozpaySDK } from 'endozpay-sdk';
export default function CheckoutPage() {
const isInitialized = useRef(false);
useEffect(() => {
// Prevent double-initialization in React StrictMode
if (isInitialized.current) return;
isInitialized.current = true;
const endozpay = new EndozpaySDK();
endozpay.init({
containerId: 'endozpay-checkout-node',
payload: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...', // Replace with dynamic JWT from your backend
environment: 'sandbox',
onSuccess: (data) => {
console.log('Payment authorized successfully:', data);
// Redirect to success page or update UI
},
onError: (error) => {
console.error('Payment failed:', error);
},
onCancel: () => {
console.log('User cancelled the flow.');
},
onRedirect: (url) => {
console.log('User redirected to:', url);
}
});
// Cleanup memory and remove DOM nodes on unmount
return () => {
endozpay.destroy();
isInitialized.current = false;
};
}, []);
// Ensure the target node has explicit dimensions
return (
<div className="flex justify-center items-center w-full min-h-screen bg-gray-50">
<div id="endozpay-checkout-node" className="w-full max-w-md h-[600px] relative" />
</div>
);
}
2. Vanilla HTML / Inline JS Integration
When loaded via the CDN script tag, the SDK exposes the Endozpay class globally on the window object.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Merchant Checkout</title>
<!-- 1. Load the SDK -->
<script src="https://unpkg.com/[email protected]/dist/endozpay-sdk.umd.js"></script>
<style>
/* Define the boundaries for the widget */
#payment-container { width: 100%; max-width: 500px; height: 600px; margin: 0 auto; position: relative; }
</style>
</head>
<body>
<!-- 2. Target Container -->
<div id="payment-container"></div>
<!-- 3. Initialize SDK -->
<script>
document.addEventListener("DOMContentLoaded", function() {
// The class is available globally via window.Endozpay
const sdk = new window.Endozpay();
sdk.init({
containerId: 'payment-container',
payload: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
environment: 'production',
onSuccess: function(data) {
alert("Payment Success!");
},
onCancel: function() {
console.log("Payment window closed.");
}
});
});
</script>
</body>
</html>
⚙️ API Reference
EndozpayConfig Object
The configuration object passed into the .init() method.
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| containerId | string | Yes | The DOM id of the empty <div> where the widget will mount. |
| payload | string | Yes | The encrypted payment intent or JWT payload generated by your backend. |
| environment | 'sandbox', 'production' | No | The environment in which the SDK is running. | Dictates the API base URL. Defaults to 'production'. |
| onSuccess | (data: any) => void | No | Fired when the Open Banking authorization is successful. |
| onError | (error: any) => void | No | Fired if a network error occurs or the user encounters a strict API failure. |
| onCancel | () => void | No | Fired when the user explicitly clicks the "Cancel" button. |
| onRedirect | (url: string) => void | No | Overrides default WebSocket behavior. If provided, the SDK passes the banking redirect URL to this callback instead of immediately changing window.location.href. |
SDK Methods
sdk.init(config: EndozpayConfig): Mounts the Shadow DOM, injects encapsulated styles, and boots the React UI.sdk.destroy(): Safely unmounts the internal React tree, disconnects active WebSockets, and cleans up the Shadow DOM to prevent memory leaks in Single Page Applications (SPAs).
🔒 Security Notes for Implementers
- Never pass plain text parameters: The
payloadmust be securely generated on your server and passed to the frontend. Do not construct payment details directly in the browser. - CSP (Content Security Policy): If your site utilizes strict CSP headers, ensure you allow connections to
https://endozapi.celergate.net(and your WebSocket domains) in yourconnect-srcdirectives.