Import and initialize the SDK in your application.Make sure the container that will host the widget has explicit dimensions in CSS. The Widget will fill the container bounds. Minimum recommended size is 400px × 600px.The paymentMethods option lets you control which payment methods are available to users. Omit it to show all supported methods. See the SDK Reference for all configuration options.
JavaScript/TypeScript example
Copy
Ask AI
import { PaymentWidget } from '@uphold/enterprise-payment-widget-web-sdk';// Create a Payment Widget session (see the widget flows for examples)const session = await createPaymentWidgetSession();// Create the Widget instance with optional payment method filteringconst widget = new PaymentWidget(session, { debug: true, paymentMethods: [ { type: 'card' }, { type: 'bank' }, { type: 'crypto', assets: { include: ['BTC', 'ETH', 'XRP'] } } ]});// Set up event handlerswidget.on('complete', (event) => { console.log('Payment completed:', event.detail.value); widget.unmount();});widget.on('cancel', () => { console.log('Payment cancelled'); widget.unmount();});widget.on('error', (event) => { console.error('Payment error:', event.detail.error); widget.unmount();});widget.on('ready', () => { console.log('Payment Widget is ready');});// Mount the Widget's iframe to a DOM elementwidget.mountIframe(document.getElementById('payment-container'));
The session parameter is obtained by calling the Create Session endpoint.
Native mobile applications integrate the Payment Widget using a WebView component that loads an HTML page containing the Payment Widget SDK.To handle Payment Widget events, your native application needs to implement a communication bridge between the WebView and native code. This bridge enables your native app to receive and respond to events from the Payment Widget.
Create an HTML file that includes the Payment Widget SDK in your JS bundle:
Copy
Ask AI
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>Payment Widget</title> <style> body { margin: 0; padding: 0; } #payment-container { width: 100%; height: 100vh; } </style> </head> <body> <div id="payment-container"></div> <!-- Include your JS bundle which contains the SDK --> <script src="your-bundle-with-sdk.js"></script> <script> // Initialize Widget when page loads window.addEventListener('load', () => { const session = createPaymentWidgetSession(); const widget = new PaymentWidget(session); widget.on('complete', (event) => { sendToNativeApp('complete', event.detail); widget.unmount(); }); widget.on('cancel', () => { sendToNativeApp('cancel'); widget.unmount(); }); widget.on('error', (event) => { sendToNativeApp('error', event.detail.error); widget.unmount(); }); widget.mountIframe(document.getElementById('payment-container')); }); // Helper function to send events to native app function sendToNativeApp(type, data = null) { const message = { type, data }; if (window.webkit?.messageHandlers?.paymentWidgetMessage) { // iOS - send all events through single handler window.webkit.messageHandlers.paymentWidgetMessage.postMessage(message); } else if (window.PaymentBridge) { // Android - send events through JavaScript interface window.PaymentBridge.onMessage(JSON.stringify(message)); } else if (window.ReactNativeWebView) { // React Native - send events through postMessage window.ReactNativeWebView.postMessage(JSON.stringify(message)); } } </script> </body></html>
The Payment Widget SDK must be included in your WebView bundle (for example, via your build pipeline). Loading the SDK directly from a CDN is not supported.
For iOS, file:// URLs may be restricted. Consider using source={{ html: '<html>...</html>' }} or loading a bundled asset and adjusting the URI per platform.
Widget not displayingThe widget loads in an iframe, which requires proper Content Security Policy (CSP) configuration. Add the following domains to your CSP directives: