React Native Payvessel

A React Native SDK for integrating Payvessel Payment Gateway into your mobile app. Built with TypeScript for type safety and similar API to the npm package.

Features

• 🚀 Simple API - Similar to the npm package payvessel-checkout
• 💳 Multiple Channels - Bank Transfer and Card payments
• 📱 Modal Checkout - Full-screen WebView modal
• 🔄 Callbacks - onSuccess, onError, onClose support
• 🪝 React Hook - usePayvessel hook for easy state management
• 📝 TypeScript - Full TypeScript support with type definitions

Installation

npm install react-native-payvessel react-native-webview
# or
yarn add react-native-payvessel react-native-webview

iOS Setup

cd ios && pod install

Android Setup

No additional setup required.

Usage

Basic Usage with Component

import React, { useState } from 'react';
import { View, Button } from 'react-native';
import PayvesselCheckout from 'react-native-payvessel';

const App = () => {
  const [showCheckout, setShowCheckout] = useState(false);

  return (
    <View style={{ flex: 1 }}>
      <Button 
        title="Pay with Payvessel" 
        onPress={() => setShowCheckout(true)} 
      />

      <PayvesselCheckout
        visible={showCheckout}
        apiKey="YOUR_API_KEY"
        customerEmail="[email protected]"
        customerPhoneNumber="08012345678"
        amount={1000}
        currency="NGN"
        customerName="John Doe"
        channels={['BANK_TRANSFER', 'CARD']}
        metadata={{ order_id: '12345' }}
        onSuccess={(result) => {
          console.log('Payment successful:', result);
          setShowCheckout(false);
        }}
        onError={(error) => {
          console.log('Payment error:', error);
        }}
        onClose={() => {
          console.log('Checkout closed');
          setShowCheckout(false);
        }}
      />
    </View>
  );
};

export default App;

Using the Hook

import React from 'react';
import { View, Button } from 'react-native';
import { PayvesselCheckout, usePayvessel } from 'react-native-payvessel';

const App = () => {
  const { openCheckout, checkoutProps } = usePayvessel({
    apiKey: 'YOUR_API_KEY',
    onSuccess: (result) => {
      console.log('Payment successful:', result);
    },
    onError: (error) => {
      console.log('Payment error:', error);
    },
    onClose: () => {
      console.log('Checkout closed');
    },
  });

  const handlePayment = () => {
    openCheckout({
      email: '[email protected]',
      phoneNumber: '08012345678',
      amount: 1000,
      currency: 'NGN',
      name: 'John Doe',
      channels: ['BANK_TRANSFER', 'CARD'],
      metadata: { order_id: '12345' },
    });
  };

  return (
    <View style={{ flex: 1 }}>
      <Button title="Pay with Payvessel" onPress={handlePayment} />
      {checkoutProps && <PayvesselCheckout {...checkoutProps} />}
    </View>
  );
};

export default App;

Props

PayvesselCheckout

| Prop | Type | Required | Description | |------|------|----------|-------------| | visible | boolean | ✅ | Whether the checkout modal is visible | | apiKey | string | ✅ | Your Payvessel API key | | customerEmail | string | ✅ | Customer's email | | customerPhoneNumber | string | ✅ | Customer's phone number | | amount | string | ✅ | Amount to charge (e.g., "1000") | | currency | string | ❌ | Currency code (default: "NGN") | | customerName | string | ✅ | Customer's full name | | channels | string[] | ❌ | Payment channels (default: ["BANK_TRANSFER"]) | | metadata | object | ❌ | Custom metadata | | reference | string | ❌ | Unique transaction reference | | redirectUrl | string | ❌ | URL to redirect after payment | | onSuccess | function | ❌ | Called on successful payment | | onError | function | ❌ | Called on payment error | | onClose | function | ❌ | Called when checkout is closed | | showHeader | boolean | ❌ | Show header (default: true) | | headerTitle | string | ❌ | Header title (default: "Checkout") |

usePayvessel Hook

const {
  isVisible,      // boolean - checkout visibility
  isLoading,      // boolean - loading state
  error,          // string | null - error message
  transactionData, // TransactionData | null - transaction data
  openCheckout,   // (params: CheckoutParams) => void - open checkout
  closeCheckout,  // () => void - close checkout
  resetError,     // () => void - reset error state
  checkoutProps,  // CheckoutProps | null - props to spread on component
} = usePayvessel({
  apiKey: 'YOUR_API_KEY',
  onSuccess: (result) => {},
  onError: (error) => {},
  onClose: () => {},
});

Types

import { 
  PaymentStatus, 
  PaymentChannel,
  CheckoutParams,
  PayvesselSuccessResponse,
  PayvesselErrorResponse,
} from 'react-native-payvessel';

// Payment Status Enum
enum PaymentStatus {
  SUCCESS = 'success',
  FAILED = 'failed',
  CANCELLED = 'cancelled',
  PENDING = 'pending',
}

// Payment Channel Enum
enum PaymentChannel {
  BANK_TRANSFER = 'BANK_TRANSFER',
  CARD = 'CARD',
}

Payment Channels

import { PaymentChannel } from 'react-native-payvessel';

// Use in channels prop
<PayvesselCheckout
  channels={[PaymentChannel.BANK_TRANSFER, PaymentChannel.CARD]}
  // ... other props
/>

Result Objects

// Success Response
interface PayvesselSuccessResponse {
  status: 'success';
  reference?: string;
  transactionId?: string;
  accessCode?: string;
  paymentId?: string;
  data?: TransactionData;
}

// Error Response
interface PayvesselErrorResponse {
  status: 'failed';
  message: string;
  code?: string;
}

Comparison with npm Package

| npm Package | React Native SDK | |-------------|------------------| | Checkout({ api_key }) | <PayvesselCheckout apiKey="..." /> | | initializeCheckout({ ... }) | Props on component | | onSuccess | onSuccess prop | | onError | onError prop | | onClose | onClose prop |

Example App

See the example directory for a complete sample app.

License

MIT License - see LICENSE for details.