MONEI Pay React Native SDK

Accept NFC tap-to-pay payments in your React Native app via MONEI Pay.

Built as an Expo module — works with both Expo and bare React Native projects.

Requirements

• React Native 0.73+
• Expo SDK 50+
• iOS 15.0+ / Android 8.0+ (API 26)
• POS auth token from your backend (POST /v1/pos/auth-token)

Installation

npx expo install @monei-pay/react-native

Or with npm/pnpm:

npm install @monei-pay/react-native
# or
pnpm add @monei-pay/react-native

iOS Setup

Add to your app.json or app.config.js:

{
  "expo": {
    "ios": {
      "infoPlist": {
        "LSApplicationQueriesSchemes": ["monei-pay"]
      }
    },
    "scheme": "your-app-scheme"
  }
}

Android Setup

No additional setup needed — the SDK's AndroidManifest includes the required <queries> entries.

Usage

import { useEffect } from 'react';
import { Linking, Platform } from 'react-native';
import * as MoneiPay from '@monei-pay/react-native';

function PaymentScreen() {
  // Wire URL callback handler (iOS only)
  useEffect(() => {
    if (Platform.OS === 'ios') {
      const sub = Linking.addEventListener('url', ({ url }) => {
        MoneiPay.handleCallback(url);
      });
      return () => sub.remove();
    }
  }, []);

  const handlePayment = async () => {
    try {
      const result = await MoneiPay.acceptPayment({
        token: 'eyJ...',              // Raw JWT from your backend
        amount: 1500,                 // Amount in cents (1500 = 15.00 EUR)
        description: 'Order #123',    // Optional
        customerName: 'John Doe',     // Optional
        customerEmail: '[email protected]', // Optional
        callbackScheme: 'your-app',   // iOS only — your registered URL scheme
        mode: 'direct',               // Android only — 'direct' or 'via-monei-pay'
      });

      console.log('Payment approved:', result.transactionId);
      console.log('Card:', result.cardBrand, result.maskedCardNumber);
    } catch (error) {
      console.error('Payment failed:', error.message);
    }
  };

  return <Button title="Pay" onPress={handlePayment} />;
}

API Reference

acceptPayment(params)

Accept an NFC payment. Returns a Promise.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | token | string | Yes | Raw JWT auth token (no "Bearer " prefix) | | amount | number | Yes | Amount in cents | | description | string | No | Payment description | | customerName | string | No | Customer name | | customerEmail | string | No | Customer email | | customerPhone | string | No | Customer phone | | callbackScheme | string | iOS | Your app's registered URL scheme | | mode | string | No | Android: 'direct' (default) or 'via-monei-pay' |

Returns PaymentResult. Throws on failure.

handleCallback(url)

Handle incoming callback URL from MONEI Pay (iOS only). Wire into your Linking handler.

cancelPendingPayment()

Cancel any pending payment.

PaymentResult

| Property | Type | Description | |----------|------|-------------| | transactionId | string | Unique transaction ID | | success | boolean | Whether payment was approved | | amount | number | Amount in cents | | cardBrand | string | Card brand (visa, mastercard, etc.) | | maskedCardNumber | string | Masked card number (****1234) |

Error Codes

| Code | Description | |------|-------------| | NOT_INSTALLED | MONEI Pay or CloudCommerce not on device | | PAYMENT_IN_PROGRESS | Another payment is active | | CANCELLED | User cancelled | | PAYMENT_FAILED | Payment declined/failed | | INVALID_PARAMS | Invalid input parameters | | INVALID_TOKEN | Auth token expired or invalid | | PAYMENT_TIMEOUT | Callback not received in time (iOS) |

Example App

The example/ directory contains a merchant demo app that demonstrates the full payment flow:

1. Enter your MONEI API key
2. Fetch a POS auth token
3. Enter an amount and accept an NFC payment
4. View the payment result

To run:

cd example
npm install
npx expo run:ios    # or npx expo run:android

Requires a physical device — NFC is not available in simulators/emulators.

Token Generation

Your backend generates POS auth tokens via the MONEI API:

curl -X POST https://api.monei.com/v1/pos/auth-token \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"

See the MONEI API docs for details.

License

MIT