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

The package is on npm: @monei-js/monei-pay-react-native-sdk.

npx expo install @monei-js/monei-pay-react-native-sdk

Or with npm or pnpm:

npm install @monei-js/monei-pay-react-native-sdk
pnpm add @monei-js/monei-pay-react-native-sdk

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-js/monei-pay-react-native-sdk';

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: 'john@ex.com', // 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