# Integrar com IA · blockwallets

> Adicione pagamentos em cripto da blockwallets sem escrever código você mesmo: escolha o seu site e a sua ferramenta de IA, copie o prompt gerado para o Claude Code, Codex, Cursor ou ChatGPT, e ele integra a partir da documentação e confere o próprio trabalho.
>
> HTML: https://blockwallets.io/docs/ai?lang=pt · English: https://blockwallets.io/docs/ai.md?lang=en

## Prompt universal

```text
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.
```

## Conte sobre o seu site.

Não tem certeza? Escolha “Outro / não sei” e a IA olhará primeiro o seu projeto.

- Com o que o seu site é feito: WordPress / WooCommerce · PHP · Node.js / Next.js · Python · Go · Java · Outro / não sei
- Como você quer receber:
  - Redirecionar para uma página de pagamento: Crie uma cobrança no checkout; avisamos o seu servidor quando ela for paga. Os pedidos seguem sozinhos.
  - Um endereço de depósito fixo por usuário: Cada usuário recebe um endereço permanente e recarrega qualquer valor, a qualquer momento.
  - Link de pagamento (sem código): Crie um link no painel e compartilhe. A IA só adiciona um botão.

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.

## Qual IA você usa?

- **Claude Code / Codex**: IA que edita o seu código e executa comandos. A mais fácil.
  - 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.md`
  - O Codex lê o AGENTS.md sozinho. Para o Claude Code, execute também:
  - `echo '@AGENTS.md' >> CLAUDE.md`
  - Depois 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. https://blockwallets.io/docs/mcp?lang=pt
- **Cursor / Windsurf / Copilot**: IA dentro do seu editor de código.
  - Coloque o AGENTS.md também na raiz do projeto (o Cursor o detecta automaticamente):
  - `curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md`
  - Mude 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. https://blockwallets.io/docs/mcp?lang=pt
- **ChatGPT / Claude (web)**: Só chat. Você mesmo cola o código no seu site.
  - 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.
- **Outra IA**: Gemini, o chat do Copilot e outras.
  - Cole o prompt. Se ela não conseguir abrir páginas web, cole também o conteúdo de llms-full.txt.

## Copie o prompt.

Ele se atualiza conforme você escolhe acima e traz os links da documentação, as armadilhas comuns e um checklist de aceitação.

Exemplo: Outro / não sei + redirecionar para uma página de pagamento + Claude Code / Codex

```text
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.
```

### Quando a IA terminar, confira isto

**Redirecionar para uma página de pagamento**

1. Criar uma cobrança de teste com as credenciais Test e obter o link da página de pagamento (result.url)
2. Abrir a página de pagamento e clicar em “Simular pagamento” → valor total
3. O meu servidor recebe um webhook com status paid e a assinatura é verificada
4. O pedido correspondente é marcado como pago
5. 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

**Um endereço de depósito fixo por usuário**

1. Abrir um endereço para um usuário de teste com as credenciais Test e obter o endereço e o link da página de depósito
2. Enviar um webhook de exemplo com POST /v1/test-webhook/wallet
3. O meu servidor recebe um webhook com type wallet e a assinatura é verificada
4. O saldo desse usuário aumenta em payment_amount_usd
5. O mesmo webhook chegando de novo não credita o saldo duas vezes

**Link de pagamento (sem código)**

1. O botão fica certo no computador e no celular
2. O botão abre o meu link de pagamento (use primeiro um link criado no modo Test)
3. Clicar em “Simular pagamento” na página de pagamento faz o pagamento aparecer em “Recebimentos › Transações” no painel

## Quando a IA trava.

- **A assinatura nunca é verificada**: Cole o corpo bruto do webhook no [verificador de assinatura](https://blockwallets.io/docs/sign?lang=pt). Ele mostra cada passo intermediário e marca a primeira diferença; diga à sua IA exatamente o que difere.
- **Um endpoint retorna erro**: 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.
- **Não sei onde travou**: 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.

### Quatro coisas para você vigiar.

- **Dê à IA apenas credenciais Test**: O ID do merchant e a API key de Test rodam em testnets; mesmo que vazem, nenhum dinheiro pode se mover.
- **Mantenha a API key Live fora das conversas**: 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 backup antes de a IA editar**: Faça um commit (git commit) ou copie os arquivos do seu site antes de a IA começar, para poder voltar atrás.
- **Pague você mesmo uma vez antes de entrar em produção**: 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.

## Um arquivo de regras para agentes de código.

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.

```sh
curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md
echo '@AGENTS.md' >> CLAUDE.md
```

- [Regras de integração (AGENTS.md)](https://blockwallets.io/agents.md)
- [Resumo de uma página](https://blockwallets.io/llms.txt)
- [Documentação completa](https://blockwallets.io/llms-full.txt)
- [Esta página em Markdown](https://blockwallets.io/docs/ai.md?lang=pt)
- [Documentação em Markdown](https://blockwallets.io/docs.md?lang=pt)
- [Servidor MCP](https://blockwallets.io/docs/mcp?lang=pt)

## Dúvidas, respondidas.

### Consigo mesmo integrar com IA sem saber programar?

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.

### Qual ferramenta de IA devo usar?

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.

### Devo dar a minha API key para a IA?

Somente as credenciais Test, e em um arquivo de ambiente em vez da conversa. Coloque você mesmo a API key Live no seu servidor.

### A assinatura do webhook nunca é verificada. E agora?

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.

### A IA diz que terminou. Como confiro?

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.