react-native-plugpag-nitro

✨ Features

• 🚀 High Performance - Built with Nitro Modules for JSI performance
• 📘 TypeScript First - Complete type safety and IntelliSense support
• ⚡ Real-time Events - Monitor payment status with React hooks
• 💳 Multiple Payment Types - Credit, Debit, Voucher, and PIX support
• 🔄 Transaction Management - Payment, refund, and cancellation support
• 🖨️ Receipt Printing - Integrated thermal receipt printing
• 🛡️ Error Handling - Comprehensive error codes and messages

📦 Installation

npm install react-native-plugpag-nitro react-native-nitro-modules

Requirements

• React Native ≥ 0.72
• Android API ≥ 21
• PagSeguro PlugPag terminal

🚀 Quick Start

import {
  initializeAndActivatePinPad,
  doPayment,
  useTransactionEvent,
  PaymentType,
  ErrorCode
} from 'react-native-plugpag-nitro';

function PaymentScreen() {
  const paymentEvent = useTransactionEvent();

  const handlePayment = async () => {
    // Initialize terminal
    await initializeAndActivatePinPad('YOUR_ACTIVATION_CODE');
    
    // Process payment
    const result = await doPayment({
      amount: 2500, // R$ 25.00 in cents
      type: PaymentType.CREDIT
    });

    if (result.result === ErrorCode.OK) {
      console.log('Payment approved!', result);
    }
  };

  return (
    <View>
      {/* Real-time payment events */}
      {paymentEvent.code > 0 && (
        <Text>Status: {paymentEvent.message}</Text>
      )}
      
      <Button title="Pay R$ 25.00" onPress={handlePayment} />
    </View>
  );
}

📚 API Reference

Core Functions

initializeAndActivatePinPad(activationCode: string)

Initializes and activates the PlugPag terminal.

const result = await initializeAndActivatePinPad('YOUR_ACTIVATION_CODE');
// Returns: { result: ErrorCode, errorCode?: string, errorMessage?: string }

doPayment(options: PaymentOptions)

Process payments with type-safe enums.

interface PaymentOptions {
  amount: number;                    // Amount in cents
  type: PaymentType;                // Payment type enum
  installmentType?: InstallmentType; // Installment type enum
  installments?: number;            // Number of installments (default: 1)
  printReceipt?: boolean;           // Print receipt (default: true)
  userReference?: string;           // User reference (default: auto-generated)
}

const result = await doPayment({
  amount: 2500,                    // Amount in cents
  type: PaymentType.CREDIT,        // CREDIT | DEBIT | VOUCHER | PIX
  installmentType: InstallmentType.BUYER_INSTALLMENT, // Optional
  installments: 3,                 // Optional
  printReceipt: true              // Optional
});

refundPayment(options)

Refunds a previous payment transaction.

const result = await refundPayment({
  transactionCode: 'abc123',
  transactionId: 'def456',
  printReceipt: true
});

React Hooks

useTransactionEvent()

Real-time payment event monitoring hook.

const paymentEvent = useTransactionEvent();
// Returns: { code: number, message: string, customMessage?: string }

useEffect(() => {
  if (paymentEvent.code > 0) {
    console.log('Payment event:', paymentEvent.message);
  }
}, [paymentEvent]);

Utility Functions

// Get terminal serial number
getTerminalSerialNumber(): string

// Get available constants
getConstants(): PlugpagConstants

// Abort current transaction
doAbort(): Promise<PlugpagAbortResult>

// Print custom receipt from file
print(filePath: string): Promise<void>

Type Definitions

enum PaymentType {
  CREDIT = 1,   // Credit card
  DEBIT = 2,    // Debit card
  VOUCHER = 3,  // Voucher/meal card
  PIX = 5       // PIX instant payment
}

enum ErrorCode {
  OK = 0,                    // Success
  OPERATION_ABORTED = -1,    // Operation aborted
  COMMUNICATION_ERROR = -3,  // Connection error
  // ... more error codes
}

enum InstallmentType {
  NO_INSTALLMENT = 1,        // No installment
  BUYER_INSTALLMENT = 2,     // Buyer pays installment fee
  SELLER_INSTALLMENT = 3     // Seller pays installment fee
}

🎨 UI Customization & Theming

Customize the appearance of PagBank SDK modal dialogs to match your app's design. The library provides complete control over colors, themes, and UI elements displayed during payment transactions.

⚡ Quick Theme Setup

import { setStyleTheme } from 'react-native-plugpag-nitro';

// Create and apply a custom theme
await setStyleTheme({
  headBackgroundColor: '#1A1A1D',     // Header background
  headTextColor: '#FFFFFF',           // Header text
  positiveButtonBackground: '#22C55E', // "Confirm" button color  
  negativeButtonBackground: '#EF4444', // "Cancel" button color
  contentTextColor: '#FFFFFF',        // Body text color
  lineColor: '#71717A'               // Borders and lines
});

🛠️ Custom Theme Creation

Create themes that match your app's design system:

// Create a custom brand-based theme
const customTheme = {
  headBackgroundColor: '#00D4FF',      // Your primary brand color
  headTextColor: '#FFFFFF',            // White text on colored header
  contentTextColor: '#1A1A1D',         // Dark text for body content
  positiveButtonBackground: '#00D4FF',  // Consistent brand color
  negativeButtonBackground: '#EF4444',  // Standard red for cancel
  lineColor: '#E5E7EB'                 // Light gray for borders
};

await setStyleTheme(customTheme);

🎨 Complete Style Properties

interface PlugpagStyleData {
  // Header styling
  headTextColor?: string;              // Header text color
  headBackgroundColor?: string;        // Header background color
  
  // Content styling  
  contentTextColor?: string;           // General content text
  contentTextValue1Color?: string;     // Primary monetary values
  contentTextValue2Color?: string;     // Secondary monetary values
  
  // Button styling
  positiveButtonTextColor?: string;    // Confirm button text
  positiveButtonBackground?: string;   // Confirm button background
  negativeButtonTextColor?: string;    // Cancel button text  
  negativeButtonBackground?: string;   // Cancel button background
  genericButtonBackground?: string;    // Generic button background
  genericButtonTextColor?: string;     // Generic button text
  
  // Input field styling
  genericSmsEditTextBackground?: string; // SMS input background
  genericSmsEditTextTextColor?: string;  // SMS input text
  
  // Interface elements
  lineColor?: string;                  // Lines, borders, dividers
}

🔧 Theme Utilities

import { ThemeUtils } from 'react-native-plugpag-nitro';

// Validate theme colors
const errors = ThemeUtils.validateTheme(myTheme);
if (errors.length === 0) {
  await setStyleTheme(myTheme);
}

// Merge themes
const customizedTheme = ThemeUtils.mergeThemes(
  baseTheme,  // Your base theme
  { positiveButtonBackground: '#FF6B6B' }
);

// Preview theme colors (for debugging)
const preview = ThemeUtils.createThemePreview(myTheme);
console.log(preview); // { headBackgroundColor: '#1A1A1D', ... }

💡 Best Practices

• Apply early: Set themes during app initialization, before payment operations
• Match your design: Use colors that complement your existing UI
• Accessibility: Ensure sufficient contrast between text and backgrounds
• Validation: Always validate themes before applying them
• Error handling: Wrap theme operations in try-catch blocks

🏗️ Integration Example

import React, { useEffect } from 'react';
import { setStyleTheme } from 'react-native-plugpag-nitro';

export default function App() {
  useEffect(() => {
    // Apply theme matching your app's design
    const initializeTheme = async () => {
      try {
        const customTheme = {
          headBackgroundColor: '#1A1A1D',
          headTextColor: '#FFFFFF',
          positiveButtonBackground: '#22C55E',
          negativeButtonBackground: '#EF4444'
        };
        
        await setStyleTheme(customTheme);
        console.log('Theme applied successfully');
      } catch (error) {
        console.error('Failed to apply theme:', error);
      }
    };
    
    initializeTheme();
  }, []);

  // ... rest of your app
}

📖 Complete styling guide: See STYLING_GUIDE.md for detailed documentation and examples.

💡 Usage Examples

Complete Payment Flow

import React, { useState, useEffect } from 'react';
import {
  PaymentType,
  ErrorCode,
  doPayment,
  useTransactionEvent,
  initializeAndActivatePinPad
} from 'react-native-plugpag-nitro';

function PaymentScreen() {
  const [isInitialized, setIsInitialized] = useState(false);
  const [isProcessing, setIsProcessing] = useState(false);
  const paymentEvent = useTransactionEvent();

  // Initialize terminal on mount
  useEffect(() => {
    const initialize = async () => {
      try {
        const result = await initializeAndActivatePinPad('YOUR_ACTIVATION_CODE');
        if (result.result === ErrorCode.OK) {
          setIsInitialized(true);
        }
      } catch (error) {
        console.error('Initialization failed:', error);
      }
    };
    
    initialize();
  }, []);

  const handleCreditPayment = async () => {
    if (!isInitialized) {
      Alert.alert('Error', 'Terminal not initialized');
      return;
    }

    try {
      setIsProcessing(true);
      const result = await doPayment({ 
        amount: 2500, 
        type: PaymentType.CREDIT 
      });

      if (result.result === ErrorCode.OK) {
        Alert.alert('Success', 'Payment approved!');
      } else {
        Alert.alert('Failed', result.message || 'Payment failed');
      }
    } catch (error) {
      Alert.alert('Error', error.message);
    } finally {
      setIsProcessing(false);
    }
  };

  return (
    <View style={{ padding: 20 }}>
      <Text>Terminal: {isInitialized ? '✅ Ready' : '❌ Not Ready'}</Text>
      
      {/* Real-time Event Display */}
      {paymentEvent.code > 0 && (
        <View style={{ padding: 10, backgroundColor: '#e3f2fd', marginVertical: 10 }}>
          <Text>Status: {paymentEvent.message}</Text>
          <Text>Code: {paymentEvent.code}</Text>
        </View>
      )}
      
      <Button 
        title="Credit Card R$ 25.00"
        onPress={handleCreditPayment}
        disabled={!isInitialized || isProcessing}
      />
    </View>
  );
}

⚠️ Error Handling

import { ErrorCode, doPayment, PaymentType } from 'react-native-plugpag-nitro';

try {
  const result = await doPayment({ amount: 2500, type: PaymentType.CREDIT });
  
  if (result.result !== ErrorCode.OK) {
    // Handle specific errors
    switch (result.result) {
      case ErrorCode.OPERATION_ABORTED:
        console.log('Payment cancelled by user');
        break;
      case ErrorCode.COMMUNICATION_ERROR:
        console.log('Connection error - check terminal');
        break;
      default:
        console.log('Payment failed:', result.message);
    }
    return;
  }
  
  console.log('Payment successful!', result);
} catch (error) {
  console.error('Payment error:', error.message);
}

🛠️ Development

# Clone the repository
git clone https://github.com/mCodex/react-native-plugpag-nitro.git
cd react-native-plugpag-nitro

# Install dependencies
yarn install

# Setup the example project
yarn example android

🤝 Contributing

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

� License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• 📚 Nitro Modules Documentation
• 🏢 PagSeguro PlugPag Official Docs
• 🐛 Report Issues
• � Discussions