Como adicionar um botão de pagamento cripto ou um checkout ao seu site
Para receber um pagamento em stablecoins no seu próprio site, carregue uma vez o script de incorporação da Cosmos Pay e adicione um elemento cosmos-pay-button ou cosmos-pay-checkout com o id de um link de pagamento. O botão abre o checkout hospedado numa janela pop-up, e o checkout incorporado desenha o pagamento dentro da sua página. A página não precisa de chave de API, e o seu servidor confirma o pagamento por um webhook assinado.
Botão ou checkout incorporado
- O botão de pagamento (cosmos-pay-button) abre o checkout hospedado numa janela pop-up centralizada sobre a sua página. Se o navegador bloquear o pop-up, a mesma aba vai para o checkout.
- O checkout incorporado (cosmos-pay-checkout) desenha o pagamento dentro da sua página, com até 420 pixels de largura: o valor, o QR code, um botão que abre a carteira de quem paga e o status ao vivo.
- Os dois funcionam com links de pagamento na Stellar, Solana e Monad, em inglês, espanhol, português, francês, alemão, hindi e chinês.
De onde vem o link
Cada elemento mostra um link de pagamento, indicado pelo id no atributo link. Crie o link no dashboard, ou no seu servidor com a API de pagamentos ou o SDK em TypeScript quando seu cliente finaliza a compra, e coloque o id dele na página. A página lê o link sem chave de API, então a sua chave secreta fica no seu servidor.
Mostre um checkout incorporado por pagamento: um link é pago uma vez.
API de links de pagamentoComo aceitar pagamentos em USDC online
Atributos e estilo
- link: o id do link de pagamento. Obrigatório.
- lang: o idioma, como es ou es-AR. Por padrão, o idioma do navegador de quem paga; se não houver, inglês.
- theme: light (o padrão), dark ou auto, que segue a configuração do sistema de quem paga.
- demo: mostra um exemplo que não pode ser pago e não envia nenhuma requisição, para demonstrações.
- O texto dentro do botão substitui o rótulo dele, e ::part(button) e ::part(card) permitem que o seu CSS mude o estilo dos elementos.
Adicione um botão de pagamento, passo a passo
Carregue o script
Adicione uma tag script à sua página, uma única vez: https://payments.cosmospay.lat/embed/cosmos-pay.js, com o atributo defer.
Obtenha um link de pagamento
Crie um link no dashboard, ou no seu servidor quando seu cliente finaliza a compra, e guarde o id dele.
Adicione o elemento
Escreva um elemento cosmos-pay-button ou cosmos-pay-checkout com link definido como esse id e, se quiser, lang ou theme.
Permita-o na sua CSP
Se o seu site envia uma Content Security Policy, permita script-src https://payments.cosmospay.lat, connect-src https://api.cosmospay.lat e img-src data:.
Teste
Use um link criado no Sandbox: o checkout incorporado avisa que funciona numa rede de testes. O atributo demo mostra um exemplo sem nenhum link.
Confirme no seu servidor
Adicione um endpoint de webhook e entregue o pedido quando PAYMENT_INTENT_SUCCEEDED chegar.
Eventos e confirmação do pagamento
Os dois elementos disparam os eventos cosmospay:status e cosmospay:paid na sua página, com o id e o status do link. Use-os para atualizar o que quem paga vê, não para entregar o pedido: um evento na página pode ser falsificado.
Entregue o pedido quando o seu servidor receber PAYMENT_INTENT_SUCCEEDED, o webhook assinado que a Cosmos Pay envia assim que a rede confirma o pagamento. Se a sua página envia uma Cross-Origin-Opener-Policy com valor same-origin, ou se o pop-up for bloqueado, o botão não envia eventos.
Perguntas e respostas.
Pagamentos por rede:Pagamentos na StellarPagamentos na SolanaPagamentos na Monad
A página precisa da minha chave de API?
Não. Os elementos leem o link de pagamento sem chave. Crie os links no seu servidor, onde a chave fica.
O checkout incorporado é um iframe?
Não. Ele é desenhado dentro da sua página, no próprio shadow DOM, então nenhuma regra frame-src é necessária. O próprio checkout hospedado não pode ser exibido dentro de um frame.
Um botão pode receber vários pagamentos?
Não. Um link é pago uma vez, então dê a cada pagamento o próprio link, por exemplo criando-o no seu servidor quando o cliente finaliza a compra.
Funciona em qualquer site?
Sim, em qualquer página que possa carregar um script, desde que a Content Security Policy dela permita o script, a API e imagens data:.
