Página de pago

Usa la payment_url que devuelve POST /v1/invoices como URL canónica de pago. Esa misma URL admite dos formas de presentación: redirección a página completa y pago integrado en un iframe.

Las dos formas funcionan en cualquier canal salvo Bot de Telegram. Ahí esa misma payment_url abre el bot de Paymos: no hay página de pago alojada que redirigir ni integrar.

Modo redirección

La redirección es la integración más sencilla. Envía al cliente a payment_url después de que tu servidor haya creado la factura:

<a href="https://checkout.paymos.io/invoice/inv_xxx">Pay invoice</a>

El cliente completa el pago en la página alojada por Paymos. Tu servidor entrega el pedido solo después de recibir y verificar el evento firmado del webhook.

Pago integrado

El pago integrado usa la misma payment_url con ?embed=true. Elígelo cuando tu servidor ya cree las facturas y solo necesites la interfaz de la página de pago dentro de tu propia página:

<iframe
  src="https://checkout.paymos.io/invoice/inv_xxx?embed=true"
  title="Paymos checkout"
  allow="clipboard-write"
  sandbox="allow-scripts allow-same-origin allow-forms"
  style="display:block;width:100%;max-width:460px;height:min(90vh,900px);border:0;"
></iframe>

Eventos del pago integrado

El iframe de la página de pago envía eventos de transporte por postMessage a la página contenedora:

Evento	Significado
paymos:succeeded	El pago alcanzó paid o paid_over.
paymos:failed	El pago llegó a un estado final de fallo, como underpaid, expired o cancelled.
paymos:close	El cliente pulsó cerrar o volver dentro de la página de pago integrada.

La página contenedora debe validar tanto el origen del remitente como la procedencia del iframe:

const iframe = document.querySelector('#paymos-checkout');

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://checkout.paymos.io') return;
  if (event.source !== iframe.contentWindow) return;
  if (!event.data || typeof event.data !== 'object') return;

  switch (event.data.type) {
    case 'paymos:succeeded':
      console.log('Payment UI succeeded:', event.data.invoice_id);
      break;
    case 'paymos:failed':
      console.warn('Payment UI failed:', event.data.reason);
      break;
    case 'paymos:close':
      iframe.remove();
      break;
  }
});

Modelo de seguridad

El sandbox recomendado para el iframe es deliberadamente reducido:

• —allow-scripts es necesario para la interactividad de la página de pago: llamadas a la API, temporizadores, botones de copiado y actualización del estado en vivo.
• —allow-same-origin permite que la página alojada por Paymos se ejecute con su propio origen en lugar de un origen opaco de sandbox.
• —allow-forms permite la interacción normal con formularios dentro de la página de pago.
• —allow-top-navigation se omite para que el iframe no pueda navegar la página del comercio.
• —allow-popups se omite porque la página de pago no necesita abrir ventanas de navegador adicionales.

Cuándo usar el Low-Code SDK en su lugar

Usa el Low-Code SDK cuando quieras que Paymos cree las facturas desde una configuración en el navegador, dibuje el botón de pago, gestione el ciclo de vida de la ventana modal, valide los mensajes del iframe y dispare por ti los CustomEvent de la familia paymos:*.

Integra el iframe a mano cuando tu backend ya se encargue de crear las facturas y solo necesites colocar la interfaz de pago dentro de tu página.