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"
  }
}

On iOS the SDK launches MONEI Pay via a Universal Link (https://pay.monei.com/accept-payment), which opens the app directly with no "Open in MONEI Pay?" prompt. Installs that predate Universal Link support fall back to the monei-pay:// custom scheme, so the LSApplicationQueriesSchemes entry above is still required. No extra merchant configuration is needed.

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: '[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 | | callbackUrl | string | No | HTTPS endpoint for the signed webhook. Trusted channel — use for fulfillment. Must be https://, max 2048 chars. | | orderId | string | No | Merchant order reference. Surfaced in the webhook callback for reconciliation. Max 2048 chars. If omitted, the SDK generates one. | | transactionType | string | No | Optional: 'SALE' (default), 'AUTH', 'REFUND', 'CAPTURE', 'CANCEL', 'PAYOUT', 'VERIF'. Server-validated. | | completeScheme | string | iOS | Your app's registered URL scheme. MONEI Pay opens <completeScheme>://payment-result on completion. | | mode | string | No | Android: 'direct' (default) or 'via-monei-pay' |

Returns PaymentResult. Throws on failure.

handleCompleteRedirect(url)

Handle the post-payment redirect 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"

Partner / master account integrations: use your master account API key, set the sub-account ID via MONEI-Account-ID, and identify yourself with a partner User-Agent (MONEI/<PARTNER_NAME>/<VERSION>). A custom User-Agent is required whenever MONEI-Account-ID is set.

curl -X POST https://api.monei.com/v1/pos/auth-token \
  -H "Authorization: pk_live_MASTER_KEY" \
  -H "MONEI-Account-ID: SUB_ACCOUNT_ID" \
  -H "User-Agent: MONEI/MyPartner/0.1.0" \
  -H "Content-Type: application/json"

See docs.monei.com/monei-connect for details.

See the MONEI API docs for details.

License

MIT