O botão de compra
O botão de compra são algumas linhas de HTML que você cola em qualquer página. Sem framework, sem passo de instalação do seu lado. O botão é renderizado na primeira pintura; o seletor de provedores e os SDKs dos provedores de pagamento carregam sob demanda na primeira vez que um comprador clica. Funciona em qualquer site ou framework que renderize HTML, incluindo os construtores de sites sem código que permitem colar embeds de HTML.
Funcionamento confirmado com: Angular, Hugo, Jekyll, HTML puro, Webflow (embed de Custom Code), Carrd (elemento Embed), Framer (embed de HTML), Squarespace (Code Block), WordPress (bloco Custom HTML), Ghost, sites do Notion (widgets de embed de HTML). Se o seu site permite colar HTML em uma página, o botão de compra funciona ali.
Referência de atributos
| Atributo | Obrigatório | O que aceita | Notas |
|---|---|---|---|
endpoint | Não | String de URL | Quase sempre omita isto. O botão detecta automaticamente a sua base de API: https://api.coinmoebius.com em produção, http://localhost:8787 em localhost. Defina apenas como substituição para uma configuração incomum (por exemplo, um proxy auto-hospedado na frente da API). |
project-id | Sim | String, prefixada com proj_ | Da sua página de projeto no painel. Seguro para expor publicamente, é um identificador, não uma credencial. |
product-id | Sim (no modo estrito) / Recomendado (no modo ad-hoc) | String, qualquer formato que você escolher | O seu identificador de produto interno. No modo estrito (o padrão), é assim que o worker consulta o preço no seu catálogo. No modo ad-hoc, ele ainda é repassado aos seus webhooks em metadata.productId para que você possa mapear transações de volta ao estoque. Veja a seção Modo estrito vs modo ad-hoc abaixo. |
amount | Apenas no modo ad-hoc | Número decimal como string | O preço em unidades maiores (por exemplo, dólares, não centavos). Deve ser positivo. Omita isto no modo estrito. O worker lê o preço canônico do seu catálogo e ignora qualquer valor no HTML. Obrigatório apenas quando o projeto está em modo ad-hoc e o product-id não está no catálogo. |
currency | Apenas no modo ad-hoc | Código ISO 4217 de três letras ou o seu próprio nome de unidade | USD, EUR, etc. para métodos de cartão / cripto. O provedor de pagamento por correio aceita qualquer string (por exemplo, GBK) porque é o comerciante quem liquida a transação. Mesma regra do amount: omita no modo estrito, obrigatório no modo ad-hoc para produtos que não estão no catálogo. |
label | Não | String | O texto do botão. O padrão é Buy. Use isto para distinguir botões na mesma página. |
customer-ref | Não | String, qualquer formato que você escolher | Um identificador opaco para o comprador no seu próprio sistema, como um id de usuário logado. O botão o encaminha para o worker como metadata.customerRef, e o worker marca a transação com ele. Depois você pode perguntar "qual dos meus usuários pagou?" usando o seu próprio id, sem que guardemos nenhum dado real do cliente. Omita para checkouts anônimos. |
theme | Não | dark ou light | Escolhe o esquema de cores embutido para o botão e o popup juntos. O padrão é dark. Defina theme="light" para o esquema claro. As suas variáveis CSS substituem qualquer um dos dois. Veja o guia de estilo. |
editable-amount | Não | true ou false | Quando true, o popup mostra um campo de valor que o comprador preenche (gorjetas, doações, pague o quanto quiser). O padrão é false, onde o amount que você definiu fica fixo e nenhum campo aparece. Os botões de pagamento permanecem desativados até que o valor seja um número positivo. |
Múltiplos botões em uma página
O script registra o botão uma vez, depois qualquer número de instâncias pode ser renderizado em uma página. Cada instância é independente. O exemplo abaixo usa o modo estrito (o padrão): sem amount ou currency no HTML, porque o worker consulta o preço de cada produto no seu catálogo.
<coin-moebius-buy
project-id="proj_YOUR_ID"
product-id="t-shirt-medium"
label="T-shirt (medium)">
</coin-moebius-buy>
<coin-moebius-buy
project-id="proj_YOUR_ID"
product-id="mug-blue"
label="Blue mug">
</coin-moebius-buy>Se o seu projeto está em modo ad-hoc (widgets de doação, caixinhas), cada botão também inclui amount e currency. Veja Modo estrito vs modo ad-hoc para o panorama completo.
Estilizando o botão
O botão de compra é renderizado dentro de um Shadow DOM, o que significa que nenhum CSS existente da sua página alcança o interior dele. Isso é deliberado: mantém o botão com a mesma aparência em todos os sites, e impede que uma regra perdida de * { box-sizing: ... } quebre o modal do seletor. Você o estiliza através de duas superfícies a partir da sua própria folha de estilo: propriedades CSS personalizadas para cores, fontes, e formato, e seletores ::part() para todo o resto. Sem nenhum JavaScript envolvido.
Cada variável e parte está documentada no guia de estilo, com exemplos ao vivo em que você pode clicar e copiar:
Abrir o guia de estilo interativo →
As URLs de sucesso e cancelamento
Quando você conecta o Stripe ou o NOWPayments na aba Provedores do painel, você define duas URLs:
- URL de sucesso, onde o comprador chega após um pagamento bem-sucedido. Stripe e NOWPayments acrescentam um parâmetro de consulta (
?session_id=...para o Stripe,?NP_id=...para o NOWPayments) para que a sua página de sucesso possa identificar qual transação foi concluída. A maioria dos sites estáticos apenas mostra uma mensagem genérica de "Obrigado, o seu pagamento está sendo processado" e depende do painel como a fonte da verdade. - URL de cancelamento, onde o comprador chega se desistir antes de pagar. Muitas vezes a mesma que a sua página de carrinho.
Ambas as URLs são configuradas por provedor no painel, o elemento não precisa saber sobre elas.