# omnipay-reactnative-sdk

Omnipay react native sdk

## Installation

```sh
yarn add omnipay-reactnative-sdk
```

## Dependencies

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

Make sure your manifest files includes permission to read contacts

```sh
<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`:

```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:

```xml
<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

```sh
<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:

```sh
pod install
```

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

```sh
android.useAndroidX=true
android.enableJetifier=true
```

## Usage

```js
// 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:**

```js
<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

```js
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

```js
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                         |