A assinatura nunca é verificada
Cole o corpo bruto do webhook no verificador de assinatura. Ele mostra cada passo intermediário e marca a primeira diferença; diga à sua IA exatamente o que difere.
Sem programar. Escolha o seu site e a sua ferramenta de IA, entregue a ela o prompt que geramos e ela integra a partir da nossa documentação e depois confere o próprio trabalho item por item.
Prompt universal · sem escolhas
Ajude-me a aceitar pagamentos em cripto no meu site com a blockwallets (os clientes pagam em USDT, USDC, BTC e mais; eu sou creditado em dólares americanos). 1. Leia primeiro a documentação em vez de adivinhar a API: https://blockwallets.io/llms-full.txt (documentação completa) e https://blockwallets.io/agents.md (regras de integração, erros comuns, checklist de aceitação). Avise-me se não conseguir abri-los. 2. Olhe o meu projeto, diga com o que ele é feito e como pretende integrar, e aguarde o meu OK. 3. Por padrão: “criar uma cobrança e redirecionar para a página de pagamento + webhook”. Sempre verifique as assinaturas dos webhooks e deduplique os webhooks, porque o mesmo pode chegar duas vezes. 4. Guarde o ID do merchant e a API key em variáveis de ambiente e faça tudo funcionar primeiro com as credenciais Test nas testnets. 5. Ao terminar, percorra o checklist de aceitação do agents.md item por item e me diga cada resultado. Não sou programador: a cada passo, diga o que você mudou e o que eu preciso fazer.
Ao abrir, o prompt completo é copiado para a área de transferência; o link leva apenas uma frase inicial curta. Cole quando abrir.
Quer um prompt que combine com o seu site? Três passos abaixo. ↓
Passo 1
Não tem certeza? Escolha “Outro / não sei” e a IA olhará primeiro o seu projeto.
Links de pagamento não precisam de código: painel → “Recebimentos › Links de pagamento” → informe um valor → criar, e depois compartilhe o link. A IA só coloca um botão no seu site.
Abrir o painelPasso 2
Cada ferramenta lê a documentação de um jeito; siga os passos correspondentes.
Abra um terminal na pasta do projeto do seu site e salve as regras de integração como AGENTS.md:
curl -fsSL https://blockwallets.io/agents.md -o AGENTS.mdO Codex lê o AGENTS.md sozinho. Para o Claude Code, execute também:
echo '@AGENTS.md' >> CLAUDE.mdDepois cole o prompt do passo 3.
Você também pode instalar o servidor MCP da blockwallets para que a IA consulte a documentação e crie cobranças de teste diretamente.Configurar o MCP →
Coloque o AGENTS.md também na raiz do projeto (o Cursor o detecta automaticamente):
curl -fsSL https://blockwallets.io/agents.md -o AGENTS.mdMude para o modo Agent e cole o prompt.
Você também pode instalar o servidor MCP da blockwallets para que a IA consulte a documentação e crie cobranças de teste diretamente.Configurar o MCP →
Cole o prompt em uma conversa nova, ou use “Abrir no ChatGPT / Claude” abaixo.
Se ele disser que não consegue abrir links, abra https://blockwallets.io/llms-full.txt, selecione tudo, copie e cole também.
Ele vai dar o código completo e onde colocá-lo; siga passo a passo. Uma ferramenta que edita o código por você (Claude Code, Codex, Cursor) poupa muito copiar e colar.
Cole o prompt. Se ela não conseguir abrir páginas web, cole também o conteúdo de llms-full.txt.
Passo 3
Ele se atualiza conforme você escolhe acima e traz os links da documentação, as armadilhas comuns e um checklist de aceitação.
Você é o meu desenvolvedor. Ajude-me a aceitar pagamentos em cripto no meu site com a blockwallets (os clientes pagam em USDT, USDC, BTC e mais 14 moedas; eu sou creditado em dólares americanos).
## Sobre mim
- Meu site é feito com: Não tenho certeza. Olhe primeiro o meu projeto, diga com o que ele é feito e depois comece.
- Como quero receber: Crie uma cobrança no checkout e redirecione o cliente para a página de pagamento da blockwallets; quando o dinheiro chegar, a blockwallets chama o meu servidor e eu marco o pedido como pago e o envio.
- Não sou programador. A cada passo, diga quais arquivos você alterou e o que eu preciso fazer (por exemplo, onde colocar as variáveis de ambiente). Não mude coisas demais de uma vez.
- AGENTS.md na raiz do projeto traz as regras de integração da blockwallets; leia-o primeiro, e leia https://blockwallets.io/llms-full.txt para os detalhes.
## Leia primeiro a documentação; não adivinhe a API de memória
- Documentação de integração completa (Markdown): https://blockwallets.io/llms-full.txt
- Regras de integração e erros comuns: https://blockwallets.io/agents.md
- Se o site já usa a Cryptomus, a NOWPayments ou a Coinbase Commerce, troque para a API compatível correspondente em vez de reescrever: https://blockwallets.io/docs/migrate.md?lang=en
- Se você não conseguir abrir um link, me avise e eu colo o conteúdo.
## Pontos-chave (onde as integrações costumam dar errado)
1. Todo endpoint é POST + JSON em https://blockwallets.io. Cabeçalhos: merchant = o UUID do merchant, sign = md5(base64(corpo da requisição) + API key). Assine exatamente a string JSON que você envia; não serialize de novo depois de assinar.
2. Crie uma cobrança com POST /v1/payment. Obrigatórios: amount (uma string com até duas casas decimais, p. ex. "42.00"), currency ("USD"), order_id (o número do meu pedido: letras, dígitos, - e _, até 100 caracteres). Passe também url_callback (a URL do webhook) e url_success (para onde o cliente volta depois de pagar). Redirecione o cliente para result.url.
3. Chamar de novo com o mesmo order_id retorna a mesma cobrança, então novas tentativas são seguras e nunca criam uma segunda cobrança.
4. As assinaturas dos webhooks precisam ser verificadas: analise o JSON do webhook, remova o campo sign, recodifique o resto como o json_encode do PHP faz (compacto, caracteres não ASCII mantidos, / escapada como \/) e então md5(base64(codificado) + API key) deve ser igual a sign. Esquecer de escapar / é o erro mais comum.
5. Marque o pedido como pago somente quando status for paid ou paid_over, usando payment_amount_usd. O mesmo webhook pode chegar mais de uma vez: deduplique por uuid + status. Responda com status 2xx depois de tratar.
6. Guarde o ID do merchant e a API key em variáveis de ambiente (p. ex. BW_MERCHANT, BW_API_KEY); nunca os escreva direto no código nem os envie ao repositório. Antes, cadastre o domínio da URL do webhook em “Domínios do site”, na página “Desenvolvedores › Integração e chaves” do painel.
7. Faça tudo funcionar primeiro com as credenciais Test (testnets, sem dinheiro real); passe para Live somente depois que eu confirmar.
## Quando terminar, confira cada item e me diga o resultado
- [ ] Criar uma cobrança de teste com as credenciais Test e obter o link da página de pagamento (result.url)
- [ ] Abrir a página de pagamento e clicar em “Simular pagamento” → valor total
- [ ] O meu servidor recebe um webhook com status paid e a assinatura é verificada
- [ ] O pedido correspondente é marcado como pago
- [ ] O mesmo webhook chegando de novo (reenvie-o por “Desenvolvedores › Log de webhooks” no painel, ou com POST /v1/payment/resend) não envia o pedido duas vezes
Se algum item falhar, diga onde travou e a mensagem de erro exata antes de mudar qualquer outra coisa.
Peça à IA que informe cada resultado. Passe para Live somente quando tudo passar.
Travou?
A maioria dos problemas é de assinatura. O texto bruto ajuda a IA muito mais do que uma descrição.
Cole o corpo bruto do webhook no verificador de assinatura. Ele mostra cada passo intermediário e marca a primeira diferença; diga à sua IA exatamente o que difere.
Cole para a sua IA a requisição e a resposta exatas (incluindo message). Quando a assinatura está errada, debug.body_base64 na resposta 401 é o texto que assinamos; peça à IA que o compare com o dela.
Peça à IA que percorra o checklist de aceitação a partir do primeiro item, um de cada vez, informando cada resultado. “Desenvolvedores › Log de webhooks” no painel mostra cada requisição de webhook e a resposta do seu servidor.
Segurança
O ID do merchant e a API key de Test rodam em testnets; mesmo que vazem, nenhum dinheiro pode se mover.
Coloque você mesmo a API key Live nas variáveis de ambiente do seu servidor. Nunca a cole em uma conversa nem a envie a um repositório.
Faça um commit (git commit) ou copie os arquivos do seu site antes de a IA começar, para poder voltar atrás.
Depois de passar para Live, pague um valor real pequeno por “Testar um pagamento” na página inicial do painel e confira se o pedido foi pago e se o saldo chegou.
Arquivo de regras
O AGENTS.md reúne o essencial da integração, os erros comuns e o checklist de aceitação. Coloque-o na raiz do seu projeto: Codex e Cursor o leem automaticamente, e o Claude Code o importa com @AGENTS.md.
curl -fsSL https://blockwallets.io/agents.md -o AGENTS.mdecho '@AGENTS.md' >> CLAUDE.mdArquivos para a IA
Perguntas frequentes
Para a maioria dos sites, sim. A IA escreve o código de criação de cobrança e de assinatura a partir da documentação; você coloca as credenciais em variáveis de ambiente e percorre o checklist de aceitação em modo de teste. Se você não quer código nenhum, use links de pagamento.
O mais fácil é uma ferramenta que edita o seu projeto e executa comandos: Claude Code, Codex ou Cursor. ChatGPT ou Claude na web também servem, mas você mesmo cola o código no seu site.
Somente as credenciais Test, e em um arquivo de ambiente em vez da conversa. Coloque você mesmo a API key Live no seu servidor.
Remova sign, recodifique o resto como o json_encode do PHP faz e escape / como \/. Cole o corpo bruto do webhook em /docs/sign para comparar cada passo e depois diga à IA o que difere.
Percorra o checklist de aceitação: crie uma cobrança de teste, simule o pagamento, veja o webhook ser verificado, veja o pedido marcado como pago e reenvie o mesmo webhook para confirmar que nada é enviado duas vezes. Pague um valor pequeno em Live antes de entrar em produção.