Cómo agregar un botón de pago cripto o un checkout a tu sitio web
Para cobrar en stablecoins en tu propio sitio web, carga una vez el script de inserción de Cosmos Pay y agrega un elemento cosmos-pay-button o cosmos-pay-checkout con el id de un enlace de pago. El botón abre el checkout alojado en una ventana emergente, y el checkout embebido dibuja el pago dentro de tu página. La página no necesita ninguna clave de API, y tu servidor confirma el pago con un webhook firmado.
Botón o checkout embebido
- El botón de pago (cosmos-pay-button) abre el checkout alojado en una ventana emergente centrada sobre tu página. Si el navegador bloquea la ventana emergente, la misma pestaña va al checkout.
- El checkout embebido (cosmos-pay-checkout) dibuja el pago dentro de tu página, con un ancho de hasta 420 píxeles: el monto, el código QR, un botón que abre la wallet de quien paga y el estado en vivo.
- Ambos funcionan con enlaces de pago en Stellar, Solana y Monad, en inglés, español, portugués, francés, alemán, hindi y chino.
De dónde sale el enlace
Cada elemento muestra un enlace de pago, indicado por su id en el atributo link. Crea el enlace en el dashboard, o desde tu servidor con la API de pagos o el SDK de TypeScript cuando tu cliente finaliza la compra, y pon su id en la página. La página lee el enlace sin una clave de API, así que tu clave secreta se queda en tu servidor.
Muestra un checkout embebido por pago: un enlace se paga una sola vez.
Atributos y estilos
- link: el id del enlace de pago. Obligatorio.
- lang: el idioma, como es o es-AR. Por defecto, el idioma del navegador de quien paga o, si no, inglés.
- theme: light (el valor por defecto), dark o auto, que sigue la configuración del sistema de quien paga.
- demo: muestra un ejemplo que no se puede pagar y no envía ninguna solicitud, para demostraciones.
- El texto dentro del botón reemplaza su etiqueta, y ::part(button) y ::part(card) permiten que tu CSS cambie el estilo de los elementos.
Agrega un botón de pago, paso a paso
Carga el script
Agrega una etiqueta script a tu página, una sola vez: https://payments.cosmospay.lat/embed/cosmos-pay.js, con el atributo defer.
Obtén un enlace de pago
Crea un enlace en el dashboard, o desde tu servidor cuando tu cliente finaliza la compra, y guarda su id.
Agrega el elemento
Escribe un elemento cosmos-pay-button o cosmos-pay-checkout con link definido como ese id y, si quieres, lang o theme.
Permítelo en tu CSP
Si tu sitio envía una Content Security Policy, permite script-src https://payments.cosmospay.lat, connect-src https://api.cosmospay.lat e img-src data:.
Pruébalo
Usa un enlace creado en Sandbox: el checkout embebido indica que funciona en una red de pruebas. El atributo demo muestra un ejemplo sin ningún enlace.
Confírmalo en tu servidor
Agrega un endpoint de webhook y entrega el pedido cuando llegue PAYMENT_INTENT_SUCCEEDED.
Eventos y confirmación del pago
Ambos elementos disparan los eventos cosmospay:status y cosmospay:paid en tu página, con el id y el estado del enlace. Úsalos para actualizar lo que ve quien paga, no para entregar el pedido: un evento en la página se puede falsificar.
Entrega el pedido cuando tu servidor reciba PAYMENT_INTENT_SUCCEEDED, el webhook firmado que Cosmos Pay envía cuando la red confirma el pago. Si tu página envía una Cross-Origin-Opener-Policy con valor same-origin, o si se bloquea la ventana emergente, el botón no envía eventos.
¿La página necesita mi clave de API?
No. Los elementos leen el enlace de pago sin una clave. Crea los enlaces en tu servidor, donde se queda la clave.
¿El checkout embebido es un iframe?
No. Se dibuja dentro de tu página en su propio shadow DOM, así que no hace falta ninguna regla frame-src. El checkout alojado en sí no se puede mostrar dentro de un frame.
¿Un botón puede recibir muchos pagos?
No. Un enlace se paga una sola vez, así que dale a cada pago su propio enlace, por ejemplo creándolo en tu servidor cuando el cliente finaliza la compra.
¿Funciona en cualquier sitio web?
Sí, en cualquier página que pueda cargar un script, siempre que su Content Security Policy permita el script, la API y las imágenes data:.
