Pix no Zapier

Para usar Pix no Zapier com a xFlow, você trabalha com o app genérico Webhooks by Zapier: a ação Custom Request cria a cobrança na API Pix da xFlow e o gatilho Catch Raw Hook recebe o aviso de pagamento. A xFlow não tem app próprio no Zapier. Por isso, a ação API Request (Beta), que depende de um app já conectado ao Zapier, não se aplica aqui.

Antes de começar

• Plano do Zapier. Segundo a central de ajuda do Zapier, o Webhooks by Zapier está nos planos Professional, Team e Enterprise.
• Chave de API da xFlow. Gere no painel em Desenvolvedores > Chaves de API. Comece pela chave de teste (pk_test_ e sk_test_), que pode ser criada antes da aprovação do cadastro.
• Segredo do webhook. É gerado quando você cadastra a URL de webhook na xFlow. Guarde, porque você vai usá-lo no passo 3.

Passo 1: criar a cobrança com Custom Request

No Zap, adicione a ação Webhooks by Zapier com o evento Custom Request. A documentação de envio de webhooks explica que, nesse modo, você escreve o JSON direto no campo Data e o Zapier envia o texto sem formatar.

{
  "amountCents": 1990,
  "customer": {
    "name": "Nome do cliente",
    "email": "cliente@exemplo.com",
    "document": "00000000000"
  },
  "external_reference": "pedido-1234"
}

Troque os valores fixos pelos campos dos passos anteriores do Zap. O amountCents vai em centavos e sem aspas (R$ 19,90 é 1990), e o documento vai só com dígitos. Um JSON inválido volta como 400 validation.

Nos headers:

• Content-Type: application/json.
• Authorization: Basic seguido do base64 de chave_publica:segredo. No terminal, printf '%s' 'pk_test_...:sk_test_...' | base64 gera o valor. Trate o resultado como o próprio segredo.
• Idempotency-Key: o id do pedido. Se o Zap repetir a chamada, a API devolve a mesma cobrança em vez de gerar outro Pix. Veja idempotência em API de pagamento.

A ação também tem um campo Basic Auth. Se preferir usá-lo, siga o formato pedido no próprio campo. A resposta 201 traz id, status, pix.copyPaste e pix.qrCodeBase64, que os próximos passos podem mapear, por exemplo para enviar o copia e cola ao cliente.

Passo 2: receber o pagamento com Catch Raw Hook

Crie outro Zap com o gatilho Webhooks by Zapier no evento Catch Raw Hook. Ele entrega o corpo sem interpretação e os headers, com limite de 2 MB. Copie a URL gerada e cadastre na xFlow, em Integrações > Webhooks, com o evento transaction.paid.

Para o Zapier ter uma amostra, simule um pagamento no sandbox (detalhes abaixo) e use o teste do gatilho. Na amostra, localize o campo com o corpo cru e o header com o valor de x-webhook-signature.

Dois comportamentos do Zapier mudam o desenho do fluxo. Com o Zap ligado, ele responde 200 e não deixa personalizar a resposta. Com o Zap desligado, responde 404, e a xFlow reenvia o evento até 3 vezes.

Passo 3: conferir a assinatura com Code by Zapier

A xFlow assina cada entrega com x-webhook-signature: sha256=<hex>, o HMAC-SHA256 do corpo cru com o segredo do endpoint. Adicione um passo Code by Zapier em JavaScript. O ambiente roda Node.js 22 e inclui a biblioteca padrão do Node.js, segundo a documentação de código no Zapier.

Em Input Data, crie três campos: corpo (o corpo cru), assinatura (o header) e segredo (o segredo do webhook). Depois, use este código:

const crypto = require('crypto');
const esperado = Buffer.from('sha256=' + crypto
  .createHmac('sha256', inputData.segredo)
  .update(inputData.corpo, 'utf8')
  .digest('hex'));
const recebido = Buffer.from(inputData.assinatura || '');
const valida = esperado.length === recebido.length
  && crypto.timingSafeEqual(esperado, recebido);
const evento = valida ? JSON.parse(inputData.corpo) : { data: {} };
output = {
  valida,
  evento: evento.event || '',
  livemode: evento.data.livemode === true,
  pedido: evento.data.external_reference || '',
  valor_centavos: evento.data.amount || 0,
};

Passo 4: filtrar e dar baixa

Adicione um Filter que só deixa o Zap seguir quando valida é verdadeiro, evento é transaction.paid e livemode é verdadeiro. Depois dele, entram as suas ações: atualizar o pedido, avisar o cliente, registrar na planilha.

Antes de dar baixa, confira se o pedido de pedido já foi processado. O mesmo evento pode chegar mais de uma vez, e o guia de webhook Pix explica como tratar repetições.

O que muda com a resposta sempre 200

Como o Zapier confirma a entrega na hora, a xFlow não reenvia o evento se um passo posterior falhar. Acompanhe o histórico de execuções do Zap. Para recuperar pagamentos que ficaram para trás, faça um Custom Request GET para https://app.xflowpayments.com/api/v1/charges?status=paid&from=...&to=....

Teste no sandbox

Com a chave de teste no header Authorization, crie a cobrança e chame POST /api/v1/test/charges/{id}/pay num segundo Custom Request, sem corpo. O evento chega com livemode: false e payer: null, então o Filter para o Zap, como deve ser em produção. Para testar as ações seguintes, ajuste a condição de livemode só durante o teste. O guia completo está em API Pix sandbox.

Cuidados

• Quem edita o Zap vê o segredo. O header Authorization e o campo segredo ficam salvos no Zap. Limite o acesso a ele.
• Allowlist de IP. Se você restringiu as chaves por IP, as chamadas do Zapier só passam se saírem de um endereço da lista. Fora dela, a API responde 401.
• Limite de requisições. Ao receber 429 rate_limited, espere os segundos do header retry-after.

O mesmo fluxo existe no n8n e no Make. O mapa completo da documentação está em Desenvolvedores.