X-Pay React Native SDK

Official React Native SDK for X-Pay payment gateway integration. Accept payments from multiple providers (Cards via Stripe, Mobile Money, Orange Money, X-Pay Wallet) with a unified API and beautiful pre-built UI components.

Features

• Single Payment Widget - One component handles all payment methods, just like Stripe/Flutterwave
• Secure Card Payments - PCI DSS compliant, powered by Stripe (bundled inside)
• Simple Integration - Just one SDK to install, no need to install Stripe or other payment SDKs separately
• Beautiful Pre-Built UI - Professional payment modal with all payment methods
• Multi-Currency - Support for USD, LRD, NGN, UGX, RWF, GHS, and more
• Multiple Payment Methods - Cards, Mobile Money, Orange Money, X-Pay Wallets
• Public Key Only - Client-side SDK uses public keys (pk_), never secret keys
• TypeScript - Full TypeScript support with comprehensive type definitions
• Payment Gateway Abstraction - Integrate once, accept payments from multiple providers

Installation

npm install @bits-innovate/xpay-react-native

Note: You do NOT need to install Stripe or any other payment SDK separately. Everything is bundled in @bits-innovate/xpay-react-native.

Quick Start

1. Get Your Public Key

Sign up at X-Pay Dashboard and get your public key:

• Sandbox: pk_sandbox_xxx (for testing)
• Live: pk_live_xxx (for production)

2. Wrap Your App with XPayProvider

import { XPayProvider } from '@bits-innovate/xpay-react-native';

export default function App() {
  return (
    <XPayProvider
      publicKey="pk_sandbox_xxx"
      environment="sandbox"
    >
      <YourApp />
    </XPayProvider>
  );
}

Important:

• Use ONLY XPayProvider. Do not import or use StripeProvider - Stripe is bundled inside.
• You do NOT provide Stripe keys - X-Pay handles card payments with its own Stripe account.

3. Accept Payments (Recommended Approach)

The easiest way - show a payment button that opens X-Pay's payment modal:

import React, { useState } from 'react';
import { View, Text, TouchableOpacity } from 'react-native';
import { XPayPaymentSheet } from '@bits-innovate/xpay-react-native';

function CheckoutScreen() {
  const [showPayment, setShowPayment] = useState(false);

  const handlePaymentSuccess = async (payment) => {
    console.log('Payment successful!', payment);

    // Now create your order on your backend
    await fetch('https://your-backend.com/api/orders', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        paymentId: payment.id,
        items: [...],
        customer: {...},
      }),
    });

    // Navigate to success screen
    navigation.navigate('OrderSuccess');
  };

  return (
    <View>
      <Text>Total: $50.00</Text>

      <TouchableOpacity onPress={() => setShowPayment(true)}>
        <Text>Pay Now</Text>
      </TouchableOpacity>

      <XPayPaymentSheet
        visible={showPayment}
        amount={5000}
        currency="USD"
        merchantId="your_merchant_id"
        description="Coffee Shop Order"
        customer={{
          email: '[email protected]',
          name: 'John Doe',
        }}
        onSuccess={handlePaymentSuccess}
        onError={(error) => console.error('Payment failed:', error)}
        onDismiss={() => setShowPayment(false)}
      />
    </View>
  );
}

That's it! The XPayPaymentSheet component:

• Automatically loads all available payment methods from X-Pay
• Shows beautiful UI for method selection and payment input
• Handles payment processing with X-Pay backend
• Returns success/error - you handle order creation

Payment Flow

┌─────────────┐
│   User      │
│ Clicks Pay  │
└──────┬──────┘
       │
       ▼
┌──────────────────┐
│ XPayPaymentSheet │ ◄── Handles EVERYTHING
│  Opens Modal     │     (methods, input, processing)
└──────┬───────────┘
       │
       ▼
┌──────────────────┐
│   X-Pay Backend  │ ◄── Processes payment
│  Returns Success │     (Stripe/MoMo/Orange/Wallet)
└──────┬───────────┘
       │
       ▼
┌──────────────────┐
│ Your Backend     │ ◄── Create order AFTER payment succeeds
│ Creates Order    │
└──────────────────┘

Key Points:

• X-Pay handles payment processing - you get success/error callback
• X-Pay has nothing to do with your orders - that's your backend's job
• On payment success, create order on your backend with the payment ID
• Simple and clean separation of concerns

API Reference

XPayPaymentSheet (RECOMMENDED)

Complete payment modal that handles all payment methods.

Props:

• visible (boolean, required) - Whether the payment sheet is visible
• amount (number, required) - Amount in minor units (cents, e.g., 5000 = $50.00)
• currency (string, required) - Currency code (USD, LRD, etc.)
• merchantId (string, required) - Your merchant ID from X-Pay dashboard
• description (string, optional) - Payment description
• customer (object, optional) - Customer info { email, name }
• metadata (object, optional) - Custom metadata to attach to payment
• onSuccess (function, required) - Called with payment object when payment succeeds
• onError (function, required) - Called with error when payment fails
• onDismiss (function, required) - Called when user closes the sheet

Example:

<XPayPaymentSheet
  visible={showPayment}
  amount={5000}
  currency="USD"
  merchantId="test_merchant_123"
  description="Order #12345"
  customer={{ email: '[email protected]', name: 'John Doe' }}
  metadata={{ orderId: '12345', source: 'mobile_app' }}
  onSuccess={(payment) => {
    console.log('Payment ID:', payment.id);
    console.log('Status:', payment.status); // 'succeeded'
    // Create your order now
  }}
  onError={(error) => {
    console.error('Payment failed:', error.message);
  }}
  onDismiss={() => setShowPayment(false)}
/>

XPayProvider

Main context provider that wraps your app. Handles both X-Pay and Stripe configuration internally using X-Pay's Stripe account.

Props:

• publicKey (string, required) - Your X-Pay public key
• environment ('sandbox' | 'live', optional) - Environment (auto-detected from key)
• merchantIdentifier (string, optional) - Apple Pay merchant identifier (iOS only)
• baseUrl (string, optional) - Custom API base URL

Note: Stripe is configured automatically with X-Pay's credentials. Merchants never provide Stripe keys.

Advanced Components

For custom payment flows, these components are available:

XPayCheckout

Complete checkout flow with customization options.

XPayPaymentMethodSelector

Payment method selection component.

XPayMobileMoneyInput

Mobile Money payment input (Orange Money, MTN MoMo).

XPayWalletInput

X-Pay Wallet payment input.

XPayCardPayment

Card payment component (uses Stripe internally).

See full documentation at https://docs.xpay.com for advanced usage.

Hooks

useXPay

Access X-Pay SDK context.

import { useXPay } from '@bits-innovate/xpay-react-native';

const { config, api, publicKey, environment } = useXPay();

useStripe (Advanced)

Access Stripe hooks for advanced use cases (re-exported from Stripe SDK).

import { useStripe } from '@bits-innovate/xpay-react-native';

const { initPaymentSheet, presentPaymentSheet } = useStripe();

Note: Most developers won't need this - the SDK components handle Stripe internally.

Integration Patterns

Pattern 1: Client-Side Only (Mobile → X-Pay)

// Mobile app calls X-Pay directly
<XPayPaymentSheet
  visible={showPayment}
  amount={5000}
  currency="USD"
  merchantId="merchant_123"
  onSuccess={(payment) => {
    // Payment successful, no backend needed
    console.log('Paid:', payment.id);
  }}
/>

Pattern 2: Hybrid (RECOMMENDED)

// Mobile handles UI, backend creates order after payment
<XPayPaymentSheet
  visible={showPayment}
  amount={5000}
  currency="USD"
  merchantId="merchant_123"
  onSuccess={async (payment) => {
    // Payment successful, now create order on your backend
    await createOrder(payment.id);
  }}
/>

Pattern 3: Server-Side Only

// Your backend calls X-Pay API, mobile shows custom UI
// Use X-Pay backend SDK (Node.js, Go, PHP, etc.)

Security

• PCI DSS Compliance - Card data handled by Stripe, never touches your servers
• Public Key Only - Mobile app uses public key, secret key stays on backend
• Secure Communication - All API calls use HTTPS
• Token-Based - Card tokens are single-use and expire
• PIN Encryption - Wallet PINs are encrypted in transit

Platform Support

• iOS 12.0+
• Android API 21+ (Android 5.0+)
• Expo compatible
• TypeScript supported

Example App

See the example merchant app for a complete implementation showing:

• Coffee shop mobile app with shopping cart
• XPayPaymentSheet integration
• Order creation after payment success
• All payment methods (Cards, Mobile Money, Orange Money, Wallet)

Troubleshooting

"Cannot find module '@stripe/stripe-react-native'"

You don't need to install Stripe separately. The SDK bundles it internally. Just install @bits-innovate/xpay-react-native.

"Invalid publishable key"

Make sure you're using your X-Pay public key (pk_sandbox_xxx or pk_live_xxx), NOT a Stripe key. X-Pay manages Stripe credentials internally.

Payment methods not showing

Ensure your merchant account is configured in X-Pay dashboard with the payment methods you want to accept.

Support

• Documentation: https://docs.xpay.com
• Email: [email protected]
• GitHub Issues: https://github.com/x-pay/x-pay/issues

License

MIT