Saltar al contenido principal

Express Checkout

El express checkout te permite recopilar direcciones de envío y facturación directamente desde las interfaces de Apple Pay, Google Pay o PayPal, sin necesidad de un formulario de dirección independiente.

Disponible en los componentes PaymentRequest (Apple Pay / Google Pay) y PayPal.

Antes de empezar​

Cómo funciona​

  1. El navegador abre la interfaz de cartera (Apple Pay, Google Pay o PayPal) con tu ID de cuenta y el importe inicial
  2. El cliente selecciona las opciones de envío/facturación — tus callbacks actualizan los importes de forma dinámica
  3. Tras la aprobación, el token y los detalles se envían a tu backend
  4. Tu backend crea el pago con el token — no es necesario crear el pago previamente
  5. MONEI envía el estado final del pago mediante webhook

Express checkout con envío​

Con envío, el importe autorizado por la cartera puede diferir del importe inicial cuando cambian los costes de envío. Este flujo usa el enfoque de accountId — no es necesario crear el pago previamente. El pago se crea en el servidor una vez que el cliente confirma en la interfaz de cartera.

1. Incluir monei.js (lado del cliente)​

Añade la etiqueta script al head de tu archivo HTML.

checkout.html
<head>
  <script src="https://js.monei.com/v3/monei.js"></script>
</head>
<body>
  <!-- Use "payment_request" for Apple Pay / Google Pay, "paypal_container" for PayPal -->
  <div id="payment_request"></div>
  <div id="paypal_container"></div>
  <script src="client.js"></script>
</body>

2. Inicializar el Component con express checkout (lado del cliente)​

client.js
const paymentRequest = monei.PaymentRequest({
  accountId: 'your_account_id',
  sessionId: 'unique_session_id',
  amount: 1099, // base amount in minor units (before shipping)
  currency: 'EUR',
  requestShipping: true,
  requestBilling: true,
  shippingOptions: [
    {id: 'standard', label: 'Standard Shipping', amount: 500},
    {id: 'express', label: 'Express Shipping', amount: 1200, description: '1-2 business days'}
  ],
  onShippingAddressChange(address) {
    // Called when the customer changes their shipping address.
    // address contains: country, city, state, zip (no street-level data mid-flow).
    // Return updated shipping options and/or amount based on the address.
    if (address.country !== 'ES') {
      return {
        shippingOptions: [{id: 'intl', label: 'International', amount: 2000}],
        amount: 3099 // product (1099) + intl shipping (2000)
      };
    }
    return {shippingOptions: [{id: 'standard', label: 'Standard', amount: 500}], amount: 1599};
  },
  onShippingOptionChange(option) {
    // Called when the customer selects a different shipping option.
    // Return updated total amount.
    return {amount: 1099 + option.amount};
  },
  async onSubmit(result) {
    // Called when the customer approves the payment in the wallet UI.
    // Create the payment server-side (see Step 3).
    await fetch('/create-payment', {
      method: 'POST',
      headers: {'Content-Type': 'application/json'},
      body: JSON.stringify({
        amount: result.finalAmount,
        currency: 'EUR',
        sessionId: 'unique_session_id',
        paymentToken: result.token,
        billingDetails: result.billingDetails,
        shippingDetails: result.shippingDetails
      })
    });
  },
  onError(error) {
    console.error(error);
  }
});

paymentRequest.render('#payment_request');

Opciones principales:

  • accountId string: Tu ID de cuenta MONEI.
  • sessionId string: Un identificador de sesión único. Debe coincidir con el sessionId pasado al crear el pago en el servidor.
  • amount number: Importe inicial en la unidad monetaria más pequeña (p. ej., 1099 = 10,99 EUR).
  • requestShipping boolean: Activa la recopilación de la dirección de envío en la interfaz de cartera.
  • requestBilling boolean: Activa la recopilación de la dirección de facturación (solo PaymentRequest — PayPal siempre devuelve la información de facturación).
  • shippingOptions ShippingOption[]: Opciones de envío disponibles.

Consulta las opciones de PaymentRequest y PayPal para la lista completa.

3. Crear el pago (lado del servidor)​

Cuando el cliente confirma en la interfaz de cartera, tu manejador onSubmit envía el resultado a tu servidor. Crea el pago pasando el paymentToken — esto confirma el pago automáticamente.

important

Debes pasar el mismo sessionId utilizado para inicializar el componente en el frontend. Esto garantiza que el cliente que generó el token sea el mismo que realiza el pago.

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": 1599,
  "currency": "EUR",
  "orderId": "14379133960355",
  "description": "Test Shop - #14379133960355",
  "sessionId": "unique_session_id",
  "paymentToken": "token_from_client",
  "callbackUrl": "https://example.com/checkout/callback",
  "customer": {
    "email": "email@example.com"
  },
  "billingDetails": {},
  "shippingDetails": {}
}'

Consulta todos los parámetros de la solicitud disponibles.

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

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 3. 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.

  1. Verifica la cabecera MONEI-Signature para confirmar que el webhook proviene realmente de MONEI. Consulta la guía de verificación de firmas para los detalles de implementación.
  2. Devuelve un código de estado HTTP 200 OK inmediatamente para confirmar la recepción.

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

Checkout solo con facturación​

Si solo necesitas la dirección de facturación (sin envío), el flujo es más sencillo — usa paymentId en lugar de accountId y confirma en el lado del cliente con confirmPayment. Sigue los mismos pasos que en Crea un checkout personalizado, pero añade requestBilling: true para recopilar la dirección de facturación desde la cartera:

client.js
const paymentRequest = monei.PaymentRequest({
  paymentId: '{{payment_id}}',
  requestBilling: true,
  async onSubmit(result) {
    await monei.confirmPayment({
      paymentId: '{{payment_id}}',
      paymentToken: result.token,
      billingDetails: result.billingDetails
    });
  },
  onError(error) {
    console.error(error);
  }
});

paymentRequest.render('#payment_request');

Referencia de tipos​

Consulta las definiciones de tipos completas en la Referencia:

Antes de pasar a producción​