Echezona React Native SDK

React Native SDK for Echezona Payment Gateway.

Features

• Secure Handling: Encrypted card details using RSA.
• Multiple Payment Methods: Card, Transfer, USSD, OPay.
• Ready-to-use UI: CheckoutModal and CheckoutView components for quick integration.
• Hooks-based: useInitializePayment for triggering the checkout flow.
• Real-time Updates: SignalR integration for transaction status.

Installation

npm install echezona-react-native-sdk

Peer Dependencies

Ensure you have react and react-native installed. For Expo projects, you will also need a storage adapter like expo-secure-store.

Usage

1. Wrap your app in EchezonaProvider

The EchezonaProvider requires a configuration object. You should provide a storage adapter to persist session data.

import {
  EchezonaProvider,
  EchezonaErrorResponse,
  CheckoutModal,
} from "echezona-react-native-sdk";
import * as SecureStore from "expo-secure-store";

// If you are using Expo, you should provide a storage adapter to persist session data.
const expoStorage = {
  getItem: async (key: string) => await SecureStore.getItemAsync(key),
  setItem: async (key: string, value: string) =>
    await SecureStore.setItemAsync(key, value),
  removeItem: async (key: string) => await SecureStore.deleteItemAsync(key),
};

const config = {
  apiKey: "YOUR_API_KEY", // not required if you are using accessCode
  storage: expoStorage, // Required for persistence
  onSuccess: () => {
    console.log("Payment successful");
  },
  onClose: () => {
    console.log("Checkout closed");
  },
  onError: (error: EchezonaErrorResponse) => {
    console.error("Payment Error:", error.responseMessage);
  },
};

export default function App() {
  return (
    <EchezonaProvider config={config}>
      <MainContent />
      {/* Add the Modal component to your root */}
      <CheckoutModal />
    </EchezonaProvider>
  );
}

2. Trigger Payment Flow (Recommended: Access Code)

It is highly recommended to initialize payments on your backend. Once your backend returns an accessCode, pass it to the startCheckout function.

See our API Documentation for more information on how to initialize a payment and generate an access code.

import { useInitializePayment } from "echezona-react-native-sdk";

const MainContent = () => {
  const { startCheckout } = useInitializePayment();

  const handlePay = async () => {
    // 1. Fetch access code from your backend
    const { accessCode } = await myApi.createPayment({ amount: 1000 });

    // 2. Start checkout
    startCheckout(accessCode);
  };

  return <Button title="Pay Now" onPress={handlePay} />;
};

3. Alternative: Client-side Initialization.

You can also initialize payments directly from the client, but this means you must pass your API key to the client, which is less secure.

const { initializePayment } = useInitializePayment();

const handlePay = async () => {
  const payload = {
    email: "[email protected]",
    amount: 0.1,
    currency: "NGN",
    isLive: true,
    phone: "08182426598",
    firstName: "Emino",
    lastName: "Minamino",
    transactionId: `ECHY-RXT-NTV-${Date.now()}`,
    // ... other payload fields
  };

  await initializePayment(payload);
};

Advanced Usage (Headless Hooks)

For custom checkout experiences, you can use our specific hooks for different payment methods.

1. Card Payments (useCardCheckout)

Includes support for encryption, 3DS, and OTP validation.

import { useCardCheckout } from "echezona-react-native-sdk";

const CardPayment = () => {
  const { makeCardPayment, validateCardOtp, cardPage } = useCardCheckout();

  const handlePay = async () => {
    // 1. Initiate payment
    await makeCardPayment({
      cardNumber: "5399...",
      expiryMonth: "12",
      expiryYear: "25",
      cvv: "123",
      pin: "1234"
    });
  };

  const handleOtp = async (otp: string) => {
    // 2. Validate OTP if cardPage is "otp"
    await validateCardOtp(otp);
  };

  return (
    // Your custom UI here
    // Show OTP input if cardPage === "otp"
  );
};

2. Bank Transfers (useTransferCheckout)

Handles virtual account creation and automatic polling for confirmation.

import { useTransferCheckout, PaymentTypes } from "echezona-react-native-sdk";

const TransferPayment = () => {
  const { makeTransferPayment, verifyTransferPayment, validationTimer } = useTransferCheckout();

  const handlePay = async () => {
    const res = await makeTransferPayment({
      paymentType: PaymentTypes.TRANSFER
    });

    if (res?.data) {
      // Start polling for payment confirmation
      verifyTransferPayment();
    }
  };

  return (
    // Display transfer details (bankName, accountNumber)
    // Show remaining time from validationTimer
  );
};

3. USSD Payments (useUssdCheckout)

Handles USSD string generation and confirmation polling.

import { useUssdCheckout } from "echezona-react-native-sdk";

const UssdPayment = () => {
  const { makeUssdPayment, verifyUssdPayment, validationTimer } = useUssdCheckout();

  const handlePay = async () => {
    const ussdString = "*737*...";
    const res = await makeUssdPayment(ussdString);

    if (res) {
      // Start polling for payment confirmation
      verifyUssdPayment();
    }
  };

  return (
    // Display USSD string to user
    // Show remaining time from validationTimer
  );
};

Platform Support

• iOS 13+
• Android API 24+
• Expo / Bare React Native

License

ISC