Primeros pasos

Acepta pagos NFC desde tu propia app de comercio utilizando los SDK de MONEI Pay.

Cómo funciona

Tu backend genera un token de autenticación POS usando tu clave de API de MONEI
Tu app de comercio recibe el token a través de tu propia API
La app llama a acceptPayment() con el token y el importe
El SDK abre MONEI Pay (o CloudCommerce en Android) para el pago NFC por contacto
El resultado del pago se devuelve a tu app

Descarga MONEI Pay

Paso 1: Obtén tu clave de API

Regístrate en dashboard.monei.com
Ve a Ajustes → Claves de API
Usa la clave de prueba para desarrollo y la clave de producción para entornos en vivo

Paso 2: Genera un token de autenticación POS

Tu backend llama a la API de MONEI para crear un token por cada sesión de pago. El token es válido durante 24 horas — puedes reutilizarlo para múltiples transacciones dentro de ese período. Nunca expongas tu clave de API en la app de comercio. Consulta la referencia completa de la API Crear token de autenticación POS.

cURL
Node.js
Python
PHP

curl -X POST https://api.monei.com/v1/pos/auth-token \
  -H "Authorization: YOUR_API_KEY"
# Optional: scope to a specific terminal or store
#   -H "Content-Type: application/json" \
#   -d '{"pointOfSaleId": "pos_abc123", "storeId": "store_xyz"}'

server.js
import {Monei} from '@monei-js/node-sdk';

const monei = new Monei('YOUR_API_KEY');

const {token} = await monei.posAuthToken.create();
// Optional: .create({pointOfSaleId: 'pos_abc123', storeId: 'store_xyz'})
// Send `token` to your merchant app

server.py
import Monei

monei = Monei.MoneiClient(api_key="YOUR_API_KEY")

result = monei.pos_auth_token.create()
# Optional: monei.pos_auth_token.create(
#     CreatePosAuthTokenRequest(point_of_sale_id="pos_abc123", store_id="store_xyz")
# )
token = result.token
# Send `token` to your merchant app

server.php
<?php
require_once 'vendor/autoload.php';

use Monei\MoneiClient;

$monei = new MoneiClient('YOUR_API_KEY');

$result = $monei->posAuthToken->create();
// Optional: ->create(new CreatePosAuthTokenRequest(['point_of_sale_id' => 'pos_abc123', 'store_id' => 'store_xyz']))
$token = $result->getToken();
// Send $token to your merchant app
?>

Parámetros de la solicitud

Parámetro	Tipo	Requerido	Descripción
`pointOfSaleId`	String	No	Identificador único del punto de venta. Si se especifica, el pago queda vinculado a ese punto de venta.
`storeId`	String	No	Identificador único de la tienda. Si se especifica, el pago queda vinculado a esa tienda.

Respuesta

{
  "token": "eyJhbGciOiJSUzI1NiIs..."
}

El token es un JWT (firmado con RS256) que contiene el ID de cuenta y los metadatos del comercio. Expira después de 24 horas. Genera uno por sesión — no necesitas un token nuevo para cada transacción.

Paso 3: Integra tu app

Instala el SDK, configura tu proyecto, llama a acceptPayment() con el token del Paso 2 y gestiona los resultados. Cada guía cubre la instalación, la configuración de la plataforma, la referencia del SDK, la app de ejemplo y la resolución de problemas.

iOS — SDK en Swift mediante SPM o CocoaPods
Android — SDK en Kotlin mediante GitHub Packages o JitPack, modos Direct y Via MONEI Pay
React Native — Módulo Expo, multiplataforma con una sola API
Web — POS basado en navegador. Sin SDK; abre el deep link de MONEI Pay desde Safari o Chrome

Verifica los pagos desde el servidor

El SDK devuelve un PaymentResult a tu app, pero siempre debes verificar el pago desde tu backend antes de completar un pedido. Esto evita la manipulación en el lado del cliente.

Usa el endpoint Obtener pago con el transactionId devuelto en el resultado:

curl https://api.monei.com/v1/payments/{transactionId} \
  -H "Authorization: YOUR_API_KEY"

También puedes configurar un callbackUrl al crear pagos para recibir notificaciones asíncronas por webhook. Consulta Verificar firma para más detalles sobre la validación de las cargas útiles del webhook.

Entrega de resultados

MONEI Pay devuelve los resultados de los pagos a través de dos canales independientes. Cumplen funciones distintas — úsalos conjuntamente, nunca de forma intercambiable.

Canal	Tipo	Confianza	Usar para
`callback_url`	Webhook HTTPS firmado	De confianza	Cumplimiento de pedidos, lógica de negocio, conciliación
`complete_url`	Redirección en cliente	NO de confianza	Redirección UX, devolver al usuario a tu flujo

`callback_url` — webhook de confianza

Un webhook HTTPS firmado entregado de servidor a servidor con un HMAC MONEI-Signature verificable. Este es el único canal en el que debes basar las decisiones de negocio (completar pedidos, conceder acceso, enviar recibos).

Debe ser https:// — http, IPs privadas y localhost son rechazados
Máximo 2048 caracteres
Anulación opcional por pago; si se omite, MONEI usa el webhook configurado en tu punto de venta
Valida la firma en el servidor antes de confiar en la carga útil — consulta Verificar firma

`complete_url` — redirección UX

Una URL que se abre en el dispositivo del usuario cuando el pago finaliza (con éxito o con error). Es una redirección única con el resultado codificado en parámetros de consulta. No está firmada, puede suplantarse y nunca debe usarse para lógica de negocio.

Acepta https://, esquemas de URL personalizados (mymerchant://...), Universal Links (iOS) y App Links (Android)
Esquemas rechazados: http, tel, sms, mailto, javascript, file, data, blob, intent, además de esquemas internos de la plataforma
Máximo 2048 caracteres
Úsalo para devolver al usuario a tu app o página — luego confirma el resultado real mediante Obtener pago o el webhook callback_url

Parámetros de consulta del resultado al abrir `complete_url`

Cuando MONEI Pay abre complete_url, añade los siguientes parámetros de consulta:

Éxito:

Parámetro	Descripción
`success`	`"true"`
`transaction_id`	ID de transacción de MONEI
`amount`	Importe del pago en céntimos
`card_brand`	Marca de la tarjeta (p. ej. `visa`, `mastercard`)
`masked_card_number`	Número de tarjeta enmascarado (p. ej. `****1234`)

Error / cancelación:

Parámetro	Descripción
`success`	`"false"`
`error`	Código de error (ver más abajo)

Códigos de error que pueden aparecer en error:

Código	Significado
`CANCELLED`	El usuario canceló, o tu app abandonó el flujo a mitad
`TOKEN_EXPIRED`	El token de autenticación POS ha expirado (>24h)
`INVALID_TOKEN`	El token de autenticación POS está mal formado o firmado con la clave incorrecta
`INVALID_AMOUNT`	El importe falta, no es numérico o no es positivo
`INVALID_CALLBACK_URL`	`callback_url` no es https estricto o supera los 2048 caracteres
`INVALID_COMPLETE_URL`	`complete_url` usa un esquema bloqueado o supera los 2048 caracteres
`NOT_AUTHENTICATED`	No hay token POS y el usuario no ha iniciado sesión en MONEI Pay
`ACCOUNT_NOT_CONFIGURED`	La cuenta de MONEI Pay existe pero le falta la configuración POS requerida
`PAYMENT_FAILED`	Tarjeta rechazada, error de red u otro fallo posterior

Patrón recomendado

Combina ambos canales. El webhook se dispara de forma fiable desde los servidores de MONEI incluso si el dispositivo se queda sin conexión; la redirección le proporciona al usuario una ruta de regreso limpia.

monei-pay://accept-payment
  ?amount=1500
  &auth_token=eyJ...
  &order_id=order_42
  &callback_url=https://merchant.com/webhook/monei
  &complete_url=https://merchant.com/checkout/done

Cuando se abra complete_url, trata los parámetros de consulta solo como una pista — confirma mediante el webhook o Obtener pago antes de completar el pedido.

Conciliación con `order_id`

Opcional. Pasa tu propio order_id para que aparezca como orderId del pago en el webhook firmado callback_url. Es útil cuando tu POS ya tiene una referencia de pedido (número de mesa, número de factura, ID de carrito interno) y quieres correlacionar el pago de MONEI sin una consulta adicional a la base de datos. Si se omite, MONEI genera uno.

Problemas frecuentes

Problema	Causa	Solución
El SDK devuelve "app not found"	MONEI Pay (o CloudCommerce en modo Direct de Android) no está instalado	Instala la app requerida en el dispositivo
Token rechazado / 401	Token expirado (>24h) o clave de API del entorno incorrecto	Genera un token nuevo; asegúrate de usar la clave de prueba para el modo de prueba y la de producción para producción
NFC no funciona	NFC desactivado o dispositivo no compatible	Comprueba los ajustes del dispositivo; consulta la descripción general de MONEI Pay para los requisitos del dispositivo
El pago se completa en el dispositivo pero el backend no tiene registro	Falta la verificación en el servidor	Verifica siempre mediante la API o los webhooks (ver más arriba)

Próximos pasos

Descripción general de MONEI Pay — funcionalidades del producto y requisitos del dispositivo
API REST de MONEI — referencia completa de la API
Pruebas — tarjetas de prueba y entorno sandbox
Verificar firma — valida las cargas útiles del webhook

Cómo funciona​

Descarga MONEI Pay​

Paso 1: Obtén tu clave de API​

Paso 2: Genera un token de autenticación POS​

Parámetros de la solicitud​

Respuesta​

Paso 3: Integra tu app​

Verifica los pagos desde el servidor​

Entrega de resultados​

callback_url — webhook de confianza​

complete_url — redirección UX​

Parámetros de consulta del resultado al abrir complete_url​

Patrón recomendado​

Conciliación con order_id​

Problemas frecuentes​

Próximos pasos​