omnipay-reactnative-sdk

omnipay-reactnative-sdk

Omnipay react native sdk

Installation

yarn add omnipay-reactnative-sdk

Dependencies

yarn add react-native-select-contact react-native-webview react-native-share

Make sure your manifest files includes permission to read contacts

<uses-permission android:name="android.permission.READ_CONTACTS" />

Camera Permission (Required for Face Verification):

If you're using the FaceVerification component, you need to add camera permissions to your app's manifest files (not the SDK's):

Android - Add to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA" />
<uses-feature android:name="android.hardware.camera" android:required="false" />
<uses-feature android:name="android.hardware.camera.autofocus" android:required="false" />

iOS - Add to your app's Info.plist file:

<key>NSCameraUsageDescription</key>
<string>This app needs access to your camera for face verification</string>

Note: These permissions should be added to your app's manifest files, not the SDK's manifest, since face verification is an optional feature.

Also add this for Android 11+ support below the application tag in your AndroidManifest.xml file

<application>
......
</application>
<queries>
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="vnd.android.cursor.dir/contact" />
    </intent>
</queries>

If using CocoaPods, in the ios/ run:

pod install

Please make sure AndroidX is enabled in your project by editting android/gradle.properties and adding 2 lines:

android.useAndroidX=true
android.enableJetifier=true

Usage

// usage with useOmnipay hook
import { OmnipayProvider, useOmnipay } from 'omnipay-reactnative-sdk';

// Wrap your parent component with OmnipayProvider like below
<OmnipayProvider
  publicKey="OMNIPUBKEY_HZA3ERGYEE5XUFGTZDQV_MNKRSTA3-TU"
  env="dev"
  color="red"
>
  {/* the rest of your app */}
</OmnipayProvider>;

// import useOmnipay hook in the component you need to show the bills or wallet sdk in
const { initiateBills, initiateWallet } = useOmnipay();

function onBillsClosed() {
  console.log('sdk is closed..you can do some stuff');
}

function onWalletClosed() {
  console.log('wallet is closed..you can do some stuff');
}

initiateBills({
  phoneNumber: '08020001111',
  onClose: onBillsClosed,
});

initiateWallet({
  phoneNumber: '08020001111',
  customerRef: '9ab6790',
  userRef: '889huop',
  onClose: onWalletClosed,
  usesPaylater: true,
  usesPromo: true,
  usesAirtimeData: true,
  usesTransfer: true,
  usesBills: true,
  usesPos: true,
  promoBalanceOffset: 0,
  deviceId: 'device123',
  deviceName: 'My Device',
  hideWalletTransfer: false,
  isBvnValidationRequired: false,
  walletTab: 'Account', // 'Paylater' | 'Account' | 'Omoni'
  sessionId: 'session123',
  kycStatus: 'verified', // 'verified' | 'unverified'
  launchPage: 'wallet',
  metadata: { usesPinReset: false, usesPinUpdate: false },
});

Properties

OmnipayProvider Props

Name	Type	Description
color	String	color of primary buttons and links
env	String	dev or prod
publicKey	String	public key of the company on omnipay
analyticsConfig	Object	optional analytics configuration object

Analytics Configuration

The analytics prop accepts an object with the following properties:

Name	Type	Description
onEvent	Function	callback to receive analytics events from the SDK
allowedEvents	String[]	optional whitelist of event names to forward (if empty, all events are sent)

Example Usage:

<OmnipayProvider
  publicKey="OMNIPUBKEY_HZA3ERGYEE5XUFGTZDQV_MNKRSTA3-TU"
  env="dev"
  color="red"
  analyticsConfig={{
    onEvent: (eventName, payload) => {
      // Forward to your analytics tool (e.g., Mixpanel, Amplitude)
      console.log('Analytics Event:', eventName, payload);
    },
    allowedEvents: ['payment_success', 'checkout_initiated'],
  }}
>
  {/* the rest of your app */}
</OmnipayProvider>

How it works:

-The SDK listens for a structured analyticsEvent message from the WebView.

-The eventName and eventProperties are extracted directly from the message payload.

-If allowedEvents is provided, only events matching names in the list are forwarded

initiateBills Props

Name	Type	Description
phoneNumber	String	phone number of the customer
onClose	Function	this is used to notify you when the sdk closes
metadata	Object	optional object to pass additional properties to the SDK

initiateWallet Props

Name	Type	Description
phoneNumber	String	phone number of the customer
customerRef	String	unique reference for the customer
userRef	String	unique reference for the user
onClose	Function	this is used to notify you when the sdk closes
usesPaylater	Boolean	whether to show paylater tab in wallet view
usesPromo	Boolean	whether to show promo tab in wallet view
usesAirtimeData	Boolean	whether to show airtime and data shortcut in wallet view
usesTransfer	Boolean	whether to show transfer shortcut in wallet view
usesBills	Boolean	whether to show bills shortcut in wallet view
usesPos	Boolean	whether to show pos shortcut in wallet view
promoBalanceOffset	Number	offset for promo balance display
deviceId	String	unique identifier for the device
deviceName	String	name of the device
hideWalletTransfer	Boolean	whether to hide wallet transfer functionality
isBvnValidationRequired	Boolean	whether BVN validation is required
walletTab	String	initial wallet tab to display ('Paylater', 'Account', 'Omoni')
sessionId	String	unique session identifier
kycStatus	String	KYC status of the user ('verified', 'unverified')
launchPage	String	page to launch in the wallet
metadata	Object	optional object to pass additional properties to the SDK

Registration Sdk

import { Omnipay } from 'omnipay-reactnative-sdk';

//render it anywhere on your page where you want to display the registration sdk
<Omnipay.Registration
  env="dev"
  color="#42a99b"
  publicKey="OMNIPUBKEY_K0VUJN0JAJZIXUGKAG6XNBXR-RH5YNRS"
  phoneNumber="09031234571"
  onRegistrationSuccessful={({ customerRef, walletId }) => {
    /**
     * the customer ref and walletid can be saved
     * to your database at this point
     *
     * we will also be sending a webhook notification
     * so, you can either save at this point or via the webhook
     */
    console.log(customerRef, walletId);
  }}
  onEvent={(eventName, payload) => {
    // Forward to your analytics tool
    console.log('Event received:', eventName, payload);
  }}
  allowedEvents={['payment_success', 'checkout_initiated']}
  onClose={() => {
    /**
     * the user is done with registration.
     * you can navigate them else where at this point
     */
  }}
/>;

Properties

Name	Type	Description
color	String	color of primary buttons and links
env	String	dev or prod
phoneNumber	String	phone number of the customer
publicKey	String	public key of the company on omnipay
view	String	the view to render on the sdk
onEvent	Function	optional callback to receive analytics events from the SDK
allowedEvents	String[]	optional whitelist of event names to forward (if empty, all events are sent)

Payment Linking Sdk

import { Omnipay } from 'omnipay-reactnative-sdk';

//render it anywhere on your page where you want to display the payment linking sdk
<Omnipay.PaymentLinking
  env="dev"
  color="#42a99b"
  publicKey="OMNIPUBKEY_K0VUJN0JAJZIXUGKAG6XNBXR-RH5YNRS"
  phoneNumber="09031234571"
  customerRef="010019ddh"
  amount={5000}
  sessionId="session123"
  orderId="order456"
  onPaymentLinkingSuccessful={() => {
    /**
     * payment linking has been completed successfully
     */
  }}
  onClose={() => {
    /**
     * the user is done with payment linking.
     * you can navigate them else where at this point
     */
  }}
/>;

Properties

Name	Type	Description
color	String	color of primary buttons and links
env	String	dev or prod
publicKey	String	public key of the company on omnipay
phoneNumber	String	phone number of the customer (required if customerRef not provided)
customerRef	String	customer reference of the customer (required if phoneNumber not provided)
userRef	String	user reference of the customer (if phoneNumber/customer ref not provided)
amount	Number	amount to be linked for payment in kobo
sessionId	String	unique session identifier
orderId	String	order identifier
onPaymentLinkingSuccessful	Function	callback when payment linking is successful
onClose	Function	callback when the payment linking modal is closed