Orquestração de Pix com vários PSPs

Orquestrar Pix com vários PSPs é colocar uma camada entre o seu sistema e os provedores Pix que decide em qual deles cada cobrança é gerada, troca de provedor quando um não responde e devolve tudo no mesmo formato. Assim, você ganha redundância sem manter uma integração por provedor. Na xFlow Payments, essa camada é a orquestração de pagamentos, ligada a 11 adquirentes por uma única API.

PSP, adquirente e Pix: os termos

O Pix é o arranjo de pagamentos instantâneos do Banco Central do Brasil. Para receber por Pix, alguém precisa gerar a cobrança (o QR Code e o copia e cola) e liquidar o pagamento. Esse alguém é um PSP, o prestador de serviço de pagamento.

Na documentação da xFlow, os PSPs aparecem como provedores ou adquirentes. Aqui, os três termos se referem à mesma coisa: a instituição que gera a cobrança e confirma o pagamento.

Por que usar mais de um PSP no Pix

• Indisponibilidade. Todo provedor tem instabilidades. Com um só, a sua operação para junto.
• Concentração. Depender de um provedor deixa a operação exposta a qualquer mudança de regra, limite ou condição dele.
• Faixas de valor e horários. Provedores diferentes podem fazer mais sentido para tíquetes ou períodos diferentes.
• Recursos que variam. Nem todo provedor oferece os mesmos recursos, como estorno pela API ou saque por QR Code.

O que precisa ser orquestrado

O Pix não é só gerar a cobrança. Cada etapa do ciclo muda quando há mais de um provedor:

Os desafios de orquestrar Pix por conta própria

Cobrança duplicada no retry

Quando o seu sistema não recebe resposta, a tendência é tentar de novo. Se o primeiro pedido chegou ao provedor, você gera duas cobranças para o mesmo pedido. Na xFlow, o cabeçalho Idempotency-Key resolve isso: com a mesma chave e o mesmo corpo, a API devolve a mesma cobrança em vez de gerar outro Pix.

Estorno amarrado ao provedor de origem

O estorno de um Pix acontece no provedor que gerou a cobrança. Se você orquestra por conta própria, precisa guardar qual PSP gerou cada cobrança. Na xFlow, isso fica registrado do lado da xFlow: você chama POST /api/v1/charges/{id}/refund e o pedido vai para a adquirente certa. Se ela não oferece estorno pela API, a resposta é 422 refund_not_supported.

Saque por QR Code

Nem todo provedor aceita saque para um QR Code. Na xFlow, quando a adquirente não aceita, a API responde 422 transfer_failed e nada é debitado do saldo. O saque por chave Pix (CPF, CNPJ, e-mail, telefone ou chave aleatória) segue o mesmo endpoint. Veja o passo a passo em API de saque Pix.

Webhooks em formatos diferentes

Cada provedor avisa o pagamento do próprio jeito: campos, nomes de status e forma de assinatura variam. Quem orquestra por conta própria precisa de um receptor e de uma validação para cada um. Na xFlow, o seu sistema recebe um único formato de webhook, com x-webhook-event e x-webhook-signature (HMAC-SHA256 do corpo cru), e os eventos transaction.*, withdrawal.* e dispute.*. Se o seu endpoint não confirmar com 2xx, a xFlow reenvia até 3 vezes. O guia de webhook Pix mostra a validação.

Confirmação que não depende só do aviso

Num cenário com vários provedores, cada aviso de pagamento chega de uma origem diferente. Antes de lançar um valor no saldo, a xFlow confere o pagamento na própria adquirente. Só depois disso a cobrança vira paid e o webhook é enviado.

Conciliação

O identificador que amarra um Pix do começo ao fim é o End-to-end ID, o identificador único da liquidação. Na xFlow, ele vem em pix.endToEnd, junto com payer (nome, documento e banco de quem pagou, informados pelo provedor na confirmação). O guia de conciliação de pagamentos mostra como usar esses campos.

Como a xFlow orquestra o Pix entre 11 adquirentes

1. Seu sistema chama POST /api/v1/charges.
2. A regra de roteamento da sua conta escolhe a adquirente, por valor, horário e dia da semana.
3. Se ela não responde, a xFlow tenta de novo e, se precisar, gera a cobrança na próxima da cadeia.
4. A API devolve o QR Code e o copia e cola, no mesmo formato para qualquer adquirente.
5. Quando o pagamento entra, a xFlow confere na adquirente, lança o líquido no saldo e envia transaction.paid.
6. Estorno, saque e consultas usam os mesmos endpoints, e a xFlow fala com a adquirente certa por trás.

Exemplo: uma cobrança paga, no mesmo formato para todas as adquirentes

curl https://app.xflowpayments.com/api/v1/charges/{id} \
  -u "pk_live_...:sk_live_..."

{
  "id": "clx...",
  "livemode": true,
  "status": "paid",
  "amountCents": 1990,
  "external_reference": "pedido-1234",
  "payer": { "name": "Fulano de Tal", "document": "10900327570", "bank": "BANCO EXEMPLO" },
  "pix": { "endToEnd": "E18236120202609130426s1894658118" },
  "paidAt": "2026-09-13T04:26:13.927Z"
}

Você não precisa saber qual adquirente processou a cobrança para conciliar ou estornar.

Checklist para a sua integração

• Envie um Idempotency-Key único por pedido e por saque.
• Use webhooks e valide a assinatura x-webhook-signature.
• Grave o external_reference com o identificador do pedido no seu sistema.
• Concilie pelo pix.endToEnd e pelos dados de payer.
• Trate 502 charge_failed (cobrança não gerada) e 429 rate_limited (espere o retry-after).
• Teste tudo no sandbox com chaves pk_test_ antes de ir para produção.

A documentação tem os endpoints completos, e a página da API Pix resume o que a API oferece.