Integración de app React Native

Acepta pagos NFC desde tu app React Native usando @monei-js/monei-pay-react-native-sdk. Construido como módulo Expo — funciona tanto con proyectos Expo como con proyectos bare de React Native.

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

Multiplataforma

Una sola API para ambas plataformas. El SDK gestiona automáticamente los esquemas de URL en iOS y los intents en Android.

Cómo funciona

1. Tu app llama a MoneiPay.acceptPayment(...) con un token y un importe
2. iOS: el SDK abre MONEI Pay mediante esquema de URL
3. Android: el SDK lanza CloudCommerce (por defecto) o MONEI Pay mediante intent
4. El resultado del pago se resuelve como una promesa

Requisitos previos

• Cuenta MONEI
• React Native 0.73+ / Expo SDK 50+
• Token de autenticación POS desde tu backend (consulta Primeros pasos)
• iOS: MONEI Pay instalado en el dispositivo
• Android (Directo): CloudCommerce instalado
• Android (A través de MONEI Pay): MONEI Pay instalado

Se requiere build de desarrollo

Este SDK incluye código nativo — solo compatible con builds de desarrollo. Expo Go no es compatible.

Integración

1. Instala el SDK

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

O instala directamente desde GitHub:

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

2. Configuración de plataforma

iOS

Añade a app.json (o directamente a Info.plist):

app.json

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

Conecta el gestor de finalización:

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 se necesita configuración. El AndroidManifest.xml del SDK incluye las entradas <queries> requeridas, que se fusionan automáticamente mediante el sistema de compilación.

3. Acepta un pago

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);
  }
}

Modelo de confianza

callbackUrl es un webhook firmado de confianza entregado de servidor a servidor — úsalo para completar pedidos. completeScheme (y la complete_url resultante) es solo una redirección del lado del cliente — devuelve al usuario a tu app pero no está firmada. Consulta Entrega de resultados.

Referencia del SDK

acceptPayment(params)

Parámetro	Tipo	Obligatorio	Descripción
token	string	Sí	Token de autenticación POS (JWT en bruto, sin prefijo "Bearer ")
amount	number	Sí	Importe del pago en céntimos (p. ej. 1500 = 15,00 EUR)
description	string	No	Descripción del pago
customerName	string	No	Nombre del cliente
customerEmail	string	No	Correo electrónico del cliente
customerPhone	string	No	Teléfono del cliente
callbackUrl	string	No	URL del webhook firmado de confianza. Debe ser https:// estricto, máx. 2048 caracteres. Consulta Entrega de resultados.
orderId	string	No	Referencia de pedido del comercio. Aparece en el webhook de callback para la conciliación. Máx. 2048 caracteres. Si se omite, el SDK genera uno.
transactionType	string	No	Tipo de transacción opcional: 'SALE' (por defecto), 'AUTH', 'REFUND', 'CAPTURE', 'CANCEL', 'PAYOUT', 'VERIF'. Validado en el servidor.
completeScheme	string	Sí (solo iOS)	Esquema de URL registrado de tu app — usado para redirigir al usuario de vuelta tras completar el pago
mode	string	No (solo Android)	'direct' (por defecto) o 'via-monei-pay'

handleCompleteRedirect(url)

Gestiona la URL de redirección de finalización de MONEI Pay (solo iOS). Conéctalo en tu gestor de Linking.

Devuelve boolean — true si la URL fue gestionada.

cancelPendingPayment()

Cancela cualquier pago pendiente. La promesa se rechaza con 'CANCELLED'.

PaymentResult

Propiedad	Tipo	Descripción
transactionId	string	ID de transacción de MONEI
success	boolean	Indica si el pago fue aprobado
amount	number	Importe del pago en céntimos
cardBrand	string	Marca de la tarjeta (p. ej. visa, mastercard)
maskedCardNumber	string	Número de tarjeta enmascarado (p. ej. ****1234)

Códigos de error

Código	Descripción
NOT_INSTALLED	MONEI Pay o CloudCommerce no está instalado
PAYMENT_IN_PROGRESS	Otro pago ya está activo
PAYMENT_FAILED	Pago rechazado o fallido
PAYMENT_TIMEOUT	Sin respuesta a tiempo (iOS)
CANCELLED	El usuario canceló
INVALID_PARAMS	Parámetros de entrada no válidos
INVALID_CALLBACK_URL	callbackUrl no es https estricto o supera los 2048 caracteres
INVALID_COMPLETE_URL	complete_url (de completeScheme) usa un esquema bloqueado o supera los 2048 caracteres
INVALID_TOKEN	Token de autenticación no válido o mal formado
TOKEN_EXPIRED	El token de autenticación ha expirado (>24h)
NOT_AUTHENTICATED	Sin token y el usuario no ha iniciado sesión en MONEI Pay
ACCOUNT_NOT_CONFIGURED	La cuenta de MONEI Pay no tiene la configuración POS requerida
FAILED_TO_OPEN	No se pudo abrir MONEI Pay (iOS)

App de ejemplo

El directorio example/ contiene una app de demo para comercios. Desde esa carpeta ejecuta npm install y luego npx expo run:ios o npx expo run:android. Usa un dispositivo físico — NFC no está disponible en simuladores ni emuladores.