React Native SDK

React Native SDK

React Native SDK for integrating Waffy services into mobile applications. SDK integration with Waffy Features.

View on npm

Installation:

npm install @waffyapp/waffy-sdk-reactnative

Installation

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

Install Dependencies

Required dependency for WebView functionality

npm install react-native-webview
# or
yarn add react-native-webview

Usage

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

PropAppended asWhen to use
ticketticketRecommended 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.
hintlogin_hintA login hint that identifies the customer.
userTokenuserTokenUrlLegacy 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 as ticket. Recommended.
  • hint: Login hint, appended as login_hint.
  • userToken: Legacy customer token, appended as userTokenUrl.

See Authentication above.

onPaymentComplete (optional)

Callback function invoked when the payment is completed

Parameters:

  • status: The payment status, one of:
    • WaffyPaymentStatus.SUCCESS
    • WaffyPaymentStatus.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