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 zips-typescript-sdk@1.1.5 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

``bash


Install latest version

npm install zips-react-native-sdk-test@latest

Or install specific version

npm install zips-react-native-sdk-test
`

$3

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

📱 Quick Start

`tsx
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 (
apiKey="your-api-key"
paymentDetails={paymentDetails}
onSuccess={(transaction) => {
console.log('Payment successful:', transaction);
}}
onError={(error) => {
console.error('Payment failed:', error);
}}
/>
);
}
`

🎨 Customization

$3

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

$3

`tsx
// Use your own button content
apiKey="your-api-key"
paymentDetails={paymentDetails}
onSuccess={handleSuccess}
onError={handleError}
>



Pay with ZIPS



`

📚 API Reference

$3

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

$3

`tsx
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
}
`

$3

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

🔧 Environment Setup

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

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

🔍 Error Handling

`tsx
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.

$3

`bash
npm install zips-typescript-sdk@latest
`

$3

`typescript
// 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,
});
}
});
`

$3

`tsx
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);
}}
/>
`

$3

`typescript
// 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'
);
}
}
`

$3

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: dev@zips.gm
- Documentation: https://docs.zips.gm

📄 License

MIT License - see LICENSE file for details.

---

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