React Native App Integration

Accept NFC payments from your React Native app using @monei-js/monei-pay-react-native-sdk. Built as an Expo module — works with both Expo and bare React Native projects.

Source: github.com/MONEI/monei-pay-react-native-sdk

Cross-platform

One API for both platforms. The SDK handles URL schemes on iOS and intents on Android automatically.

How It Works

1. Your app calls MoneiPay.acceptPayment(...) with a token and amount
2. iOS: the SDK opens MONEI Pay via URL scheme
3. Android: the SDK launches CloudCommerce (default) or MONEI Pay via intent
4. The payment result resolves as a promise

Prerequisites

• MONEI account
• React Native 0.73+ / Expo SDK 50+
• POS auth token from your backend (see Getting Started)
• iOS: MONEI Pay installed on the device
• Android (Direct): CloudCommerce installed
• Android (Via MONEI Pay): MONEI Pay installed

Development build required

This SDK includes native code — development builds only. Expo Go is not supported.

Integration

1. Install the SDK

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

Or install directly from GitHub:

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

2. Platform Configuration

iOS

Add to app.json (or Info.plist directly):

app.json

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

Wire the callback handler:

App.tsx

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

export default function App() {
  useEffect(() => {
    const subscription = Linking.addEventListener('url', ({url}) => {
      MoneiPay.handleCallback(url);
    });
    return () => subscription.remove();
  }, []);

  // ...
}

Android

No configuration needed. The SDK's AndroidManifest.xml includes the required <queries> entries, merged automatically by the build system.

3. Accept a Payment

import * as MoneiPay from '@monei-js/monei-pay-react-native-sdk';

async function acceptPayment() {
  try {
    const result = await MoneiPay.acceptPayment({
      token: 'eyJ...',
      amount: 1500,
      description: 'Order #123',
      customerName: 'John Doe',
      customerEmail: 'john@example.com',
      callbackScheme: 'your-app', // iOS only
      mode: 'direct' // Android only: 'direct' (default) or 'via-monei-pay'
    });

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

SDK Reference

acceptPayment(params)

Parameter	Type	Required	Description
token	string	Yes	POS auth token (raw JWT, no "Bearer " prefix)
amount	number	Yes	Payment amount in cents (e.g. 1500 = 15.00 EUR)
description	string	No	Payment description
customerName	string	No	Customer name
customerEmail	string	No	Customer email
customerPhone	string	No	Customer phone
callbackScheme	string	Yes (iOS only)	Your app's registered URL scheme
mode	string	No (Android only)	'direct' (default) or 'via-monei-pay'

handleCallback(url)

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

Returns boolean — true if the URL was handled.

cancelPendingPayment()

Cancel any pending payment. The promise rejects with 'CANCELLED'.

PaymentResult

Property	Type	Description
transactionId	string	MONEI transaction ID
success	boolean	Whether the payment was approved
amount	number	Payment amount in cents
cardBrand	string	Card brand (e.g. visa, mastercard)
maskedCardNumber	string	Masked card number (e.g. ****1234)

Error Codes

Code	Description
NOT_INSTALLED	MONEI Pay or CloudCommerce not installed
PAYMENT_IN_PROGRESS	Another payment is already active
PAYMENT_FAILED	Payment declined or failed
PAYMENT_TIMEOUT	No response in time (iOS)
CANCELLED	User cancelled
INVALID_PARAMS	Invalid input parameters
INVALID_TOKEN	Auth token invalid or expired
FAILED_TO_OPEN	Could not open MONEI Pay (iOS)

Example App

The example/ directory contains a merchant demo app. From that folder run npm install, then npx expo run:ios or npx expo run:android. Use a physical device — NFC is not available in simulators or emulators.