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 a Universal Link (no system prompt)
3. Android: the SDK launches CloudCommerce (default) or MONEI Pay via intent
4. The payment result resolves as a promise

iOS opens with no prompt

On iOS the SDK opens MONEI Pay via a Universal Link (https://pay.monei.com/accept-payment), so the app launches directly without an "Open in MONEI Pay?" confirmation. MONEI Pay installs that predate Universal Link support fall back automatically to the monei-pay:// URL scheme. No change to your integration is required.

Prerequisites

• MONEI account
• React Native 0.73+ / Expo SDK 50+
• 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 completion 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.handleCompleteRedirect(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',
      callbackUrl: 'https://merchant.com/webhook/monei',
      completeScheme: '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);
  }
}

Trust model

callbackUrl is a trusted, signed webhook delivered server-to-server — use it to fulfill orders. completeScheme (and the resulting complete_url) is a client-side redirect only — it brings the user back to your app but is not signed. See Result Delivery.

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
callbackUrl	string	No	Trusted signed webhook URL. Must be strict https://, max 2048 chars. See Result Delivery.
orderId	string	No	Your merchant order reference. Surfaced in the webhook callback for . Max 2048 chars. If omitted, the SDK generates one.
transactionType	string	No	Optional transaction type: 'SALE' (default), 'AUTH', 'REFUND', 'CAPTURE', 'CANCEL', 'PAYOUT', 'VERIF'. Server-validated.
completeScheme	string	Yes (iOS only)	Your app's registered URL scheme — used to redirect the user back after the payment completes
mode	string	No (Android only)	'direct' (default) or 'via-monei-pay'

handleCompleteRedirect(url)

Handle the completion redirect 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_CALLBACK_URL	callbackUrl is not strict https or exceeds 2048 chars
INVALID_COMPLETE_URL	complete_url (from completeScheme) uses a blocked scheme or exceeds 2048 chars
INVALID_TOKEN	Auth token invalid or malformed
TOKEN_EXPIRED	Auth token has expired (>24h)
NOT_AUTHENTICATED	No token and user is not signed into MONEI Pay
ACCOUNT_NOT_CONFIGURED	MONEI Pay account is missing required POS configuration
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.

note

NFC is not available in simulators or emulators — use a physical device.