Usar una página de pago prediseñada

La página de pago alojada de MONEI ofrece la forma más sencilla y conforme con PCI DSS de recopilar pagos de forma segura de tus clientes utilizando varios métodos.

Vista previa de pagos alojados

Demo en vivo

Características principales:

Diseñada para eliminar fricciones: Validación de tarjeta en tiempo real con mensajes de error integrados.
Optimizada para móvil: Diseño totalmente responsivo.
Internacional: Compatible con 13 idiomas.
Múltiples métodos de pago: Compatible con varios métodos de pago.
Personalización y marca: Logotipo, botones y color de fondo personalizables desde tu MONEI Dashboard.
3D Secure: Compatibilidad integrada con la verificación SCA.
Fraude y cumplimiento normativo: Conformidad PCI simplificada y preparada para SCA.

Puedes personalizar la apariencia en tu MONEI Dashboard → Ajustes → Marca.

Antes de empezar

Necesitarás una cuenta MONEI y tus claves de API (de prueba o de producción). Encuéntralas en tu MONEI Dashboard.
Usa tus 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.
Puedes monitorizar los pagos de prueba en tu MONEI Dashboard → Pagos (asegúrate de que el Modo de prueba esté activo).

Cómo funciona

Tu backend crea un pago y recibe una redirectUrl
El cliente es redirigido a la página de pago alojada por MONEI
El cliente selecciona un método de pago y completa el pago (incluyendo 3D Secure si es necesario)
Tras el pago, el cliente es redirigido de vuelta a tu completeUrl (o cancelUrl si cancela)
MONEI envía el estado final del pago a tu backend mediante webhook — confía siempre en esto, no en la redirección

Pasos de integración

1. Crear el pago (lado del servidor)

Primero, realiza una llamada a la API en el servidor para crear un nuevo objeto Payment. Esto registra la intención de pago con MONEI.

cURL
Node.js
PHP
Python

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",
    "description": "Test Shop - #14379133960355",
    "customer": {
       "name": "John Doe",
       "email": "email@example.com",
       "phone": "+34666555444"
    },
    "billingDetails": {
       "name": "John Doe",
       "address": {
          "country": "ES",
          "city": "Malaga",
          "line1": "Fake Street 123",
          "zip": "29001"
       }
    },
    "callbackUrl": "https://example.com/checkout/callback",
    "completeUrl": "https://example.com/checkout/complete",
    "cancelUrl": "https://example.com/checkout/cancel"
}'

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

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',
  description: 'Test Shop - #14379133960355',
  customer: {
    name: 'John Doe',
    email: 'email@example.com',
    phone: '+34666555444'
  },
  billingDetails: {
    name: 'John Doe',
    address: {
      country: 'ES',
      city: 'Malaga',
      line1: 'Fake Street 123',
      zip: '29001'
    }
  },
  callbackUrl: 'https://example.com/checkout/callback',
  completeUrl: 'https://example.com/checkout/complete',
  cancelUrl: 'https://example.com/checkout/cancel'
});

// You will need the redirectUrl from the response in the next step
const redirectUrl = payment.nextAction.redirectUrl;

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

use Monei\Model\CreatePaymentRequest;
use Monei\Model\PaymentCustomer;
use Monei\Model\PaymentBillingDetails;
use Monei\Model\Address;
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',
      'description' => 'Test Shop - #14379133960355',
      'customer' => new PaymentCustomer([
        'name' => 'John Doe',
        'email' => 'email@example.com',
        'phone' => '+34666555444'
      ]),
      'billing_details' => new PaymentBillingDetails([
        'name' => 'John Doe',
        'address' => new Address([
          'country' => 'ES',
          'city' => 'Malaga',
          'line1' => 'Fake Street 123',
          'zip' => '29001'
        ])
      ]),
      'callback_url' => 'https://example.com/checkout/callback',
      'complete_url' => 'https://example.com/checkout/complete',
      'cancel_url' => 'https://example.com/checkout/cancel'
    ])
);

// You will need the redirectUrl from the response in the next step
$redirectUrl = $payment->getNextAction()->getRedirectUrl();
?>

server.py
import Monei
from Monei import CreatePaymentRequest, PaymentCustomer, PaymentBillingDetails, Address

# 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",
        description="Test Shop - #14379133960355",
        customer=PaymentCustomer(
            name="John Doe",
            email="email@example.com",
            phone="+34666555444"
        ),
        billing_details=PaymentBillingDetails(
            name="John Doe",
            address=Address(
                country="ES",
                city="Malaga",
                line1="Fake Street 123",
                zip="29001"
            )
        ),
        callback_url="https://example.com/checkout/callback",
        complete_url="https://example.com/checkout/complete",
        cancel_url="https://example.com/checkout/cancel"
    )
)

// You will need the redirectUrl from the response in the next step
redirect_url = payment.next_action.redirect_url

Parámetros principales:

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.
completeUrl string: A dónde se redirige al cliente después de intentar el pago (con éxito o con fallo).
callbackUrl string: La URL de tu endpoint de servidor para las notificaciones de webhook asíncronas (imprescindible para el estado final).
cancelUrl string: A dónde se redirige al cliente si hace clic en cancelar o "Volver a la tienda".

Consulta todos los parámetros de la solicitud disponibles.

La respuesta de la API incluye el payment.id y, de forma importante, payment.nextAction.redirectUrl.

2. Gestionar la interacción de pago (lado del cliente mediante redirección)

La respuesta de la API del Paso 1 contiene un objeto nextAction con una redirectUrl. Debes redirigir el navegador de tu cliente a esta URL.

Example Partial API Response
{
  "id": "af6029f80f5fc73a8ad2753eea0b1be0", // MONEI Payment ID
  // ... other fields ...
  "status": "PENDING", // Initial status
  "nextAction": {
    "type": "CONFIRM",
    "mustRedirect": true, // Indicates redirection is needed
    "redirectUrl": "https://secure.monei.com/payments/af6029f80f5fc73a8ad2753eea0b1be0" // <-- REDIRECT CUSTOMER HERE
  }
}

Esta redirectUrl lleva al cliente a la página de pago segura alojada por MONEI, donde seleccionará un método de pago e introducirá sus datos.

Alternativa: modal de pago

En lugar de una redirección a página completa, puedes usar monei.js para mostrar las opciones de pago dentro de un modal en tu propio sitio. Consulta la guía del modal de pago para más detalles.

Acciones del cliente:

El cliente completa los datos de pago en la página de MONEI.
Puede someterse a la verificación 3D Secure si lo requiere su banco.
Tras completar, fallar o cancelar, es redirigido de vuelta a tu sitio:
- A la completeUrl si intentó el pago.
- A la cancelUrl si canceló explícitamente.

Importante: La redirección a completeUrl no garantiza el éxito del pago. Debes confiar en el webhook (Paso 3) para el estado final.

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 es la única forma fiable de confirmar el resultado definitivo del pago, independientemente de las acciones del navegador del cliente o las redirecciones.

Es imprescindible que:

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.
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 (SUCCEEDED, FAILED, CANCELED, etc.) para determinar si debes completar el pedido o gestionar el fallo.

Example Webhook Payload (POST to your callbackUrl)
{
  "id": "af6029f80f5fc73a8ad2753eea0b1be0",
  "amount": 110,
  // ... other fields ...
  "status": "SUCCEEDED", // <-- Check this for final status
  "createdAt": 1594215339,
  "updatedAt": 1594215345
}

Antes de empezar​

Cómo funciona​

Pasos de integración​

1. Crear el pago (lado del servidor)​

2. Gestionar la interacción de pago (lado del cliente mediante redirección)​

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