Using the SDK

The Payment Widget provides a seamless way to integrate Uphold’s payment capabilities into your applications. Integration is achieved through the Payment Widget SDK, which can be used in both web and native applications. For web applications, the SDK integrates directly into your JavaScript/TypeScript code. For native applications (iOS/Android), the SDK runs within a WebView component, providing the same functionality in a native app environment.

Prerequisites

Before integrating the Payment Widget, ensure you have:

Access to Uphold’s Enterprise REST API - Get in touch with an Uphold Sales representative or your Uphold Account Manager to get started.

Installation

The Payment Widget SDK is available as an NPM package. Install it in your project:

npm install @uphold/enterprise-payment-widget-web-sdk

Web Application Integration

For web applications, import and use the SDK directly in your JavaScript/TypeScript code:

import { PaymentWidget } from '@uphold/enterprise-payment-widget-web-sdk';

// Create a Payment Widget session (See the 'Use Cases' pages for examples)
const session = createPaymentWidgetSession();

// Create the Widget instance
const widget = new PaymentWidget(session, { debug: true });

// Set up event handlers
widget.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();
});

// Mount the Widget's iframe to a DOM element
widget.mountIframe(document.getElementById('payment-container'));

The session parameter is a payment session object created through the Create Session endpoint. The specific session creation process and parameters vary depending on your use case. See the individual use case pages (Select for Deposit, Select for Withdrawal, Authorize) for detailed examples of how to create sessions for each flow.

Native Application Integration

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.

HTML Template for WebView

Create an HTML file that includes the Payment Widget SDK in your js bundle:

<!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>

Setting Up the WebView

Now that you have the HTML template, you need to set up the WebView in your native application to load this HTML file and configure event listeners to react to the Payment Widget events.

iOS (Swift)

import WebKit

class PaymentViewController: UIViewController, WKScriptMessageHandler {
    @IBOutlet weak var webView: WKWebView!

    override func viewDidLoad() {
        super.viewDidLoad()

        // Set up single message handler for all Payment Widget events
        let contentController = webView.configuration.userContentController
        contentController.add(self, name: "paymentWidgetMessage")

        // Load your HTML file with the Payment Widget
        if let url = Bundle.main.url(forResource: "payment-widget", withExtension: "html") {
            webView.loadFileURL(url, allowingReadAccessTo: url.deletingLastPathComponent())
        }
    }

    // Handle messages from the WebView
    func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
        if message.name == "paymentWidgetMessage" {
            guard let messageDict = message.body as? [String: Any],
                  let type = messageDict["type"] as? String else {
                return
            }

            let data = messageDict["data"]

            switch type {
              case "complete":
                  handlePaymentComplete(data: data)
              case "cancel":
                  handlePaymentCancel()
              case "error":
                  handlePaymentError(error: data)
              default:
                  print("Unknown Payment Widget message type: \(type)")
            }
        }
    }

    private func handlePaymentComplete(data: Any?) {
        // Handle successful payment completion
        print("Payment completed: \(data ?? "no data")")
        // Navigate to success screen or handle completion
    }

    private func handlePaymentCancel() {
        // Handle payment cancellation
        print("Payment cancelled")
        // Navigate back or show cancellation message
    }

    private func handlePaymentError(error: Any?) {
        // Handle payment error
        print("Payment error: \(error ?? "unknown error")")
        // Show error message to user
    }
}

Android (Java/Kotlin)

import android.webkit.WebView;
import android.webkit.WebSettings;
import android.webkit.JavascriptInterface;
import android.util.Log;
import org.json.JSONObject;

// Set up WebView
WebView webView = findViewById(R.id.webview);
WebSettings webSettings = webView.getSettings();
webSettings.setJavaScriptEnabled(true);

// Add JavaScript interface to handle events from WebView
webView.addJavascriptInterface(new PaymentBridge(), "PaymentBridge");

// Load your HTML file with the Payment Widget
webView.loadUrl("file:///android_asset/payment-widget.html");

// JavaScript interface class to handle WebView events
public class PaymentBridge {
    @JavascriptInterface
    public void onMessage(String messageJson) {
        try {
            JSONObject message = new JSONObject(messageJson);
            String type = message.getString("type");
            Object data = message.opt("data");

            runOnUiThread(() -> {
                switch (type) {
                    case "complete":
                        handlePaymentComplete(data != null ? data.toString() : null);
                        break;
                    case "cancel":
                        handlePaymentCancel();
                        break;
                    case "error":
                        handlePaymentError(data != null ? data.toString() : null);
                        break;
                    default:
                        Log.w("Payment", "Unknown Payment Widget message type: " + type);
                }
            });
        } catch (Exception e) {
            Log.e("Payment", "Error parsing Payment Widget message", e);
        }
    }

    private void handlePaymentComplete(String data) {
        // Handle successful payment completion
        Log.d("Payment", "Payment completed: " + data);
        // Navigate to success screen or handle completion
    }

    private void handlePaymentCancel() {
        // Handle payment cancellation
        Log.d("Payment", "Payment cancelled");
        // Navigate back or show cancellation message
    }

    private void handlePaymentError(String error) {
        // Handle payment error
        Log.e("Payment", "Payment error: " + error);
        // Show error message to user
    }
}

React Native

import { WebView } from 'react-native-webview';
import { Alert } from 'react-native';

const PaymentScreen = () => {
  const handleMessage = (event) => {
    try {
      const message = JSON.parse(event.nativeEvent.data);

      switch (message.type) {
        case 'complete':
          handlePaymentComplete(message.data);
          break;
        case 'cancel':
          handlePaymentCancel();
          break;
        case 'error':
          handlePaymentError(message.data);
          break;
        default:
          console.log('Unknown message type:', message.type);
      }
    } catch (error) {
      console.error('Error parsing WebView message:', error);
    }
  };

  const handlePaymentComplete = (data) => {
    // Handle successful payment completion
    console.log('Payment completed:', data);
    Alert.alert('Success', 'Payment completed successfully!');
    // Navigate to success screen
  };

  const handlePaymentCancel = () => {
    // Handle payment cancellation
    console.log('Payment cancelled');
    Alert.alert('Cancelled', 'Payment was cancelled');
    // Navigate back
  };

  const handlePaymentError = (error) => {
    // Handle payment error
    console.error('Payment error:', error);
    Alert.alert('Error', 'An error occurred during payment');
    // Show error message or retry option
  };

  return (
    <WebView
      source={{ uri: 'file:///path/to/payment-widget.html' }}
      javaScriptEnabled={true}
      domStorageEnabled={true}
      onMessage={handleMessage}
    />
  );
};

Next Steps

Now that you understand how to integrate the Payment Widget SDK, explore what you can do:

Use Cases

Select for Deposit - Allows users to select an external account for depositing funds
Select for Withdrawal - Allows users to select an external account for withdrawing funds
Authorize - Authorizes transactions with user confirmation

Additional Resources

Create Session Endpoint
SDK Reference

FAQ

Q: The Payment Widget does not show when running locally, what is the cause? A: This might be due to Content Security Policy (CSP) settings. Check your framework documentation on how to configure CSP to allow the Payment Widget iframe to be loaded.

Topper

Payment

KYC

Prerequisites

Installation

Web Application Integration

Native Application Integration

HTML Template for WebView

Setting Up the WebView

Next Steps

Use Cases

Additional Resources

FAQ

Topper

Payment

KYC

​Prerequisites

​Installation

​Web Application Integration

​Native Application Integration

​HTML Template for WebView

​Setting Up the WebView

​Next Steps

​Use Cases

​Additional Resources

​FAQ

Prerequisites

Installation

Web Application Integration

Native Application Integration

HTML Template for WebView

Setting Up the WebView

Next Steps

Use Cases

Additional Resources

FAQ