Saltar al contenido principal

Crea un checkout personalizado

Crea tu propia experiencia de checkout personalizada usando MONEI Components para recopilar de forma segura los datos de pago de varios métodos directamente en tu sitio.

Demo de pagos MONEI

Demo en vivo

Código fuente

Características principales de MONEI Components:

  • Recopila datos de pago de forma segura a través de iframes alojados por MONEI.
  • Genera un paymentToken de un solo uso para el procesamiento seguro en el servidor.
  • Disponible para JavaScript puro, React, Vue, Angular y Svelte.
  • Compatible con personalización de estilos, idioma y múltiples métodos de pago.
  • Ayuda a cumplir los requisitos de conformidad PCI DSS, ya que los datos sensibles no pasan por tu servidor.

Antes de empezar​

  • Esta guía cubre la integración de Components para varios métodos de pago. Si prefieres una solución más sencilla sin necesidad de código, considera la Página de pago alojada.
  • 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​

  1. Tu backend crea un pago a través de la MONEI API y recibe un payment.id
  2. El payment.id se pasa a la página de checkout del lado del cliente
  3. El cliente introduce los datos de pago en un MONEI Component (iframe seguro)
  4. monei.confirmPayment() envía los datos tokenizados a MONEI, que gestiona 3D Secure si es necesario
  5. MONEI envía el estado final del pago a tu backend mediante webhook

Pasos de integración​

1. Crear el pago (lado del servidor)​

Crea un Pago en tu servidor con un importe y una moneda. Determina siempre el importe en el lado del servidor.

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": {
    "email": "email@example.com"
   },
  "callbackUrl": "https://example.com/checkout/callback"
}'

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

Parámetros principales:

  • amount positive integer: Importe en la unidad monetaria más pequeña.
  • currency string: Código de moneda ISO de tres letras.
  • orderId string: Tu identificador de pedido único.
  • callbackUrl string: Tu endpoint de servidor para las notificaciones de webhook.

Consulta todos los parámetros de la solicitud disponibles.

La respuesta contiene payment.id. Pásalo de forma segura al lado del cliente para el siguiente paso.

2. Añadir el Component a tu página de pago (lado del cliente)​

Incluye monei.js en tu página de checkout añadiendo la etiqueta script al head de tu archivo HTML.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.monei.com/v3/monei.js"></script>
</head>
<body>
  <!-- Create an empty container for the card input -->
  <div id="card-element">
    <!-- A MONEI Card Input Component will be inserted here. -->
  </div>
  <!-- Your client-side script -->
  <script src="client.js"></script>
</body>

Crea un nodo DOM vacío (contenedor) con un ID único en tu página de checkout. A continuación, inicializa el Component:

client.js
// Get paymentId passed securely from your server
const paymentId = '{{payment_id}}'; // Replace with actual paymentId

// Create an instance of the Card Input Component using the paymentId.
const cardElement = monei.CardInput({
  paymentId: paymentId
  // You can add other options like style, onFocus, onChange here
  // See MONEI Components reference for details
});

// Render the Component into the container
cardElement.render('#card-element');

// Next step: Confirm the payment (see below)
Alternativa: inicializar con el ID de cuenta

También puedes inicializar CardInput con accountId + sessionId en lugar de paymentId para generar un token antes de crear el pago. Esto es útil para el express checkout con envío o la activación de suscripciones.

const cardElement = monei.CardInput({
  accountId: 'YOUR_ACCOUNT_ID',
  sessionId: 'unique_session_id'
});

Al usar este método, pasa el mismo sessionId al crear el pago en el servidor. Consulta la referencia de MONEI Components para más información.

3. Confirmar el pago (lado del cliente)​

Para completar el pago, debes confirmarlo usando la función monei.confirmPayment.

Debes proporcionar el paymentId (obtenido en el Paso 1) y un paymentToken generado con el Component.

client.js
// Assumes cardElement is the initialized CardInput component from Step 2

// Function to submit the card input and confirm the payment
async function handlePayment() {
  try {
    // Generate a payment token from the card input
    const {token, error} = await cardElement.submit();

    if (error) {
      // Inform the user if there was an error.
      console.error('Submit error:', error);
      return;
    }

    // Confirm the payment with the generated token
    const result = await monei.confirmPayment({
      paymentId: paymentId,
      paymentToken: token
    });

    // At this moment you can show a customer the payment result (e.g., redirect)
    // But you should ALWAYS rely on the result passed to the callback endpoint
    // on your server (Step 4) to update the final order status.
    console.log('Payment status (client-side):', result.status);
    // Example: window.location.href = '/thank-you?paymentId=' + paymentId;
  } catch (error) {
    console.error(error);
  }
}

// You would typically call handlePayment() when the user clicks your pay button.
// Example: document.getElementById('your-pay-button').addEventListener('click', handlePayment);

Después de confirmar el pago, MONEI gestiona todos los pasos necesarios, como la autenticación 3D Secure.

Flujo alternativo

Como proceso alternativo, puedes enviar el paymentToken generado a tu servidor y luego confirmar el pago en el servidor.

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

Tras la interacción del lado del cliente y cualquier procesamiento en segundo plano necesario (como 3D Secure o la autorización bancaria), MONEI envía el estado final y definitivo 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.

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

Antes de pasar a producción​