How to add a crypto pay button or checkout to your website
To take a stablecoin payment on your own website, load the Cosmos Pay embed script once and add a cosmos-pay-button or a cosmos-pay-checkout element with a payment link’s id. The button opens the hosted checkout in a popup, and the embedded checkout draws the payment inside your page. The page needs no API key, and your server confirms the payment through a signed webhook.
Button or embedded checkout
- The pay button (cosmos-pay-button) opens the hosted checkout in a popup centred on your page. If the browser blocks the popup, the same tab goes to the checkout instead.
- The embedded checkout (cosmos-pay-checkout) draws the payment inside your page, up to 420 pixels wide: the amount, the QR code, a button that opens the payer’s wallet and the live status.
- Both work for payment links on Stellar, Solana and Monad, in English, Spanish, Portuguese, French, German, Hindi and Chinese.
Where the link comes from
Each element shows one payment link, named by its id in the link attribute. Create the link in the dashboard, or from your server with the Payments API or the TypeScript SDK when your customer checks out, and put its id in the page. The page reads the link without an API key, so your secret key stays on your server.
Show one embedded checkout per payment: a link is paid once.
Attributes and styling
- link: the payment link’s id. Required.
- lang: the language, such as es or es-AR. By default, the payer’s browser language, else English.
- theme: light (the default), dark, or auto, which follows the payer’s system setting.
- demo: shows a sample that cannot be paid and sends no request, for showcases.
- Text inside the button replaces its label, and ::part(button) and ::part(card) let your CSS restyle the elements.
Add a pay button, step by step
Load the script
Add one script tag to your page, once: https://payments.cosmospay.lat/embed/cosmos-pay.js, with the defer attribute.
Get a payment link
Create a link in the dashboard, or from your server when your customer checks out, and keep its id.
Add the element
Write a cosmos-pay-button or a cosmos-pay-checkout element with link set to that id, and lang or theme if you like.
Allow it in your CSP
If your site sends a Content Security Policy, allow script-src https://payments.cosmospay.lat, connect-src https://api.cosmospay.lat and img-src data:.
Test it
Use a link created in Sandbox: the embedded checkout says it runs on a test network. The demo attribute shows a sample without any link.
Confirm it on your server
Add a webhook endpoint and deliver the order when PAYMENT_INTENT_SUCCEEDED arrives.
Events and confirming the payment
Both elements fire cosmospay:status and cosmospay:paid events on your page, with the link’s id and status. Use them to update what the payer sees, not to deliver the order: an event in the page can be faked.
Deliver the order when your server receives PAYMENT_INTENT_SUCCEEDED, the signed webhook Cosmos Pay sends once the network confirms the payment. If your page sends a Cross-Origin-Opener-Policy of same-origin, or the popup is blocked, the button sends no events.
Does the page need my API key?
No. The elements read the payment link without a key. Create links on your server, where the key stays.
Is the embedded checkout an iframe?
No. It draws inside your page in its own shadow DOM, so no frame-src rule is needed. The hosted checkout itself cannot be framed.
Can one button take many payments?
No. A link is paid once, so give each payment its own link, for example by creating it on your server when the customer checks out.
Does it work on any website?
Yes, on any page that can load a script, as long as its Content Security Policy allows the script, the API and data: images.
