A React Native library that provides a secure WebView component for integrating Gnosis Pay PSE functionality into your mobile applications.
npm install @gnosispay/pse-react-nativeA React Native library that provides a secure WebView component for integrating Gnosis Pay PSE functionality into your mobile applications.
This guide assumes that you have already integrated PSE SDK into your web flow.
On your backend, you first need to host the static HTML wrapper for the PSE SDK client.
We have provided an example HTML file in our example for backend integration.
We recommend putting this endpoint in the same application that serves the ephemeral tokens to your PSE integration, so you can easily inject that token into the frame.
Then you should pass the URL to this frame as webViewUrl parameter.
Refer to PSE Docs for all further details.
``bash`
npm install @gnosispay/pse-react-native
Make sure you have the required peer dependencies installed:
`bash`
npm install react-native-webview
For Expo projects:
`bash`
npx expo install react-native-webview
`tsx
import React, { useRef } from "react";
import { View, Button, Alert } from "react-native";
import { PSEWebView, PSEWebViewRef } from "@gnosispay/pse-react-native";
export default function PaymentScreen() {
const webViewRef = useRef
const config = {
appId: "your-app-id",
gnosisPayApiAuthToken: "users-gnosispay-api-token",
cardToken: "users-card-token",
webViewUrl: "https://pse-backend.v2.gnosispay.com/native-webview",
};
const handleError = (error: string) => {
Alert.alert("Payment Error", error);
};
const handleMessage = (message: any) => {
console.log("Received message from WebView:", message);
// Handle different message types from the WebView
};
const handleLoad = () => {
console.log("WebView loaded successfully");
};
return (
config={config}
onError={handleError}
onMessage={handleMessage}
onLoad={handleLoad}
style={{ flex: 1 }}
testID="pse-webview"
/>
);
}
`
| Prop | Type | Required | Description |
| ----------- | ------------------------- | -------- | ------------------------------------------------ |
| config | PSEConfig | ✅ | Configuration object with authentication details |onError
| | (error: string) => void | ❌ | Callback fired when an error occurs |onMessage
| | (message: any) => void | ❌ | Callback fired when WebView sends a message |onLoad
| | () => void | ❌ | Callback fired when WebView finishes loading |style
| | ViewStyle | ❌ | Style object for the WebView container |testID
| | string | ❌ | Test identifier for testing frameworks |
`tsx`
interface PSEConfig {
appId: string; // Your application identifier
gnosisPayApiAuthToken: string; // Authentication token
cardToken: string; // Card-specific token
webViewUrl?: string; // Full URL where your PSE iframe is hosted
}
The component exposes these methods via ref:
`tsx`
interface PSEWebViewRef {
goBack: () => void; // Navigate back in WebView history
reload: () => void; // Reload the current page
postMessage: (message: string) => void; // Send message to WebView
}
The WebView can send various message types. Handle them in your onMessage callback:
`tsx`
const handleMessage = (message: any) => {
switch (message.type) {
case "error":
console.error("WebView error:", message.message);
break;
case "success":
console.log("Operation successful:", message.data);
break;
case "navigation":
console.log("Navigation event:", message.url);
break;
default:
console.log("Unknown message type:", message);
}
};
The component provides comprehensive error handling:
`tsx
const handleError = (error: string) => {
// Common error scenarios:
// - Network connectivity issues
// - Invalid authentication tokens
// - WebView loading failures
// - Backend service unavailable
console.error("PSE WebView Error:", error);
// Show user-friendly error message
Alert.alert(
"Payment Error",
"Unable to load payment interface. Please try again.",
[{ text: "OK", onPress: () => webViewRef.current?.reload() }]
);
};
`
`tsx`
const config = {
appId: "your-prod-app-id",
gnosisPayApiAuthToken: "your-prod-auth-token",
cardToken: "your-prod-card-token",
webViewUrl: "https://pse-backend.v2.gnosispay.com/native-webview",
};
`tsx`
const config = {
appId: "your-staging-app-id",
gnosisPayApiAuthToken: "your-staging-auth-token",
cardToken: "your-staging-card-token",
webViewUrl: "https://pse-backend-staging.v2.gnosispay.com/native-webview",
};
- React Native >= 0.70.0
- React >= 18.0.0
- react-native-webview >= 13.0.0
This repository includes an example app to test the library:
1. Clone the repository:
`bash`
git clone
cd pse-react-native
2. Install dependencies:
`bash`
npm install
3. Start the example app:
`bash`
npx expo start
4. Open the app in your preferred development environment:
- iOS Simulator
- Android Emulator
- Physical device with Expo Go
`bash`
npm run build
This compiles the TypeScript source files and generates the distribution files in the lib/ directory.
WebView not loading:
- Verify your authentication tokens are valid
- Check network connectivity
- Ensure the webViewUrl is accessible
Authentication errors:
- Double-check your appId, gnosisPayApiAuthToken, and cardToken
- Verify tokens haven't expired
- Contact your PSE provider for token validation
Build errors:
- Ensure react-native-webview is properly installed
- Check that peer dependencies match the required versions
- Clear your Metro cache: npx expo start --clear`
[Add your license information here]
For technical support or questions about integration, please contact your PSE provider or create an issue in this repository.