Interswitch Payment Gateway SDK for React Native

The Interswitch Payment Gateway (IPG) SDK for React Native provides a seamless way to integrate secure payment processing into your mobile applications. Built on top of the robust Interswitch Web Checkout, this SDK simplifies the integration process using a high-performance WebView component.

Official Documentation

---

Features

• Official Integration: Follows Interswitch Inline Checkout standards.
• Cross-Platform: Full support for both Expo and React Native CLI.
• Type Safety: Built with TypeScript for a superior developer experience and fewer runtime errors.
• Customizable: Control the payment flow with refs, handle custom response data, and style the UI to match your app.

Installation

Install the package via your preferred package manager:

NPM

npm install @interswitchapi/ipg-react-native

Yarn

yarn add @interswitchapi/ipg-react-native

Expo

npx expo install @interswitchapi/ipg-react-native

Important

This package requires react-native-webview as a peer dependency. Ensure it is installed in your project.

---

Quick Start

The following example demonstrates a basic implementation where the payment modal starts automatically.

import React, { useState } from 'react';
import { View, StyleSheet, Text } from 'react-native';
import { IswPaymentWebView } from '@interswitchapi/ipg-react-native';

export default function App() {
  const [txnRef] = useState(`txn_${Date.now()}`);

  const config = {
    merchantCode: 'MX6072',
    payItemId: '9405967',
    amount: 100000, // Amount in Kobo (e.g., 1000.00 NGN)
    mode: 'TEST' as const,
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Secure Payment</Text>
      <IswPaymentWebView
        amount={config.amount}
        autoStart={true}
        trnxRef={txnRef}
        merchantCode={config.merchantCode}
        payItem={{ id: config.payItemId }}
        mode={config.mode}
        onCompleted={(response) => {
          console.log('Payment Response:', response);
        }}
        style={styles.webView}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, paddingTop: 60, paddingHorizontal: 20 },
  title: {
    fontSize: 22,
    fontWeight: 'bold',
    textAlign: 'center',
    marginBottom: 20,
  },
  webView: { flex: 1 },
});

---

Advanced Usage

Manual Trigger with Refs

Use the IswWebViewRefMethods to programmatically start() or end() the payment process.

import React, { useRef } from 'react';
import { TouchableOpacity, Text } from 'react-native';
import {
  IswPaymentWebView,
  type IswWebViewRefMethods,
} from '@interswitchapi/ipg-react-native';

export default function PaymentScreen() {
  const paymentRef = useRef<IswWebViewRefMethods>(null);

  return (
    <>
      <TouchableOpacity onPress={() => paymentRef.current?.start()}>
        <Text>Pay Now</Text>
      </TouchableOpacity>

      <IswPaymentWebView
        ref={paymentRef}
        autoStart={false}
        // ... other props
        onCompleted={(res) => console.log(res)}
      />
    </>
  );
}

Handling Custom Response Data

You can pass a generic type to IswPaymentWebView to handle custom data fields returned in the payment callback.

interface MyCustomData {
  orderId: string;
  userId: string;
}

// ... inside your component
<IswPaymentWebView<MyCustomData>
  onCompleted={(response) => {
    console.log('Order ID:', response.orderId);
  }}
  // ...
/>;

---

API Reference: Props

Prop	Type	Required	Default	Description
trnxRef	string	Yes	-	Unique transaction reference for the session.
merchantCode	string	Yes	-	Your Interswitch Merchant Code.
amount	number | string	Yes	-	Transaction amount in Kobo (e.g., 100000 = 1000.00).
payItem	IswPayItem	Yes	-	Object containing id (required) and name (optional).
mode	'TEST' | 'LIVE'	Yes	-	Environment for the transaction.
onCompleted	Function	Yes	-	Callback triggered upon completion, cancellation, or error.
currency	number | string	No	566	ISO currency code (Default: 566 for NGN).
customer	IswCustomer	No	-	Optional customer details (id, name, email, phoneNumber).
autoStart	boolean	No	false	Automatically launch the payment modal on mount.
showBackdrop	boolean	No	false	Display a loading backdrop while the gateway initializes.
indicatorColor	ColorValue	No	-	Color for the loading activity indicator.
loadingText	string	No	-	Custom text displayed during initialization.
style	ViewStyle	No	-	custom styles for the WebView component.
backButton	ReactNode	No	-	Custom component for the back/close button.
tokeniseCard	'true' | 'false'	No	-	Flag to request card tokenization for future use.
splitAccounts	SplitAccounts[]	No	-	Array of accounts for settlement splitting.

---

Contributing

We welcome contributions! Please see the Contributing Guide for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Built with create-react-native-library