react-native-payplus-sdk

A modern React Native SDK for PayPlus payment gateway integration, built with the new architecture (Turbo Modules & Fabric). Supports both iOS and Android platforms with a seamless payment experience including 3DS authentication.

Features

✅ React Native New Architecture support
✅ TypeScript-first with complete type definitions
✅ iOS and Android support
✅ Sandbox and production environments
✅ Simple, intuitive API

Requirements

• React Native >= 0.70
• iOS >= 13.0
• Android minSdkVersion >= 21

Installation

1. Install the package

npm install react-native-payplus-sdk
# or
yarn add react-native-payplus-sdk

2. Install iOS dependencies

cd ios && pod install && cd ..

3. iOS Configuration

Open ios/<YourApp>/Info.plist and add the following to allow 3DS authentication:

<key>LSApplicationQueriesSchemes</key>
<array>
  <string>about</string>
  <string>http</string>
  <string>https</string>
</array>

This is required for 3DS authentication screens to work properly on iOS.

4. Android Configuration

No additional configuration needed. The SDK automatically integrates with your Android project.

Usage

Basic Implementation

import React, { useState } from 'react';
import { View, Button } from 'react-native';
import { PayPlusCheckout } from 'react-native-payplus-sdk';
import type { PayPlusConfig, PayPlusResult } from 'react-native-payplus-sdk';

export default function App() {
  const [isVisible, setIsVisible] = useState(false);

  // Configure your PayPlus credentials
  const config: PayPlusConfig = {
    merchantId: 'YOUR_MERCHANT_ID',
    secretKey: 'YOUR_SECRET_KEY',
    isSandbox: true, // Set to false for production
  };

  // Payment details
  const details = {
    orderId: `ORD-${Date.now()}`, // Unique order ID
    amount: 100.00,
    currency: 'LKR',
    firstName: 'John',
    lastName: 'Doe',
    email: '[email protected]',
    phone: '771234567',
    description: 'Payment for Order #123',
  };

  const handlePaymentResult = (result: PayPlusResult) => {
    if (result.status === 'SUCCESS') {
      console.log('Payment successful!', result);
      // Handle successful payment
    } else if (result.status === 'FAILED') {
      console.log('Payment failed:', result.message);
      // Handle failed payment
    } else {
      console.log('Payment cancelled');
      // Handle cancelled payment
    }
  };

  return (
    <View style={{ flex: 1, justifyContent: 'center', padding: 20 }}>
      <Button title="Pay Now" onPress={() => setIsVisible(true)} />

      <PayPlusCheckout
        isVisible={isVisible}
        config={config}
        details={details}
        onClose={() => setIsVisible(false)}
        onResult={handlePaymentResult}
      />
    </View>
  );
}

API Reference

PayPlusCheckout Component

The main component for handling PayPlus payments.

Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | isVisible | boolean | ✅ | Controls the visibility of the payment modal | | config | PayPlusConfig | ✅ | PayPlus configuration object | | details | PaymentDetails | ✅ | Payment details object | | onClose | () => void | ✅ | Callback when the modal is closed | | onResult | (result: PayPlusResult) => void | ✅ | Callback with payment result |

Types

PayPlusConfig

interface PayPlusConfig {
  merchantId: string;   // Your PayPlus merchant ID
  secretKey: string;    // Your PayPlus secret key
  isSandbox?: boolean;  // Optional: true for sandbox, false for production (default: false)
}

PaymentDetails

interface PaymentDetails {
  orderId: string;      // Unique order identifier
  amount: number;       // Payment amount (e.g., 100.00)
  currency: string;     // Currency code (e.g., 'LKR')
  firstName: string;    // Customer's first name
  lastName: string;     // Customer's last name
  email: string;        // Customer's email address
  phone: string;        // Customer's phone number
  description: string;  // Payment description
}

PayPlusResult

interface PayPlusResult {
  status: 'SUCCESS' | 'FAILED' | 'CANCELLED';
  message: string;
  transactionId?: string;  // Available on successful payment
  amount?: string;         // Available on successful payment
  currency?: string;       // Available on successful payment
}

Advanced Usage

Dynamic Payment Amounts

const [amount, setAmount] = useState('100.00');

const details = {
  orderId: `ORD-${Date.now()}`,
  amount: parseFloat(amount),
  currency: 'LKR',
  // ... other details
};

Handling Different Payment Statuses

const handlePaymentResult = (result: PayPlusResult) => {
  switch (result.status) {
    case 'SUCCESS':
      Alert.alert(
        'Success', 
        `Payment successful! Transaction ID: ${result.transactionId}`
      );
      // Update order status, navigate to success screen, etc.
      break;
      
    case 'FAILED':
      Alert.alert('Failed', result.message);
      // Show retry option or contact support
      break;
      
    case 'CANCELLED':
      Alert.alert('Cancelled', 'Payment was cancelled by user');
      // Return to cart or order summary
      break;
  }
};

Environment Switching

const isDevelopment = __DEV__;

const config: PayPlusConfig = {
  merchantId: isDevelopment 
    ? 'SANDBOX_MERCHANT_ID' 
    : 'PRODUCTION_MERCHANT_ID',
  secretKey: isDevelopment 
    ? 'SANDBOX_SECRET_KEY' 
    : 'PRODUCTION_SECRET_KEY',
  isSandbox: isDevelopment,
};

Testing

Sandbox Mode

Use isSandbox: true in your config to test payments without real transactions:

const config: PayPlusConfig = {
  merchantId: 'YOUR_SANDBOX_MERCHANT_ID',
  secretKey: 'YOUR_SANDBOX_SECRET_KEY',
  isSandbox: true,
};

Test Cards

Contact PayPlus support for test card numbers and credentials for sandbox testing.

Troubleshooting

iOS: 3DS Screen Not Appearing

If the 3DS authentication screen doesn't load on iOS, ensure you've added the URL schemes to your Info.plist:

<key>LSApplicationQueriesSchemes</key>
<array>
  <string>about</string>
  <string>http</string>
  <string>https</string>
</array>

Android: WebView Issues

If you encounter WebView issues on Android, ensure you have the latest version of react-native-webview installed:

npm install react-native-webview@latest

Metro Bundler Cache

If you encounter issues after installation, try clearing the Metro cache:

npx react-native start --reset-cache

Dependencies

This SDK includes the following dependencies:

• react-native-webview - For payment page rendering
• react-native-safe-area-context - For safe area handling
• react-native-vector-icons - For UI icons
• crypto-js - For secure signature generation

These are automatically installed with the SDK.

Security

🔒 Important Security Notes:

• Never commit your production secretKey to version control
• Use environment variables for sensitive credentials
• Always validate payment results on your backend server
• Use HTTPS for all production API calls
• Implement proper error handling and logging

Support

For PayPlus account setup, credentials, or payment gateway issues:

• Email: [email protected]
• Website: https://payplus.lk
• Documentation: https://docs.payplus.lk

For SDK issues or feature requests:

• GitHub Issues: https://github.com/PayMediaSL/react-native-payplus-sdk/issues

Contributing

We welcome contributions! Please see our Contributing Guide for details.

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT

Made with ❤️ by PayMedia (Pvt)Ltd