Integra un botón de pago o checkout

Cada enlace de pago que creas tiene un checkout alojado en https://payments.cosmospay.lat/{id}. Para cobrar sin sacar al pagador de tu sitio, agrega un script y luego uno de estos dos elementos:

• Botón de pago: <cosmos-pay-button> dibuja un botón. Al hacer clic abre el checkout alojado en una ventana emergente, y el botón avisa a tu página cuando cambia el estado.
• Checkout embebido: <cosmos-pay-checkout> dibuja un checkout compacto dentro de tu página: el importe, la red, el código QR, un botón Abrir en la wallet y el estado en vivo.

Ambos reciben el id del enlace de pago: el id de la intención de pago que creaste en tu servidor (la última parte de su URL de checkout). Crea primero la intención (consulta Intenciones de pago).

Agrega el script

<script src="https://payments.cosmospay.lat/embed/cosmos-pay.js" defer></script>

Una vez por página, en cualquier lugar. Los elementos son custom elements estándar, así que funcionan en HTML plano y en cualquier framework. El script no necesita clave de API: nunca pongas tu clave en una página web.

Botón de pago

<cosmos-pay-button link="cmh4x2k9a0001l70g8v5q3z2w"></cosmos-pay-button>

• La etiqueta es "Pagar con Cosmos Pay", en el idioma del pagador. El texto dentro del elemento la reemplaza: <cosmos-pay-button link="…">Pagar el pedido #1001</cosmos-pay-button>.
• Al hacer clic abre el checkout alojado en una ventana emergente de 480×780. Si el navegador la bloquea, la misma pestaña va al checkout.
• Mientras la ventana está abierta, el botón dispara los eventos de abajo cada vez que cambia el estado.
• Para cambiar su estilo, apunta a su parte: cosmos-pay-button::part(button) { … }.

Checkout embebido

<cosmos-pay-checkout link="cmh4x2k9a0001l70g8v5q3z2w" lang="es" theme="auto"></cosmos-pay-checkout>

Muestra el importe y el activo ("Importe libre" cuando el pagador lo elige), la descripción del enlace, la red, el código QR, Abrir en la wallet, el estado y el vencimiento cuando el enlace lo tiene. Lee el enlace desde el navegador del pagador y lo mantiene al día (cada 5 segundos mientras espera el pago, cada 3 mientras la red lo confirma, cada 30 una vez vencido) y se detiene cuando el pago se completa, falla o se cancela.

• Por defecto mide hasta 420px de ancho. Cámbialo con CSS sobre el elemento: cosmos-pay-checkout { max-width: none; }.
• No es un iframe: las páginas de pago se niegan a mostrarse dentro de un marco, a propósito. El elemento dibuja su propia interfaz en un shadow root, así que los estilos de tu página no le afectan.
• Muestra uno por pago. Cada uno lee su enlace unas 12 veces por minuto, y esa lectura está limitada por dirección del pagador.

Atributos

En el botón, lang fija la etiqueta y, cuando lo indicas, también el idioma del checkout alojado. Sin él, el checkout usa el idioma del propio pagador.

Eventos

Ambos elementos disparan estos eventos sobre sí mismos. Se propagan (bubble), así que también puedes escucharlos en document.

status es uno de los valores de la API: PENDING, SUBMITTED, SUCCEEDED, FAILED, CANCELLED, EXPIRED. SUBMITTED significa que el pago se envió y la red lo está confirmando. EXPIRED no es definitivo: un pago verificado tarde todavía puede pasar un enlace vencido a SUCCEEDED.

const checkout = document.querySelector('cosmos-pay-checkout');

checkout.addEventListener('cosmospay:status', (event) => {
  console.log(event.detail.id, event.detail.status);
});

checkout.addEventListener('cosmospay:paid', async () => {
  // Update the page, then ask YOUR server whether the order is paid.
  const res = await fetch('/orders/1001/status');
  // …
});

El botón de pago solo recibe noticias del checkout mientras su ventana está abierta, y solo si el navegador mantiene conectadas las dos ventanas. Si tu página envía Cross-Origin-Opener-Policy: same-origin, usa same-origin-allow-popups en su lugar, o el botón no recibirá actualizaciones. Cuando la ventana se bloquea y el checkout se abre en la misma pestaña, no hay eventos, pero tu servidor igualmente recibe el webhook.

Content Security Policy

Si tu sitio envía una Content-Security-Policy, permite:

Los elementos no necesitan estilos ni scripts en línea. El script se actualiza en el mismo lugar con cada versión, por eso se publica sin un hash integrity fijo.

Próximos pasos