Pix no n8n

Para usar Pix no n8n com a xFlow, você combina dois nós nativos: o HTTP Request, que chama a API Pix da xFlow para criar a cobrança, e o Webhook, que recebe o aviso quando o Pix é pago. A xFlow não tem um nó próprio no n8n. A API é REST, com JSON, autenticação HTTP Basic e valores em centavos, e o HTTP Request conversa com qualquer API assim.

O que você precisa

• Uma chave de API, gerada no painel em Desenvolvedores > Chaves de API. Comece pela chave de teste (pk_test_ e sk_test_): ela pode ser criada antes da aprovação do cadastro.
• Um n8n com endereço público em https://, no n8n Cloud ou numa instalação própria. A xFlow só entrega webhooks para URL https:// pública.
• O segredo de assinatura do endpoint de webhook, gerado quando você cadastra a URL na xFlow.

Passo 1: criar a cobrança com o HTTP Request

Configure o nó HTTP Request:

O corpo usa os dados do nó anterior, que pode ser um formulário, uma planilha ou o seu CRM:

{
  "amountCents": {{ $json.valor_centavos }},
  "customer": {
    "name": "{{ $json.nome }}",
    "email": "{{ $json.email }}",
    "document": "{{ $json.cpf }}"
  },
  "external_reference": "{{ $json.pedido_id }}"
}

Três regras evitam erro 400 validation: o valor vai em centavos e como número (R$ 19,90 é 1990), o documento vai só com dígitos e name, email e document são obrigatórios.

Atalho: o botão Import cURL aceita o exemplo da documentação. Segundo o n8n, os valores importados viram texto, então troque para Using JSON para manter amountCents como número.

A resposta 201 traz o id, o status pending, o pix.copyPaste (copia e cola) e o pix.qrCodeBase64 (imagem PNG em data-URL). Mapeie {{ $json.pix.copyPaste }} no nó que avisa o cliente. O header Idempotency-Key garante que uma nova tentativa devolva a mesma cobrança em vez de gerar outro Pix. Entenda em idempotência em API de pagamento.

Passo 2: receber o webhook

No nó Webhook, escolha o método POST, defina Respond como Using 'Respond to Webhook' Node e ative a opção Raw Body. Ela entrega o corpo exatamente como chegou, que é o que a assinatura exige.

O nó tem duas URLs. A Test URL escuta enquanto você testa no editor. A Production URL vale com o workflow publicado. Cadastre a Production URL na xFlow, em Integrações > Webhooks, com o evento transaction.paid.

Passo 3: validar a assinatura

Cada entrega traz o header x-webhook-signature: sha256=<hex>, que é o HMAC-SHA256 do corpo cru calculado com o segredo do endpoint. A validação usa quatro nós depois do Webhook.

Nó Code "Ler corpo cru", que lê o corpo e o header:

const item = $input.first();
const campo = Object.keys(item.binary ?? {})[0];
if (!campo) throw new Error('Ative a opção Raw Body no nó Webhook');
const buffer = await this.helpers.getBinaryDataBuffer(0, campo);
return [{ json: {
  corpo: buffer.toString('utf8'),
  assinatura: item.json.headers['x-webhook-signature'] ?? '',
} }];

Nó Crypto, com a ação Hmac, Type SHA256, Value {{ $json.corpo }}, Property Name hmac e Encoding HEX. O segredo fica no campo Hmac Secret da credencial do Crypto, e não no código.

Nó Code "Conferir", que compara em tempo constante:

const crypto = require('crypto');
const { corpo, assinatura } = $('Ler corpo cru').first().json;
const a = Buffer.from('sha256=' + $input.first().json.hmac);
const b = Buffer.from(assinatura);
const valida = a.length === b.length && crypto.timingSafeEqual(a, b);
return [{ json: { valida, ...(valida ? JSON.parse(corpo) : {}) } }];

Nó If, com a condição {{ $json.valida }} is true. No ramo falso, um Respond to Webhook com Response Code 401. No ramo verdadeiro, um Respond to Webhook com 200, seguido do seu processamento.

O require('crypto') funciona no n8n Cloud. Numa instalação própria, libere o módulo com NODE_FUNCTION_ALLOW_BUILTIN=crypto, como mostra o guia de módulos do nó Code.

Passo 4: dar baixa no pedido

Depois da validação, o item traz event e data. Antes de liberar qualquer coisa, confira:

• event é transaction.paid;
• data.livemode é true (eventos do sandbox chegam com false);
• o pedido de data.external_reference ainda não foi baixado.

A xFlow reenvia cada evento até 3 vezes se não receber 2xx, então o mesmo aviso pode chegar mais de uma vez. Por isso a terceira checagem importa. O formato completo do evento está no guia de webhook Pix.

Fluxo de exemplo

1. Gatilho do pedido (formulário, planilha ou CRM).
2. HTTP Request cria a cobrança na API.
3. Um nó de mensagem envia o copia e cola ao cliente.
4. Webhook recebe o transaction.paid.
5. Code, Crypto, Code e If validam a assinatura.
6. Respond to Webhook responde 200 e o fluxo dá baixa no pedido.

Teste no sandbox antes de ir ao ar

Com a credencial de teste, crie a cobrança e adicione um segundo HTTP Request para POST /api/v1/test/charges/{id}/pay, usando o id da resposta. O webhook transaction.paid chega com livemode: false e payer: null. O passo a passo está em API Pix sandbox.

Cuidados

• Segredo nas credenciais. A chave e o segredo da API ficam na credencial Basic Auth do n8n, nunca em campos de texto do fluxo.
• Allowlist de IP. Se você restringiu as chaves por IP, inclua os IPs de saída do seu n8n. Fora da lista, a API responde 401.
• Limite de requisições. Ao receber 429 rate_limited, espere os segundos do header retry-after.
• Plano B. Se o n8n ficar fora do ar além dos reenvios, recupere os pagamentos com GET /api/v1/charges?status=paid&from=...&to=....

Prefere outra ferramenta? Veja como fazer o mesmo no Zapier e no Make. Para código pronto em Node.js, PHP e Python, abra os exemplos da API Pix, e para o mapa completo da documentação, a página Desenvolvedores.