Usar pagos con código QR

Acepta pagos sin contacto en tienda con códigos QR. Elige entre la app MONEI Pay, los Puntos de venta del panel o la API de pagos.

Códigos QR permanentes frente a de un solo uso

	Permanente	De un solo uso
Creado desde	Puntos de venta del panel	App MONEI Pay / API de pagos
Formato URL	https://secure.monei.com/codes/{code_id}	https://secure.monei.com/payments/{payment_id}/qr
Reutilizable	Sí, el mismo QR para varias transacciones	No, un pago por QR
Importe	El cliente lo introduce (manual) o fijo	Predefinido por pago
Expiración	Nunca (se puede deshabilitar)	5 minutos (o expireAt personalizado mediante API)
Ideal para	Displays estáticos, materiales impresos, mesas	Checkout dinámico, facturas, TPV móvil

Antes de empezar

• Necesitarás una cuenta MONEI. Encuentra tus claves de API en MONEI Dashboard → Ajustes → API.
• Usa las claves en modo de prueba para las pruebas de integración.
• Asegúrate de que los métodos de pago relevantes estén habilitados en los ajustes de tu cuenta.
• Monitoriza los pagos de prueba en Panel → Pagos (activa el interruptor de Modo de prueba).

MONEI Pay & Dashboard

App MONEI Pay

MONEI Pay ofrece la forma más sencilla de aceptar pagos en tienda mediante una app dedicada.

Inicia sesión en pay.monei.com o descarga la app MONEI Pay usando tus credenciales del MONEI Dashboard para empezar a crear códigos de pago QR.

Pagos NFC

MONEI Pay también admite pagos NFC por aproximación para pagos sin contacto con tarjeta. Si tienes tu propia app de comercio, puedes integrar los pagos NFC usando los SDKs de integración App-to-App.

Puntos de venta del panel

Crea y gestiona Puntos de venta basados en QR directamente en tu MONEI Dashboard.

Crear un Punto de venta

1. Ve a Panel → Ajustes → Puntos de venta
2. Haz clic en Crear Punto de venta
3. Selecciona Código QR como tipo
4. Configura los ajustes de tu TPV (consulta las opciones a continuación)

Opciones de configuración

Opción	Descripción
Nombre	Identificador de este TPV (p. ej., "Entrada de tienda", "Mesa 5")
Tienda	Asociar con una tienda para el seguimiento en varias ubicaciones
Flujo de pago	Importe manual: El cliente introduce el importe cada vez. Importe fijo: El mismo importe para todas las transacciones
Importe fijo / Moneda	Importe predefinido al usar el flujo de importe fijo
Métodos de pago permitidos	Restringe qué métodos de pago aparecen (Tarjeta, Bizum, PayPal, etc.)
Captura manual	Reserva fondos (solo autorización), captura después. Compatible con Tarjeta, PayPal y Bizum
Requerir email	Obliga a los clientes a introducir su email antes de pagar
Requerir NIF/CIF	Solicita el NIF/CIF para fines de facturación
URL de callback	URL de webhook para las notificaciones de pago
Incluir QR en el email	Añade un código QR con el ID de pedido al email de confirmación (útil para entradas/eventos)
Texto del código QR	Texto personalizado mostrado junto al QR en el email de confirmación
Descripción	Descripción asociada a todos los pagos desde este TPV

Gestionar códigos QR

Cada TPV puede tener varios códigos QR. Desde la página de detalles del TPV:

• Genera nuevos códigos para diferentes ubicaciones o displays
• Descarga los códigos QR en formato SVG o PNG (300 px, 500 px o 1000 px)
• Habilita o deshabilita códigos sin eliminarlos
• Copia el enlace permanente para insertarlo: https://secure.monei.com/codes/{code_id}

Casos de uso

• Retail: Flujo de importe manual, habilita varios métodos de pago
• Eventos/Entradas: Importe fijo, requerir email, activar "QR en el email de confirmación"
• Servicio en mesa: Crea varios TPV por tienda para el seguimiento
• Kiosco: Importe fijo, restringir solo a tarjeta

Control de acceso de usuarios y agrupación de pagos

Las tiendas y los Puntos de venta permiten el control de acceso de usuarios y la agrupación de pagos:

• Asigna usuarios a tiendas/TPV: En Panel → Ajustes → Usuarios, vincula usuarios (p. ej., camareros, cajeros) a una tienda o TPV
• Visibilidad restringida: Los usuarios vinculados solo ven los pagos de su tienda/TPV asignado
• Herencia automática: Cuando un usuario vinculado crea un pago desde el panel o MONEI Pay, hereda el ID de su tienda/TPV
• Agrupación por API: Pasa storeId o pointOfSaleId al crear pagos mediante la API para agruparlos en los informes
• Trazabilidad: Los administradores pueden filtrar y rastrear pagos por tienda o TPV de origen

Payments API

Crear pagos QR de forma programática

Genera códigos de pago QR usando la MONEI API para integraciones personalizadas.

1. Crear el pago (lado del servidor)

Crea un Pago en tu servidor con un importe y una moneda.

cURL

POST https://api.monei.com/v1/payments

curl --request POST 'https://api.monei.com/v1/payments' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 110,
    "currency": "EUR",
    "orderId": "14379133960355",
    "callbackUrl": "https://example.com/checkout/callback"
}'

(Reemplaza YOUR_API_KEY con tu clave de API de MONEI real)

Node.js

server.js

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

// Replace YOUR_API_KEY with your actual MONEI API key
const monei = new Monei('YOUR_API_KEY');

const payment = await monei.payments.create({
  amount: 110,
  currency: 'EUR',
  orderId: '14379133960355',
  callbackUrl: 'https://example.com/checkout/callback'
});

// You will need the paymentId from the response to generate the QR code URL
const paymentId = payment.id;

// Construct the QR code URL
const qrCodeUrl = `https://secure.monei.com/payments/${paymentId}/qr`;

PHP

server.php

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

use Monei\Model\CreatePaymentRequest;
use Monei\MoneiClient;

// Replace YOUR_API_KEY with your actual MONEI API key
$monei = new MoneiClient('YOUR_API_KEY');

$payment = $monei->payments->create(
  new CreatePaymentRequest([
    'amount' => 110,
    'currency' => 'EUR',
    'order_id' => '14379133960355',
    'callback_url' => 'https://example.com/checkout/callback'
  ])
);

// You will need the paymentId from the response to generate the QR code URL
$paymentId = $payment->getId();

// Construct the QR code URL
$qrCodeUrl = "https://secure.monei.com/payments/{$paymentId}/qr";
?>

Python

server.py

import Monei
from Monei import CreatePaymentRequest

# Replace YOUR_API_KEY with your actual MONEI API key
monei = Monei.MoneiClient(api_key="YOUR_API_KEY")

payment = monei.payments.create(
    CreatePaymentRequest(
        amount=110,
        currency="EUR",
        order_id="14379133960355",
        callback_url="https://example.com/checkout/callback"
    )
)

# You will need the paymentId from the response to generate the QR code URL
payment_id = payment.id

# Construct the QR code URL
qr_code_url = f"https://secure.monei.com/payments/{payment_id}/qr"

Parámetros obligatorios:

• amount positive integer: Importe en la unidad monetaria más pequeña (p. ej., 110 para €1,10).
• currency string: Código de moneda ISO de tres letras (p. ej., EUR).
• orderId string: Tu identificador de pedido único.
• callbackUrl string: La URL de tu endpoint de servidor para las notificaciones de webhook asíncronas.

Parámetros opcionales:

• allowedPaymentMethods array: Restringe los métodos de pago disponibles (p. ej., ["card", "bizum"])
• description string: Descripción del pago mostrada en la página de pago
• customer object: Rellena previamente los datos del cliente (email, name, phone)
• metadata object: Pares clave-valor personalizados para el seguimiento y la conciliación
• storeId string: Asocia el pago con una tienda (para agrupación y control de acceso de usuarios)
• pointOfSaleId string: Vincula el pago a un TPV (para agrupación y control de acceso de usuarios)
• expireAt integer: Marca de tiempo Unix para la expiración personalizada (por defecto: 5 minutos desde la creación)

Consulta todos los parámetros de la solicitud disponibles.

La respuesta de la API incluye el payment.id, que usarás en el siguiente paso.

2. Mostrar el código QR y gestionar la interacción (cliente/físico)

Usa el payment.id del Paso 1 para presentar el código QR a tu cliente.

Opción 1: Insertar la imagen QR directamente

Construye la URL de la imagen del código QR: https://secure.monei.com/payments/{payment_id}/qr

Puedes renderizarla directamente en una página web o un display:

<img
  src="https://secure.monei.com/payments/{{payment_id}}/qr?format=svg&size=300"
  alt="Escanear para pagar"
  width="300"
  height="300"
/>

• Reemplaza {{payment_id}} con el ID real.
• Usa ?format=svg para SVG (por defecto es png).
• Usa ?size=400 para especificar el tamaño (mín: 100, máx: 1000, por defecto: 300).

Opción 2: Redirigir a la página alojada con QR

El objeto Payment devuelto en el Paso 1 también contiene payment.nextAction.redirectUrl. Añade ?qr=1 a esta URL para obtener un enlace a una página alojada por MONEI que muestra el código QR.

Ejemplo: https://secure.monei.com/payments/{payment_id}?qr=1

Interacción del cliente:

El cliente escanea el código QR con su teléfono y completa el pago en la página de pago de MONEI usando su método preferido.

Importante

El enlace de pago del código QR es válido durante 5 minutos. Tras ese tiempo, debes crear una nueva solicitud de pago.

3. Procesar la notificación de webhook (lado del servidor)

MONEI envía el estado final y autoritativo del pago mediante una solicitud HTTP POST asíncrona a la callbackUrl que proporcionaste en el Paso 1. El cuerpo de la solicitud contiene el objeto Payment completo en formato JSON.

Este webhook garantiza que recibas el estado definitivo incluso si el cliente cierra el navegador o pierde la conexión tras escanear.

Es imprescindible que:

1. Verifiques la cabecera MONEI-Signature incluida en la solicitud. Esto confirma que el webhook proviene realmente de MONEI. Consulta la guía de verificación de firmas para los detalles de implementación.
2. Devuelvas un código de estado HTTP 200 OK inmediatamente al recibir el webhook para confirmar la recepción. Cualquier otro código de estado indica a MONEI que la notificación ha fallado.

Si MONEI no recibe un 200 OK, reintentará el envío del webhook.

Una vez verificada la firma, inspecciona el campo status en el objeto Payment para confirmar el éxito del pago (SUCCEEDED) y completar el pedido, o gestionar los fallos.

Alternativa: Consultar el estado del pago

Para escenarios de kiosco o display en los que necesitas actualizaciones de estado en tiempo real, consulta el estado del pago en lugar de (o además de) los webhooks.

cURL

GET https://api.monei.com/v1/payments/{payment_id}

curl --request GET 'https://api.monei.com/v1/payments/{payment_id}' \
--header 'Authorization: YOUR_API_KEY'

Node.js

server.js

const payment = await monei.payments.get(paymentId);
console.log(payment.status);

PHP

server.php

<?php
$payment = $monei->payments->get($paymentId);
echo $payment->getStatus();
?>

Python

server.py

payment = monei.payments.get(payment_id)
print(payment.status)

Valores de estado: PENDING, PENDING_PROCESSING, SUCCEEDED, FAILED, CANCELED, EXPIRED

Buenas prácticas de consulta

Consulta cada 2-3 segundos. Detente cuando el estado ya no sea PENDING/PENDING_PROCESSING o cuando el QR expire.

Personalización

Puedes personalizar la apariencia del código QR (color, icono) y la página de pago alojada en tu MONEI Dashboard → Ajustes → Marca.

Pruebas

• Usa tus claves de API en modo de prueba para el desarrollo
• Activa el Modo de prueba en tu Panel para ver los pagos de prueba
• Usa números de tarjeta de prueba para simular diferentes escenarios
• Verifica la entrega de webhooks en Panel → Desarrolladores → Webhooks

Solución de problemas

Código QR expirado Los códigos QR son válidos durante 5 minutos. Crea un nuevo pago si el código expira.

El método de pago no aparece Comprueba que el método esté habilitado en tu cuenta y que no esté filtrado por allowedPaymentMethods.

Webhook no recibido Verifica que tu callbackUrl sea accesible públicamente, devuelva 200 OK y consulta los registros de webhooks en el panel.