React Native SDK
React Native SDK for integrating Waffy services into mobile applications. SDK integration with Waffy Features.
Installation:
npm install @waffyapp/waffy-sdk-reactnativeInstallation
Get started with the React Native SDK in minutes
Install SDK
Install the Waffy React Native SDK package
npm install @waffyapp/waffy-sdk-reactnative
# or
yarn add @waffyapp/waffy-sdk-reactnativeInstall Dependencies
Required dependency for WebView functionality
npm install react-native-webview
# or
yarn add react-native-webviewUsage
Integrate Waffy payments into your React Native app
Basic Payment Integration
Complete example with error handling and callbacks
import { WaffyPaymentWebView, WaffyPaymentStatus } from '@waffyapp/waffy-sdk-reactnative';
import { Alert } from 'react-native';
function PaymentScreen() {
const paymentUrl =
'https://app.waffyapp.com/external/contract-id?client_id=123';
// Request the ticket from your backend right before opening checkout
const ticket = 'your-payment-ticket-here';
const handleWebViewError = (error) => {
console.error('Payment error:', error);
};
const handleUrlChange = (url) => {
console.log('URL changed:', url);
};
const handlePaymentComplete = (status, message) => {
if (status === WaffyPaymentStatus.SUCCESS) {
Alert.alert('Success', message);
} else if (status === WaffyPaymentStatus.FAILED) {
Alert.alert('Failed', message);
}
};
return (
<WaffyPaymentWebView
paymentUrl={paymentUrl}
ticket={ticket}
onWebViewError={handleWebViewError}
onUrlChange={handleUrlChange}
onPaymentComplete={handlePaymentComplete}
style={{ flex: 1 }}
/>
);
}Authentication
Pass exactly one of ticket, hint or userToken
Authentication options
The SDK appends the value you pass to the payment URL
| Prop | Appended as | When to use |
|---|---|---|
ticket | ticket | Recommended for new integrations. A one-time payment ticket from the payment ticket request. It expires after 5 minutes, so request it right before opening checkout. |
hint | login_hint | A login hint that identifies the customer. |
userToken | userTokenUrl | Legacy customer token. Existing integrations keep working unchanged; new integrations should use ticket. |
Passing none of these, or more than one, throws a WaffyAuthError. In TypeScript, the props type also rejects these cases at compile time.
ticket and hint require @waffyapp/waffy-sdk-reactnative 0.6.0 or later.
// Payment ticket (recommended)
<WaffyPaymentWebView paymentUrl={paymentUrl} ticket={ticket} />
// Login hint
<WaffyPaymentWebView paymentUrl={paymentUrl} hint={hint} />
// Legacy user token
<WaffyPaymentWebView paymentUrl={paymentUrl} userToken={userToken} />Props
Complete reference for WaffyPaymentWebView component props
*paymentUrl (required)
The payment URL to load in the WebView
This should be the Waffy payment page URL. Example: https://app.waffyapp.com/external/contract-id?client_id=123
*ticket | hint | userToken (exactly one required)
Authenticates the customer on the payment page
ticket: One-time payment ticket, appended asticket. Recommended.hint: Login hint, appended aslogin_hint.userToken: Legacy customer token, appended asuserTokenUrl.
See Authentication above.
onPaymentComplete (optional)
Callback function invoked when the payment is completed
Parameters:
status: The payment status, one of:WaffyPaymentStatus.SUCCESSWaffyPaymentStatus.FAILED
message(optional): An optional message that you can display to the user
onUrlChange (optional)
Callback function invoked whenever the WebView navigates to a new URL
Useful for tracking navigation changes during the payment flow.
onWebViewError (optional)
Callback function invoked when an error occurs while loading or rendering the WebView
Handle WebView loading errors and network issues gracefully.
style (optional)
Optional custom styles to apply to the WebView container
Standard React Native style prop. Example: style={{ flex: 1 }}
Key Features
Everything you need for mobile payment integration
WebView Integration
Payment display via WebView component
Event Callbacks
Payment completion, URL changes, and error handling
Customizable
Custom styles for the WebView container
Dependencies
Required peer dependencies
This package requires react-native-webview to be installed.
Ready to Get Started?
Start integrating Waffy payments into your React Native app in minutes
Need Help?
Check out our examples and documentation