react-native-interswitch-pay

The Interswitch React Native SDK simplifies the integration of the Interswitch Payment Gateway (IPG) into your React Native app using a WebView component.

demo

Features

• Flexible implementation following the official documentation.
• Integrated with the Inline Checkout.
• Built with TypeScript for type safety and an enhanced developer experience.
• Supports both Expo and React Native CLI.

Installation

Npm

npm install react-native-interswitch-pay

Yarn

yarn  react-native-interswitch-pay

Expo

expo  install react-native-interswitch-pay

Important: This package depends on react-native-webview as a peer dependency and requires it for proper functionality.

Quick Examples.

Auto start Payment

import { useRef, useState } from 'react';
import { View, StyleSheet, Text, TouchableOpacity, Alert } from 'react-native';
import {
  IswPaymentWebView,
  type IswWebViewRefMethods,
} from 'react-native-interswitch-pay';

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

  const isw = {
    merchantCode: 'MX6072',
    payItemId: '9405967',
    transactionRef: txnRef,
    amount: 100000,
    currency: '566',
    mode: 'TEST',
  };

  return (
    <View style={styles.container}>
      <Text style={styles.text}>Interswitch Payment Gateway</Text>
      <IswPaymentWebView
        amount={isw.amount}
        autoStart={true}
        trnxRef={txnRef}
        showBackdrop={false}
        mode={isw.mode as any}
        merchantCode={isw.merchantCode}
        payItem={{ id: isw.payItemId }}
        style={styles.webViewStyle}
        onCompleted={(response) => {
          console.log('Response', response);
        }}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    paddingTop: 40,
    paddingHorizontal: 24,
  },
  text: {
    textAlign: 'center',
    marginTop: 40,
    fontSize: 20,
  },
  webViewStyle: {
    marginTop: '10%',
  },
});

Use with custom WebPay Callback Response payload.

import { useRef, useState } from 'react';
import { View, StyleSheet, Text, TouchableOpacity, Alert } from 'react-native';
import {
  IswPaymentWebView,
  type IswWebViewRefMethods,
} from 'react-native-interswitch-pay';


interface CustomData {
  userId: string;
  orderId: number;
  cardProductionBin: string;
}

export default function App() {
 // rest of the code.

  const isw = {
    merchantCode: 'MX6072',
    payItemId: '9405967',
    transactionRef: txnRef,
    amount: 100000,
    currency: '566',
    mode: 'TEST',
  };

  return (
    <View style={styles.container}>
      <Text style={styles.text}>Interswitch Payment Gateway</Text>
      <TouchableOpacity style={styles.button} onPress={handleStartPayment}>
        <Text style={styles.buttonText}>Start Payment</Text>
      </TouchableOpacity>
      <TouchableOpacity
        style={[styles.button, styles.stopButton]}
        onPress={() => webRef.current?.end()}
      >
        <Text style={styles.buttonText}>Stop Payment</Text>
      </TouchableOpacity>
      <IswPaymentWebView<CustomData>
        ref={webRef}
        amount={isw.amount}
        autoStart={false}
        trnxRef={txnRef}
        showBackdrop={false}
        mode={isw.mode as any}
        merchantCode={isw.merchantCode}
        payItem={{ id: isw.payItemId }}
        style={styles.webViewStyle}
        onCompleted={(response) => {
          console.log('Response', response);
          console.log('Custom Response Data:', response.cardProductionBin);
        }}
      />
    </View>
  );
}

const styles = StyleSheet.create({
 // styles
});

Customizing where the checkout page comes from

The WebView resolves its source in this order, checked top to bottom:

1. getHtml provided → the WebView loads your returned HTML string directly (source={{ html }}). This wins outright and webPayBaseUrl is ignored entirely.
2. webPayBaseUrl provided (and no getHtml) → the WebView loads that URL instead of the hosted checkout page, with the same query params appended.
3. Neither provided → falls back to the library's hosted Interswitch inline checkout page.

webPayBaseUrl must be a valid http(s) URL — passing anything else (e.g. a malformed string) throws synchronously when the component renders, so validate user-supplied values before passing them in.

Option A: point at your own checkout base URL

Use this when you're hosting your own version of the inline checkout page (or a staging/UAT variant) but still want the library to build and append the standard query params for you.

import { IswPaymentWebView } from 'react-native-interswitch-pay';

<IswPaymentWebView
  // ...other required props
  webPayBaseUrl="https://isw-inline-checkout-webview.uat.isw.la"
/>

Option B: provide your own checkout page HTML (avoid vendor lock-in)

Pass getHtml to render your own HTML instead of loading any URL at all — it receives the resolved payment params (see GetHtmlInputsFields: customer, tokeniseCard, payItem, trnxRef, merchantCode, amount, accessToken, currency, mode, splitAccounts, siteRedirectUrl) and must return a full HTML document string. Because getHtml takes precedence, webPayBaseUrl is not read at all when both are set.

import {
  IswPaymentWebView,
  type GetHtmlInputsFields,
} from 'react-native-interswitch-pay';

const buildCheckoutHtml = (params: GetHtmlInputsFields) => `
  <!DOCTYPE html>
  <html>
    <body>
      <form
        id="ipg-form"
        method="post"
        action="https://newwebpay.interswitchng.com/collections/w/pay"
        style="display: none;"
      >
        <input name="merchant_code" value="${params.merchantCode}" />
        <input name="pay_item_id" value="${params.payItem.id}" />
        <input name="site_redirect_url" value="${params.siteRedirectUrl ?? ''}" />
        <input name="txn_ref" value="${params.trnxRef}" />
        <input name="amount" value="${params.amount}" />
        <input name="currency" value="${params.currency}" />
      </form>
      <script>document.getElementById('ipg-form').submit();</script>
    </body>
  </html>
`;

<IswPaymentWebView
  // ...other required props
  getHtml={buildCheckoutHtml}
/>

Use with Ref to trigger using a button

import { useRef, useState } from 'react';
import { View, StyleSheet, Text, TouchableOpacity, Alert } from 'react-native';
import {
  IswPaymentWebView,
  type IswWebViewRefMethods,
} from 'react-native-interswitch-pay';

export default function App() {
  const webRef = useRef<IswWebViewRefMethods>(null);
  const [txnRef, setTxnRef] = useState(`txn_${Date.now()}`);

  const handleStartPayment = () => {
    try {
      const newTxnRef = `txn_${Date.now()}`;
      setTxnRef(newTxnRef);

      // Added this delay for Test purposes, so you can test multiple times
      setTimeout(() => {
        webRef.current?.start();
      }, 100);
    } catch (error) {
      Alert.alert('Validation Error', (error as Error).message);
    }
  };

  const isw = {
    merchantCode: 'MX6072',
    payItemId: '9405967',
    transactionRef: txnRef,
    amount: 100000,
    currency: '566',
    mode: 'TEST',
  };

  return (
    <View style={styles.container}>
      <Text style={styles.text}>Interswitch Payment Gateway</Text>
      <TouchableOpacity style={styles.button} onPress={handleStartPayment}>
        <Text style={styles.buttonText}>Start Payment</Text>
      </TouchableOpacity>
      <TouchableOpacity
        style={[styles.button, styles.stopButton]}
        onPress={() => webRef.current?.end()}
      >
        <Text style={styles.buttonText}>Stop Payment</Text>
      </TouchableOpacity>
      <IswPaymentWebView
        ref={webRef}
        amount={isw.amount}
        autoStart={false}
        trnxRef={txnRef}
        showBackdrop={false}
        mode={isw.mode as any}
        merchantCode={isw.merchantCode}
        payItem={{ id: isw.payItemId }}
        style={styles.webViewStyle}
        onCompleted={(response) => {
          console.log('Response', response);
        }}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    paddingTop: 40,
    paddingHorizontal: 24,
  },
  text: {
    textAlign: 'center',
    marginTop: 40,
    fontSize: 20,
  },
  title: {
    fontSize: 18,
    marginBottom: 20,
    fontWeight: 'bold',
  },
  button: {
    marginTop: '20%',
    backgroundColor: '#007bff',
    paddingVertical: 16,
    paddingHorizontal: 20,
    borderRadius: 8,
  },
  stopButton: {
    backgroundColor: '#dc3545',
  },
  buttonText: {
    color: '#fff',
    fontSize: 16,
  },
  webViewStyle: {
    marginTop: '10%',
  },
});

Props

| Props Name | Description | Required | Value | Data type | | -------------------- | ----------------------------------------------------- | -------- | ----------------- | --------- | | trnxRef | transaction reference. | Yes | | string | | merchantCode | ISW merchant code | Yes | | string | | amount | Cost of the item you want your customer to pay in Kobo e.g amount * 100 | Yes | | number | | customer | Customer information e.g email, first name, last name | No | | object | | payItem | Payment Item e.g id and name | Yes | | object[] | | autoStart | To auto initialize transaction | No | false | boolean | | indicatorColor | activity indicator color | No | red | string | | currency | ISO currency code e.g 566 | Yes | e.g 566 | number | | mode | Environment e.g LIVE, TEST | Yes | TEST | string | | onCompleted | Callback that triggers when webview close or cancels | Yes | | Function | | splitAccounts | ISW Split accounts for settlements | No | SplitAccounts[] | Array | | showBackdrop | Display loading backdrop | No | false | boolean | | style | WebView component custom style | No | object | ViewStyle | | backButton | custom back button style | No | undefined | React Node | | loadingText | Custom text shown under the loading indicator while the WebView initializes | No | 'Loading Payment Gateway, Please wait.' | string | | tokeniseCard | Whether to tokenize the customer's card; the token is returned when you re-query the transaction | No | undefined | 'true' \| 'false' | | accessToken | Access token value gotten from passport | No | undefined | 'true' \| 'false' | | siteRedirectUrl | URL Interswitch redirects to after checkout completes | No | 'https://blank.org' | string | | webPayBaseUrl | Custom checkout base URL, replacing the default hosted Interswitch checkout page. Must be a valid http(s) URL. Ignored when getHtml is set. | No | undefined | string | | getHtml | Render your own checkout HTML instead of loading webPayBaseUrl. Receives the resolved payment params, must return a full HTML document string. | No | undefined | (params: GetHtmlInputsFields) => string | | loaderContainerStyle | Custom style for the loading indicator's container | No | undefined | ViewStyle | | loaderTextStyle | Custom style for the loading indicator's text | No | undefined | TextStyle | | modalProps | Additional props passed through to the underlying Modal (e.g. animationType, transparent) | No | undefined | ModalProps | | webViewProps | Additional props passed through to the underlying WebView (e.g. injectedJavaScript, originWhitelist) | No | undefined | WebViewProps |

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

Made with create-react-native-library