@networkinternational/ni-card-management-sdk

Network International React Native Card Management SDK

The Network International React Native Card Management SDK allows you to integrate with Network International standard APIs for card management. (https://developer.network.ae) The current supported features are:

1. Get Secured Card Details : Display a card component providing the ability to show card number, expiry date, CVV and cardholder name. This supports full end to end encryption to securely transport this sensitive information.
2. Set PIN : Displays a PIN pad to allow cardholder to set a PIN on their new card. The PIN is end to end encrypted to securely transport this sensitive information
3. Change PIN: Displays two PIN pad to allow the cardholder to change their PIN by providing old & new PIN. The PINs are end to end encrypted to securely transport this sensitive information
4. Verify PIN: Displays a PIN pad to allow cardholder to verify PIN on their card. The PIN is end to end encrypted to securely transport this sensitive information
5. View PIN: Displays a component providing the ability to show PIN card. The PIN is end to end encrypted to securely transport this sensitive information

Requirements

The Network International React Native Card Management SDK requires minimum react native version 0.71.0 and later and works with iOS version 12 and above.

Installation

The SDK can be added via npm or yarn. Refer to the CONTRIBUTING.md file for the example app installation steps. The SDK requires the following dependencies: react-native-paper, @react-native-community/clipboard, react-native-linear-gradient. If you did not already, please install them before installing the SDK.

npm

• Please install the react-native-paper @react-native-community/clipboard react-native-linear-gradient packages only if you did not already.

nmp install react-native-paper @react-native-community/clipboard react-native-linear-gradient
npm install @networkinternational/ni-card-management-sdk

yarn

• Please install the react-native-paper @react-native-community/clipboard react-native-linear-gradient packages only if you did not already.

yarn add react-native-paper @react-native-community/clipboard react-native-linear-gradient
yarn add @networkinternational/ni-card-management-sdk

OPTIONAL INTEGRATION STEPS

In case of issues when running the iOS or the Android application after installing the SDK, try the following steps.

Optional iOS integration steps.

• Open the iOS project (from the iOS folder: nameOfTheProject.xcworkspace) in Xcode.
• Remove LaunchScreen.storyboard and Images.xcassets resources from Build Phases -> Copy Bundle Resources
• Add libNiCardManagementSDK.a in General -> Frameworks, Libraries, and Embedded Content

Optional Android integration steps

• Open the Android project inside Android Studio
• Locate build.gradle (Project: NameOfTheProject) file and add the following:

   dependencies { 
   ... 
  implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version" 
   ... 
   } 

• Open AndroidManifest.xml (app -> manifests) and change android:allowBackup from “false” to “true”

• In case of issues when building from terminal the project, try opening the android project inside Android studio and let it do the indexing and all the other things necessary to sync the project then try again to build it first from Android Studio and then later from terminal

Integration

Basics

After you have installed the SDK, by following one of the above set of steps, you can import the SDK into your react native app and used it.

Usage

Create NIInput model

    import {
        NiInputInterface, 
        NIConnectionProperties, 
        NIDisplayAttributes, 
        NIThemeEnum, 
        NILanguageEnum,
    } from '@networkinternational/ni-card-management-sdk';

    export const input: NiInputInterface = {
        bankCode: [yourBankCode],
        cardIdentifierId: [cardIdentifierId],
        cardIdentifierType: [cardIdentifierType],
        connectionProperties: NIConnectionProperties = {
            rootUrl: [rootUrl], token: [token],
        },
        displayAttributes: NIDisplayAttributes = {
            theme: NIThemeEnum.light as themeType,
            language: NILanguageEnum.english as languageType,
        },
    };

Display attributes

Display attributes parameter is optional. You can set one or more attributes, or even none of them.

1. Theme

We support dark and light mode, by setting the theme parameter from the display attributes. If the Customer App is in dark mode, then you should use our SDK with dark theme. If the Customer App is in light mode, then you should use our SDK with light theme.

2. Language

Languages supported are English and Arabic. You can either set the desired language or not. If you don’t set any language, it will default to English.

3. Fonts

We support customization of fonts. System and custom fonts can be set for the labels of each form view.

4. Card Attributes

Card Attributes is optional. It can be set if customization of the card details view is wanted.

We offer:

• Possibility to show or hide card details by default

To directly show the card details (not masked) when card view is displayed, we expect the shouldHide property to be set to false, otherwise to be set to false. If shouldHide property is not set, the default value is true.

    const cardAttributes = NICardAttributes(shouldHide: false)

• Background image customization

For the card background image, we expect a UIImage to be set. The recommended size would be 343 x 182.

    const backgroundImage: ImageURISource = require('../assets/images/background_image.png');
    const cardAttributes = NICardAttributes(backgroundImage: image)) 

• Possibility to set the text position as grouped labels

The card details labels are grouped as follows:

• Card Number Group

• Expiry Date & CVV Group

• Card Holder Name Group

In order to set the position of the each group, we expect percentage (of card container view height and width) values to the following parameters: leftAlignment, cardNumberGroupTopAlignment, dateCvvGroupTopAlignment, cardHolderNameGroupTopAlignment

    const textPositioning: NICardDetailsTextPositioning = {
        leftAlignment: 0.05,
        cardNumberGroupTopAlignment: 0.4,
        dateCvvGroupTopAlignment: 0.6,
        cardHolderNameGroupTopAlignment: 0.8,
    };

All are optional.

If all properties are wanted, initialization NICardAttributes is made with all properties.

    const backgroundImage: ImageURISource = 
      require('../assets/images/background_image.png');
    const textPositioning: NICardDetailsTextPositioning = {
        leftAlignment: 0.05,
        cardNumberGroupTopAlignment: 0.4,
        dateCvvGroupTopAlignment: 0.6,
        cardHolderNameGroupTopAlignment: 0.8,
    };
    const cardAttributes = NICardAttributes(
        shouldHide: false, 
        backgroundImage: image, 
        textPositioning: textPosition) 

Display Card Details View

The form interface will display the card details in a View. The card info displayed are: Card Number, Expiry Date, CVV and Cardholder Name.

    import {
        CardDetailsComponent,
        type NIErrorResponse,
    } from '@networkinternational/ni-card-management-sdk';

    <CardDetailsComponent
        input={input}
        callback={(
            error: NIErrorResponse | null,
            result: string | null = null
        ) => {
            callback(); // implement your callback
        }}
    />

Set PIN Form

A PIN-pad will be displayed into a separate View on a separate screen.

    import {
        SetPinView,
        type NIErrorResponse,
        NIPinTypeEnum,
    } from '@networkinternational/ni-card-management-sdk';

    import { input } from ['path/to/your/object/config'];

by specifying the type (pin length)

    const type = NIPinTypeEnum.fourDigits;

  return (
    <SetPinView
      input={input}
      type={type}
      callback={(
        error: NIErrorResponse | null,
        result: string | null = null
      ) => {
        callback(); // implement your callback
      }}
    />

or without specifying the type (pin length)

  return (
    <SetPinView
      input={TEST_INPUT}
      callback={(
        error: NIErrorResponse | null,
        result: string | null = null
      ) => {
        callback(); // implement your callback
      }}
    />

Change PIN Form

A PIN-pad will be displayed in a VIEW into a separate screen.

Change PIN is a two step flow:
1.Capture current PIN 
2.Capture new PIN 

    import {
        ChangePinView,
        type NIErrorResponse,
        NIThemeEnum,
    } from '@networkinternational/ni-card-management-sdk';

    import { input } from ['path/to/your/object/config'];

by specifying the type (pin length)

    const type = NIPinTypeEnum.fourDigits;

    <ChangePinView
      input={input}
      type={type}
      callback={(
        error: NIErrorResponse | null,
        result: string | null = null
      ) => {
        console.log('ChangePinView', { error, result });
        callback();  // implement your callback
      }}
    />

or without specifying the type (pin length)

    <ChangePinView
      input={input}
      callback={(
        error: NIErrorResponse | null,
        result: string | null = null
      ) => {
        console.log('ChangePinView', { error, result });
        callback(); // implement your callback
      }}
    />

Verify PIN Form

A PIN-pad will be displayed in a View into a separate screen.

javascript:

    import {
        VerifyPinView,
        type NIErrorResponse,
        NIPinTypeEnum,
    } from '@networkinternational/ni-card-management-sdk';

    import { input } from ['path/to/your/object/config'];

by specifying the type (pin length)

    const type = NIPinTypeEnum.fourDigits;

    <VerifyPinView
      input={TEST_INPUT}
      type={type}
      callback={(
        error: NIErrorResponse | null,
        result: string | null = null
      ) => {
        callback(); // implement your callback
      }}
    />

or without specifying the type (pin length)

    <VerifyPinView
      input={TEST_INPUT}
      callback={(
        error: NIErrorResponse | null,
        result: string | null = null
      ) => {
        callback(); // implement your callback
      }}
    />

Display as a view

The customer application can integrate Card Details and View Pin as a view into a UIViewController

Display Card Details View

A view of NICardView type can be added into a View, then set the input and start the flow as below:

    import {
        ViewPinComponent,
        type NIErrorResponse,
        NIPinTypeEnum,
    } from '@networkinternational/ni-card-management-sdk';

    import { input } from ['path/to/your/object/config'];

by specifying the type (pin length)

    const type = NIPinTypeEnum.fourDigits;

      <ViewPinComponent
        input={TEST_INPUT_VIEW_PIN}
        type={type}
        callback={(
          error: NIErrorResponse | null,
          result: string | null = null
        ) => {
            callback(); // implement your callback
        }}
      />

or without specifying the type (pin length)

      <ViewPinComponent
        input={TEST_INPUT_VIEW_PIN}
        callback={(
          error: NIErrorResponse | null,
          result: string | null = null
        ) => {
            callback(); // implement your callback
        }}
      />

Parameters:

• input - type NIInput - see the explanation above. This is a required parameter.
• timer - type number - offers possibility to set the display time of the PIN, expressed in seconds. Using value "0" for this parameter, the PIN will be displayed indefinitely. After the countdown, the PIN will be masked. This is a required parameter.
• the timer property will be added at input object like below.

    export const input: NiInputInterface = {
        bankCode: [yourBankCode],
        cardIdentifierId: [cardIdentifierId],
        cardIdentifierType: [cardIdentifierType],
        connectionProperties: NIConnectionProperties = {
            rootUrl: [rootUrl], token: [token],
        },
        displayAttributes: NIDisplayAttributes = {
            theme: NIThemeEnum.light as themeType,
            language: NILanguageEnum.english as languageType,
        },
        timer: 5,
    };

Display View Pin View

A view of NIViewPinView type can be added into storyboard, then set the input and start the flow as below:

    import {
        ViewPinView,
        type NIErrorResponse,
        NIPinTypeEnum,
    } from '@networkinternational/ni-card-management-sdk';

    import { input } from ['path/to/your/object/config'];

by specifying the type (pin length)

    const type = NIPinTypeEnum.fourDigits;

      <ViewPinView
        input={TEST_INPUT_VIEW_PIN}
        type={type}
        callback={(
          error: NIErrorResponse | null,
          result: string | null = null
        ) => {
            callback(); // implement your callback
        }}
      />}

or without specifying the type (pin length)

      <ViewPinView
        input={TEST_INPUT_VIEW_PIN}
        callback={(
          error: NIErrorResponse | null,
          result: string | null = null
        ) => {
            callback(); // implement your callback
        }}
      />}

Programatic Interface

The customer application will be responsible to handle the UI part.

Retrieve Card Details

The programmatic interface of the card details will return the card details in the getCardDetailsResult: NIGetCardSuccessResponse object. The card info returned are: Card Number, Expiry Date, CVV and Cardholder Name.

javascript:

    import {
        useGetCardDetails,
        type NIErrorResponse,
    } from '@networkinternational/ni-card-management-sdk';
    
    import { input } from ['path/to/your/object/config'];

  React.useEffect(
    () =>
      onGetCardDetails(
        input,
        (error: NIErrorResponse | null, result: string | null = null) => {
            callback(); // implement your callback
        }
      ),
    []
  );

  const {
    result: getCardDetailsResult,
    error: getCardDetailsError,
    isLoading,
    onGetCardDetails,
  } = useGetCardDetails();

Set PIN

The programmatic interface for the Set PIN functionality will return a success or failure response.

javascript:

    import {
        useSetPin,
        type NIErrorResponse,
    NIThemeEnum,
    } from '@networkinternational/ni-card-management-sdk';
    
    import { input } from ['path/to/your/object/config'];

  const newPin = '1234';

  React.useEffect(
    () =>
      onSetPin(
        newPin,
        input,
        (error: NIErrorResponse | null, result: string | null = null) => {
            callback(); // implement your callback
        }
      ),
    []
  );

  const {
    result: setPinResult,
    error: setPinError,
    isLoading,
    onSetPin,
  } = useSetPin();

Change PIN

The programmatic interface for the Change PIN functionality will return a success or failure response.

javascript:

    import {
        useChangePin,
        type NIErrorResponse,
    } from '@networkinternational/ni-card-management-sdk';
    
    import { input } from ['path/to/your/object/config'];

  const oldPin = '1234';
  const newPin = '7890';

  React.useEffect(
    () =>
      onChangePin(
        oldPin,
        newPin,
        input,
        (error: NIErrorResponse | null, result: string | null = null) => {
            callback(); // implement your callback
        }
      ),
    []
  );

  const {
    result: changePinResult,
    error: changePinError,
    isLoading,
    onChangePin,
  } = useChangePin();

Verify PIN

The programmatic interface for the Verify PIN functionality will return a success or failure response.

javascript:

    import {
        useVerifyPin,
        type NIErrorResponse,
    } from '@networkinternational/ni-card-management-sdk';
    
    import { input } from ['path/to/your/object/config'];

  const pin = '1234';

  React.useEffect(
    () =>
      onVerifyPin(
        pin,
        input,
        (error: NIErrorResponse | null, result: string | null = null) => {
            callback(); // implement your callback
        }
      ),
    []
  );

  const {
    result: verifyPinResult,
    error: verifyPinError,
    isLoading,
    onVerifyPin,
  } = useVerifyPin();

View PIN

The programmatic interface for the View PIN functionality will return in viewPinResult as a String value representing the PIN or failure response.

javascript:

    import {
        useViewPin,
        type NIErrorResponse,
    } from '@networkinternational/ni-card-management-sdk';
    
    import { input } from ['path/to/your/object/config'];

  React.useEffect(
    () =>
      onViewPin(
        input,
        (error: NIErrorResponse | null, result: string | null = null) => {
            callback(); // implement your callback
        }
      ),
    []
  );

  const {
    result: viewPinResult,
    error: viewPinError,
    isLoading,
    onViewPin,
  } = useViewPin();