# Documentação da blockwallets: formas de integrar > Escolha uma integração: links de pagamento, PDV e botões incorporados sem código; a API compatível com a Cryptomus ou a API REST nativa; APIs compatíveis com Cryptomus, NOWPayments e Coinbase Commerce; prompts de IA, AGENTS.md e MCP. > > HTML: https://blockwallets.io/docs?lang=pt · English: https://blockwallets.io/docs.md?lang=en ## Documentação A blockwallets permite que você aceite USDT e USDC, além de BTC, LTC e moedas nativas (creditadas em dólares americanos a uma cotação travada). Todas as integrações abaixo criam o mesmo tipo de cobrança na mesma página de pagamento hospedada, com as mesmas confirmações, taxas e saldo; muda apenas a forma como o seu sistema fala com a gente. Escolha a que combina com você e siga a página dela. ### Escolha uma integração Agrupadas pelo seu ponto de partida. Cada cartão abre o guia completo. #### Sem código Receba pelo painel do lojista; não há nada para instalar. - [Links de pagamento](https://blockwallets.io/docs?lang=pt#links): Informe um valor (ou deixe o pagador digitar) e compartilhe o link ou o QR code. Cada visita cria uma cobrança nova. - [PDV para lojas](https://blockwallets.io/docs?lang=pt#pos): A equipe abre um link de PDV no celular ou tablet, digita o valor e o cliente escaneia o QR code. - [Botão incorporado](https://blockwallets.io/docs?lang=pt#embed): Cole um botão “Pagar” ou “Doar” em qualquer site: HTML simples, ou HTML mais uma tag de script. #### Nova integração por API Você vai escrever a integração do zero. - [API REST nativa](https://blockwallets.io/docs/api?lang=pt): Chave Bearer, valores em centavos, `ref` idempotente, webhooks HMAC-SHA256 e uma API de eventos. As chaves você mesmo gera no painel. - [API compatível com a Cryptomus](https://blockwallets.io/docs/cryptomus?lang=pt): POST + JSON com assinatura md5. Você mesmo gera as credenciais no painel, e cada endpoint principal tem um painel “Testar”. #### Migrando de outro gateway Mantenha o seu código: APIs compatíveis, então você só troca a URL base e as chaves. - [Da Cryptomus](https://blockwallets.io/docs/cryptomus?lang=pt#cryptomus): Troque `https://api.cryptomus.com` por `https://blockwallets.io` e use um novo merchant e uma nova API key. Caminhos, parâmetros, `sign` e webhooks continuam iguais. - [Da NOWPayments](https://blockwallets.io/docs/nowpayments?lang=pt): Troque `https://api.nowpayments.io/v1` por `https://blockwallets.io/nowpayments/v1` e use uma nova API key e um novo IPN secret. `x-nowpayments-sig` continua igual. - [Da Coinbase Commerce](https://blockwallets.io/docs/coinbase-commerce?lang=pt): Passe `https://blockwallets.io/coinbase/` como URL base do SDK e use uma nova API key e um novo webhook shared secret. `X-CC-Webhook-Signature` continua igual. #### Deixe a IA integrar Para quem não escreve código, mas usa uma ferramenta de programação com IA. - [Gerador de prompt](https://blockwallets.io/docs/ai?lang=pt): Escolha o seu site, o estilo de pagamento e a ferramenta de IA; copie o prompt gerado para Claude Code, Codex, Cursor ou ChatGPT. - [AGENTS.md](https://blockwallets.io/agents.md): Regras de integração, erros comuns e uma lista de verificação de aceite; salve na raiz do seu projeto para os agentes de programação. - [Servidor MCP](https://blockwallets.io/docs/mcp?lang=pt): Deixe uma ferramenta de IA pesquisar esta documentação e criar cobranças de teste diretamente. #### Ferramentas Ajuda de depuração que roda no seu navegador. - [Verificador de assinatura](https://blockwallets.io/docs/sign?lang=pt): Cole o corpo de uma requisição ou de um webhook e veja cada etapa da assinatura e onde a sua difere. A API key nunca sai do seu navegador. ### Compatível com a Cryptomus ou nativa? As duas criam as mesmas cobranças na mesma página de pagamento, com as mesmas taxas e o mesmo saldo. A diferença está no estilo das requisições, no formato do webhook e em como você obtém as credenciais. | | Compatível com a Cryptomus | REST nativa | | --- | --- | --- | | Credenciais | Você mesmo gera no painel, em “Desenvolvedores › Integração e chaves” (um conjunto para Live e outro para Test) | Também você mesmo gera no painel, em “Desenvolvedores › Integração e chaves”: uma chave Live e uma Test (`bw_live_…` / `bw_test_…`) com as respectivas chaves de assinatura de webhook | | Requisições | Toda chamada é `POST` + JSON, com os cabeçalhos `merchant` e `sign` = `md5(base64(request body) + API key)` | REST (`GET` / `POST`) com `Authorization: Bearer`; o prefixo da chave define Live ou Test | | Valores | Strings decimais como `"42.00"`, em USD, USDT ou USDC (todas 1:1) | Inteiros em centavos de dólar, como `4200`; somente USD | | Novas tentativas | O mesmo `order_id` retorna a cobrança existente | O mesmo `ref` com os mesmos parâmetros retorna a cobrança existente; com parâmetros diferentes retorna 409 | | Webhooks | Enviados ao `url_callback` de cada cobrança; a assinatura é o campo `sign` do corpo | Enviados à URL de webhook definida no painel; `X-BW-Signature` = HMAC-SHA256 com timestamp; listagem e reenvio por `/v1/events` | | Endereços estáticos | `/v1/wallet`: uma rede por chamada | `/v1/deposit-accounts`: todas as redes de uma vez para um cliente | | Ferramentas | Painéis “Testar”, o verificador de assinatura, prompts de IA e o servidor MCP; os SDKs e plugins existentes da Cryptomus funcionam | Esta referência e seus exemplos de código | Está começando do zero? Use a API REST nativa: valores em centavos, `ref` idempotente, assinaturas de webhook com carimbo de tempo e chaves que você mesmo gera no painel. Já usa a Cryptomus, ou quer usar um SDK ou plugin da Cryptomus existente? Use a API compatível com a Cryptomus. ### Início rápido Do zero a um pagamento de teste em cinco passos (API compatível com a Cryptomus; as outras APIs seguem os mesmos passos com as próprias credenciais). - Solicite acesso na [página inicial](https://blockwallets.io/?lang=pt#join). Depois de aprovado, entre no [painel do lojista](https://blockwallets.io/dashboard). - Abra “Desenvolvedores › Integração e chaves” no painel, gere um merchant e uma API key na coluna Test e adicione os domínios do seu site. - O seu servidor cria uma cobrança com `POST /v1/payment` e redireciona o cliente para `result.url`. - Pague com “Simular pagamento” na página de pagamento e confira se o seu tratador de webhook verifica o `sign` e credita por `payment_amount_usd`. - Mude para as credenciais da coluna Live e pague uma vez um valor real pequeno (“Testar um pagamento” na página inicial do painel). ```http POST https://blockwallets.io/v1/payment merchant: sign: md5(base64(body) + API key) Content-Type: application/json { "amount": "42.00", "currency": "USD", "order_id": "order_1042", "url_callback": "https://shop.example/webhooks/crypto", "url_return": "https://shop.example/cart", "url_success": "https://shop.example/thanks?order=1042" } ``` O código em Node.js, PHP e Python de cada passo está na documentação da [API compatível com a Cryptomus](https://blockwallets.io/docs/cryptomus?lang=pt#api); se preferir que uma IA faça isso, comece pelo [gerador de prompt](https://blockwallets.io/docs/ai?lang=pt). ### Links de pagamento (sem código) Painel do lojista → “Recebimentos › Links de pagamento” → informe uma descrição e um valor (fixe uma rede ou deixe o cliente escolher) → criar. Cada link tem uma URL e um QR code. - Toda vez que alguém abre o link, uma nova cobrança é criada, então um mesmo link pode ser reutilizado (p. ex. “Plano de membros $99”). - Cada pagamento aparece em “Recebimentos › Transações”; saque-o para a sua carteira em “Fundos › Saldo e saques”. - Se você criou credenciais e uma URL de webhook em “Desenvolvedores › Integração e chaves”, os pagamentos feitos por links também são notificados, no [formato de webhook compatível com a Cryptomus](https://blockwallets.io/docs/cryptomus?lang=pt#webhooks). - Para parar de receber, clique em “Desativar” e o link deixa de funcionar imediatamente. ### PDV para lojas Para balcões e barracas: painel do lojista → “Recebimentos › PDV” → abra um terminal e pegue um link de PDV. A equipe abre no celular ou tablet, digita um valor e aparece um QR code de pagamento; quando o cliente paga, a tela mostra “Paid”. - Uma cobrança de PDV vale por 30 minutos. Os pagamentos vão para o seu saldo e aparecem em “Recebimentos › Transações”, e você é notificado na sua URL de webhook como nos links de pagamento. - Um link de PDV só pode receber pagamentos: ele não vê o seu saldo, saques, outros pedidos, configurações nem credenciais. - Perdeu um aparelho ou um funcionário saiu? Revogue esse terminal no painel e o link dele deixa de funcionar imediatamente. ### Botão incorporado Painel do lojista → “Recebimentos › Links de pagamento” → “Botão incorporado”: escolha o texto, a cor, o tamanho e o formato e copie o trecho. Ao clicar no botão, abre-se a página de pagamento daquele link de pagamento. - HTML simples: um link estilizado sem script, que funciona em qualquer lugar onde você possa colar HTML (construtores de sites, fóruns, assinaturas de e-mail). - Com o script: adicione `data-blockwallets` e uma tag `/embed.js`; no computador a página de pagamento abre numa janelinha centralizada, no celular abre normalmente. - O script não envia requisições, não grava cookies e não adiciona iframe. Se a página o bloquear, o botão continua sendo um link comum que funciona. Nos trechos abaixo, troque `/l/pl_…` pelo endereço do seu próprio link de pagamento. #### HTML simples ```html Pay with crypto ``` #### HTML + script ```html Pay with crypto ```