ZIPS React Native SDK

A lightweight React Native SDK for integrating ZIPS payment gateway into your mobile applications.

Latest Version: v2.3.42 - Enhanced with improved loading states, account name masking for security, and upgraded TypeScript SDK integration.

🆕 Latest Features (v2.3.42)

• 🔄 Enhanced Loading States: Improved opacity-based loading with 0.5 opacity and disabled button states
• 🔐 Account Name Masking: Security feature to prevent account enumeration (e.g., "Steps Keita" → "S. Keita")
• 🔍 Enhanced Debugging: Comprehensive console logging for better development experience
• ⚡ TypeScript SDK Integration: Updated to use latest [email protected] for improved reliability
• 🎨 Better UX: Enhanced visual feedback and interaction patterns across all components
• 🛡️ Privacy Protection: Account name masking prevents security vulnerabilities
• 📱 Improved Components: Enhanced PaymentButton, AccountDetails, BankAccountInput, and OTPVerification
• 🏦 Access Bank Support: Focused integration with Access Bank Gambia
• 💰 ZApp Wallet: Streamlined ZApp digital wallet payment integration

✨ Features

• 🚀 Easy Integration: Simple drop-in component
• � ZApp Wallet Payments: Secure ZApp digital wallet integration
• 🏦 Access Bank Support: Seamless integration with Access Bank Gambia
• 🎨 Fully Customizable: Style however you want
• 📱 Native UX: Smooth animations and modal management
• 🛡️ Secure Processing: Bank-grade security with account name masking
• 📊 TypeScript Support: Full type safety
• 🔄 Enhanced Loading States: Opacity-based loading with disabled button states
• 🔍 Enhanced Debugging: Comprehensive console logging for development
• 🔐 Privacy Protection: Account name masking to prevent enumeration attacks

🚀 Installation

# Install latest version
npm install zips-react-native-sdk-test@latest

# Or install specific version
npm install zips-react-native-sdk-test

Requirements

• React Native >= 0.68.0
• React >= 16.8.0
• Node.js >= 16.0.0
• TypeScript >= 4.5.0 (for TypeScript projects)

📱 Quick Start

import React from 'react';
import { PaymentButton } from 'zips-react-native-sdk-test';

function App() {
  const paymentDetails = {
    name: 'Premium Service',
    quantity: 1,
    amount: 100,
    description: 'Payment for premium service',
    projectId: 'your-project-id',
    currency: 'GMD',
    country: 'The Gambia',
    firstName: 'John',
    lastName: 'Doe',
    phoneNumber: '2207001234',
    merchantAccountId: 'your-merchant-account-id',
  };

  return (
    <PaymentButton
      apiKey="your-api-key"
      paymentDetails={paymentDetails}
      onSuccess={(transaction) => {
        console.log('Payment successful:', transaction);
      }}
      onError={(error) => {
        console.error('Payment failed:', error);
      }}
    />
  );
}

🎨 Customization

Custom Styling

// Style the button however you want
<PaymentButton
  style={{
    backgroundColor: '#FF6B35',
    borderRadius: 25,
    paddingHorizontal: 30,
    paddingVertical: 15,
  }}
  apiKey="your-api-key"
  paymentDetails={paymentDetails}
  onSuccess={handleSuccess}
  onError={handleError}
/>

Custom Content

// Use your own button content
<PaymentButton
  apiKey="your-api-key"
  paymentDetails={paymentDetails}
  onSuccess={handleSuccess}
  onError={handleError}
>
  <View style={{ flexDirection: 'row', alignItems: 'center' }}>
    <Icon name="credit-card" size={20} color="#fff" />
    <Text style={{ marginLeft: 8, color: '#fff', fontWeight: 'bold' }}>
      Pay with ZIPS
    </Text>
  </View>
</PaymentButton>

📚 API Reference

PaymentButton Props

| Prop | Type | Required | Description | | ---------------- | ------------------------------------ | -------- | -------------------------------- | | apiKey | string | ✅ | Your ZIPS API key | | paymentDetails | PaymentDetails | ✅ | Payment information | | onSuccess | (transaction: Transaction) => void | ✅ | Success callback | | onError | (error: PaymentError) => void | ✅ | Error callback | | buttonText | string | ❌ | Button text (default: "Pay Now") | | environment | 'sandbox' \| 'production' | ❌ | Environment (default: "sandbox") | | style | ViewStyle | ❌ | Custom TouchableOpacity styles | | children | React.ReactNode | ❌ | Custom button content |

PaymentDetails Interface

interface PaymentDetails {
  name: string; // Product/service name
  quantity: number; // Item quantity
  amount: number; // Amount in minor units
  description: string; // Payment description
  projectId: string; // Your project ID
  currency: string; // Currency code (GMD)
  country: string; // Country name
  firstName: string; // Customer first name
  lastName: string; // Customer last name
  phoneNumber: string; // Customer phone number
  merchantAccountId: string; // Your merchant account ID
}

Transaction Response

interface Transaction {
  id: string;
  amount: number;
  currency: string;
  status: 'success' | 'failed' | 'pending';
  timestamp: string;
  reference: string;
  // ... other transaction details
}

🔧 Environment Setup

// Sandbox mode (default)
<PaymentButton
  apiKey="sandbox_key_here"
  environment="sandbox"
  paymentDetails={paymentDetails}
  onSuccess={handleSuccess}
  onError={handleError}
/>

// Production mode
<PaymentButton
  apiKey="production_key_here"
  environment="production"
  paymentDetails={paymentDetails}
  onSuccess={handleSuccess}
  onError={handleError}
/>

🔍 Error Handling

<PaymentButton
  apiKey="your-api-key"
  paymentDetails={paymentDetails}
  onSuccess={(transaction) => {
    // Handle successful payment
    console.log('Payment successful:', transaction);
  }}
  onError={(error) => {
    // Handle payment errors
    switch (error.code) {
      case 'INSUFFICIENT_FUNDS':
        Alert.alert('Insufficient Funds', 'Please check your balance.');
        break;
      case 'INVALID_OTP':
        Alert.alert('Invalid OTP', 'Please check the OTP.');
        break;
      case 'NETWORK_ERROR':
        Alert.alert('Network Error', 'Please check your connection.');
        break;
      default:
        Alert.alert('Payment Error', error.message);
    }
  }}
/>

🛡️ Backend Transaction Verification

For security reasons, it's highly recommended to verify transactions on your backend server. The React Native SDK returns transaction data in the onSuccess callback, but you should always verify this on your server.

Step 1: Install ZIPS TypeScript SDK on your backend

npm install zips-typescript-sdk@latest

Step 2: Set up transaction verification endpoint

// backend/routes/payment.ts
import Zips from 'zips-typescript-sdk';

const zips = new Zips(process.env.ZIPS_API_KEY);

app.post('/verify-payment', async (req, res) => {
  try {
    const { reference } = req.body;

    // Verify transaction with ZIPS
    const transaction = await zips.transactions.single(reference);

    if (transaction.data.status === 'success') {
      // Update your database
      await updateOrderStatus(reference, 'completed');

      res.json({
        success: true,
        verified: true,
        transaction: transaction.data,
      });
    } else {
      res.json({
        success: false,
        verified: false,
        message: 'Transaction not successful',
      });
    }
  } catch (error) {
    res.status(500).json({
      success: false,
      error: error.message,
    });
  }
});

Step 3: Handle onSuccess in your React Native app

<PaymentButton
  apiKey="your-api-key"
  paymentDetails={paymentDetails}
  onSuccess={async (transaction) => {
    console.log('Frontend transaction data:', transaction);

    // Transaction object structure:
    // {
    //   "amount": "100",
    //   "bankName": null,
    //   "country": null,
    //   "createdAt": "2025-08-25T13:59:09.000Z",
    //   "customerAccount": null,
    //   "customerName": null,
    //   "extReference": null,
    //   "feeId": null,
    //   "fees": 50,
    //   "id": "389e5985-9cb1-47bf-a98c-033cf0cc951c",
    //   "isSettled": null,
    //   "mandateId": null,
    //   "merchantId": null,
    //   "orderId": "9ac3e46c-a468-407b-bc65-54eba18c0dd8",
    //   "orderName": "Payment Fees",
    //   "paymentDate": "25-08-2025 01:51:23 PM",
    //   "paymentReference": "099MNIP2503405GB",
    //   "paymentStatus": "Success",
    //   "projectId": "91963b0b-0000-4720-a40d-3150eaa35751",
    //   "projectName": "Nget Hub",
    //   "projectTransaction": null,
    //   "purpose": null,
    //   "reference": "742565",
    //   "status": "success",
    //   "updatedAt": "2025-08-25T13:59:09.000Z"
    // }

    try {
      // Send reference to your backend for verification
      const response = await fetch(
        'https://your-backend-api.com/verify-payment',
        {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            Authorization: `Bearer ${userToken}`,
          },
          body: JSON.stringify({
            reference: transaction.reference,
            orderId: transaction.orderId,
            amount: transaction.amount,
          }),
        }
      );

      const verification = await response.json();

      if (verification.verified) {
        // Payment verified successfully
        Alert.alert('Success', 'Payment completed and verified!');
        navigation.navigate('OrderSuccess');
      } else {
        Alert.alert('Verification Failed', 'Please contact support.');
      }
    } catch (error) {
      console.error('Verification error:', error);
      Alert.alert('Error', 'Failed to verify payment. Please contact support.');
    }
  }}
  onError={(error) => {
    console.error('Payment failed:', error);
    Alert.alert('Payment Failed', error.message);
  }}
/>

Step 4: TypeScript SDK Transaction Verification

// backend/services/transactionService.ts
import Zips from 'zips-typescript-sdk';

class TransactionService {
  private zips: Zips;

  constructor(apiKey: string) {
    this.zips = new Zips(apiKey);
  }

  async verifyTransaction(reference: string) {
    try {
      const transaction = await this.zips.transactions.single(reference);

      // Verify transaction details
      const isValid = this.validateTransaction(transaction.data);

      return {
        isValid,
        status: transaction.data.status,
        amount: transaction.data.amount,
        reference: transaction.data.reference,
        paymentDate: transaction.data.paymentDate,
        isSettled: transaction.data.isSettled,
      };
    } catch (error) {
      throw new Error(`Transaction verification failed: ${error.message}`);
    }
  }

  private validateTransaction(transaction: any): boolean {
    // Add your validation logic here
    return (
      transaction.status === 'success' &&
      transaction.paymentStatus === 'Success'
    );
  }
}

Security Best Practices

1. Never trust frontend data alone - Always verify transactions on your backend
2. Use the reference field - This is the unique identifier for verification
3. Check transaction status - Verify both status and paymentStatus fields
4. Validate amounts - Ensure the amount matches your expected payment
5. Store verification results - Keep records of verified transactions in your database
6. Handle edge cases - Account for network failures and retry mechanisms

🏦 Supported Banks

The SDK currently supports:

• Access Bank Gambia Limited: Full netbanking integration with account verification and OTP authentication

More banks will be added in future releases.

📊 Payment Flow

1. User taps the PaymentButton
2. Modal opens with payment method selection (Netbanking or ZApp Wallet)
3. For Netbanking: User selects Access Bank → Account verification → OTP process → Payment confirmation
4. For ZApp Wallet: User enters wallet details → PIN verification → Payment confirmation
5. Payment processed and confirmed
6. Success/error callback triggered

📋 Requirements

• React Native >= 0.68.0
• React >= 16.8.0

🔐 Security

• All communications use HTTPS encryption
• No sensitive data stored locally
• PCI DSS compliant payment processing
• Bank-grade security standards

🤝 Support

For technical support:

• Email: [email protected]
• Documentation: https://docs.zips.gm

📄 License

MIT License - see LICENSE file for details.

Made with ❤️ by the ZIPS Team for Gambian fintech innovation.