Integrar pagamento Pix com IA

Para integrar pagamento Pix com IA, o assistente precisa de duas coisas: a referência certa da API e regras claras de segurança. A xFlow já publica a referência num formato feito para isso, o llms.txt. As regras, você escreve no pedido. A xFlow não tem plugin nem integração própria com Cursor, Claude, Lovable, v0 ou Bolt: você entrega o texto como contexto, como faria com qualquer documentação.

O que é o llms.txt da xFlow

É a documentação da API Pix em texto puro, no padrão llms.txt, publicada para que assistentes de IA ajudem a integrar. Num único arquivo, ela traz o que um modelo de linguagem precisa para não inventar:

• a base https://app.xflowpayments.com/api/v1 e a autenticação HTTP Basic (chave pública como usuário, segredo como senha);
• valores sempre em centavos, como inteiros;
• o modo de teste com chaves pk_test_ e o endpoint de simulação de pagamento;
• cobrança, consulta, listagem, split, saldo, saque e estorno, com exemplos de requisição e resposta;
• os códigos de erro e os webhooks assinados com HMAC-SHA256;
• o que ainda não existe na API, como cartão e checkout hospedado.

A documentação completa tem o mesmo conteúdo em página, com exemplos em cURL e Node.js. Para o assistente, o llms.txt é o ponto de partida.

Como passar a documentação para cada ferramenta

API Pix no Cursor e em editores com IA

Em editores com IA, como o Cursor, salve o llms.txt como arquivo do projeto e cite esse arquivo no pedido:

curl --create-dirs -o docs/xflow-llms.txt https://app.xflowpayments.com/llms.txt

Assim a referência fica no projeto, à mão a cada pedido. Quando a documentação mudar, baixe o arquivo de novo.

Claude e a API Pix

Em assistentes de conversa, como o Claude, anexe o arquivo ou cole o texto do llms.txt na conversa antes do pedido. Se a ferramenta que você usa abre links, passe também a URL da documentação. Peça o código na sua linguagem e compare com os exemplos da API Pix em Node.js, PHP e Python, que seguem a documentação.

Lovable, v0 e Bolt: pagamento Pix em apps gerados por IA

Em ferramentas que geram o app a partir de um prompt, como Lovable, v0 e Bolt, cole no prompt as seções do llms.txt que você vai usar: autenticação, criar cobrança e webhooks. Diga com todas as letras onde cada parte roda:

• a chamada à API fica numa função de servidor ou rota de backend, nunca no código que roda no navegador;
• o segredo fica numa variável de ambiente ou no cofre de segredos da plataforma;
• o navegador recebe só o pix.copyPaste e o pix.qrCodeBase64 para mostrar ao cliente.

O webhook precisa de uma URL https:// pública. Cadastre a do app publicado, não um endereço local.

Prompt de exemplo

Adapte a stack e os nomes, mas mantenha as regras:

Use como referência única a documentação da API Pix da xFlow em
docs/xflow-llms.txt (https://app.xflowpayments.com/llms.txt).
Não invente endpoints nem campos que não estejam nela.

Stack: Node.js com Express (troque pela sua).

1. Crie a rota de servidor POST /api/pagar, que chama
   POST https://app.xflowpayments.com/api/v1/charges com HTTP Basic
   (usuário XFLOW_PUBLIC_KEY, senha XFLOW_SECRET_KEY, lidos de
   variáveis de ambiente). Valor em centavos, inteiro. Envie
   Idempotency-Key e external_reference com o id do pedido.
2. Devolva ao navegador só id, pix.copyPaste e pix.qrCodeBase64.
3. Crie a rota POST /api/webhooks/xflow. Valide o header
   x-webhook-signature: "sha256=" + HMAC-SHA256 do corpo cru com
   XFLOW_WEBHOOK_SECRET, comparação em tempo constante. Responda 401
   se não bater. Dê baixa só em transaction.paid com livemode true,
   sem processar o mesmo evento duas vezes.
4. Trate 400, 401, 409 e 429 (respeite o header retry-after).
5. Use chaves de teste e mostre como simular o pagamento com
   POST /api/v1/test/charges/{id}/pay.

Cuidados com o código gerado

1. Segredo só no servidor. Procure sk_live_ e sk_test_ em todo arquivo que vai para o navegador e no repositório. Não cole o segredo real na conversa com o assistente.
2. Revise contra a documentação. Confira cada endpoint, campo e status. Um detalhe que confunde: na criação o valor se chama amountCents, mas no webhook ele chega como amount. Se o assistente inventou um campo, a API responde 400 validation.
3. Valide a assinatura do webhook. O HMAC é calculado sobre o corpo cru. Código que faz JSON.parse antes de validar quebra a assinatura. O passo a passo, com exemplos, está em webhook Pix.
4. Filtre o modo de teste. Eventos do sandbox chegam com livemode: false. Nunca libere um pedido real com base neles.
5. Teste antes de ir ao ar. Rode o fluxo inteiro com chaves de teste, inclusive os erros. O roteiro está em API Pix sandbox.
6. Desconfie de recursos que não existem. Se o código gerado tratar cartão ou checkout hospedado, ele não segue a API atual.

Quando algo falhar, use o request_id que vem em toda resposta: ele localiza a chamada em Integrações > Logs da API. O caminho completo da integração está em Desenvolvedores.

E se você não quer escrever código

O mesmo fluxo de cobrança e webhook pode ser montado em ferramentas de automação, com os recursos genéricos de requisição HTTP e webhook de cada uma. Veja os guias de Pix no n8n, Pix no Zapier e Pix no Make.