Orquestração de pagamentos

Orquestração de pagamentos é ter uma camada entre o seu sistema e as adquirentes que escolhe, a cada cobrança, quem vai processar o pagamento e que muda de caminho quando uma delas não responde. Você integra uma vez, com uma API só, e a orquestração cuida do resto: para qual adquirente mandar, o que fazer se ela falhar, como confirmar o pagamento e onde o dinheiro cai.

Na xFlow Payments, essa camada é a própria API Pix. Ela conecta a sua operação a 11 adquirentes homologadas e aplica três recursos em cada cobrança: roteamento por regras, retentativa automática e split de pagamento. O resultado chega sempre no mesmo formato, qualquer que seja a adquirente que processou.

O que é orquestração de pagamentos

Quem vende online precisa de alguém que gere a cobrança e liquide o pagamento. No Pix, esse papel é de um provedor de pagamento (a xFlow chama esses provedores de adquirentes). O caminho mais simples é integrar uma adquirente só. Funciona até o dia em que ela fica fora do ar, muda uma regra ou deixa de atender uma faixa de valor.

A alternativa é trabalhar com várias adquirentes ao mesmo tempo. O problema é que cada uma tem a própria API, o próprio formato de resposta, os próprios webhooks e o próprio jeito de conciliar. Manter tudo isso dentro do seu sistema dá trabalho e cria novos pontos de falha.

A orquestração resolve as duas coisas. Você fala com uma API só, e ela distribui as cobranças entre as adquirentes conforme as regras que você definiu.

Por que orquestrar em vez de depender de uma adquirente

Concentrar tudo em um provedor é simples, mas deixa a operação exposta. Os motivos mais comuns para orquestrar são estes:

1. Indisponibilidade. Se a única adquirente não responde, nenhuma cobrança é gerada até ela voltar. Com orquestração, a próxima da cadeia assume.
2. Condições diferentes por faixa de valor ou horário. Cada adquirente tem condições próprias. Rotear permite mandar cada tipo de cobrança para a que faz mais sentido para ela.
3. Custo de integração. Integrar e manter várias adquirentes exige desenvolvimento a cada mudança de API. Com uma camada única, essa manutenção fica do lado da xFlow.
4. Conciliação. Quando cada adquirente devolve dados num formato, conciliar vira trabalho manual. Com uma resposta padronizada, a conciliação é igual para todas.

Como a orquestração funciona na xFlow

Uma API para todas as adquirentes

A integração é uma API REST com base em https://app.xflowpayments.com/api/v1, JSON em UTF-8 e valores em centavos (R$ 19,90 vira 1990). A autenticação é HTTP Basic, com a chave pública (pk_live_) como usuário e o segredo (sk_live_) como senha. Você cria a cobrança, consulta o status, estorna, saca e recebe webhooks pelos mesmos endpoints, não importa qual adquirente processou. Os detalhes estão na página da API Pix e na documentação.

Roteamento por regras

Você define qual adquirente recebe cada cobrança, com três critérios: valor, horário e dia da semana. Uma regra pode mandar cobranças de valor alto para uma adquirente e as de valor baixo para outra, ou trocar de adquirente à noite e no fim de semana. A regra é aplicada do lado da xFlow, então o seu código não muda quando a regra muda. Veja exemplos em roteamento de pagamentos.

Retentativa automática e cadeia de contingência

Cada regra aponta para uma cadeia de adquirentes, em ordem. Se a primeira não responde ao pedido de geração da cobrança Pix, a xFlow tenta de novo e, se precisar, gera a cobrança na próxima da cadeia. Para o seu sistema, a resposta é uma cobrança Pix pronta, com QR Code e copia e cola. A página de retentativa automática explica o que esse fallback cobre e o que ele não cobre.

Confirmação conferida na adquirente

Quando a adquirente avisa que um Pix foi pago, a xFlow confere o pagamento na própria adquirente antes de lançar o valor no saldo. Só depois disso a cobrança passa a paid, o valor líquido entra no seu saldo e o webhook transaction.paid é enviado ao seu sistema.

Split de pagamento

Ao criar a cobrança, você pode dividir o valor com outras contas da xFlow, por porcentagem do valor líquido ou por valor fixo em centavos. Também dá para deixar o split como regra padrão da conta. Quando o pagamento confirma, cada recebedor é creditado no próprio saldo. Os detalhes estão em split de pagamento.

Saque Pix

O saldo disponível sai por Pix, pela API ou pelo painel, para uma chave Pix (CPF, CNPJ, e-mail, telefone ou chave aleatória) ou para um QR Code. O envio do Idempotency-Key evita saque duplicado quando o seu sistema repete o pedido. O passo a passo está em API de saque Pix.

Painel e logs

No painel você acompanha vendas, recebimentos, saques e indicadores em um só lugar. Em Integrações ficam os webhooks e os Logs da API, onde cada requisição autenticada aparece com status, duração e código de erro por 30 dias. Toda resposta da API traz um request_id, que localiza a chamada nos logs e no suporte.

O caminho de uma cobrança, do pedido ao saldo

1. Seu sistema chama POST /api/v1/charges com o valor, os dados do cliente e, se quiser, o external_reference (o número do pedido no seu sistema) e um Idempotency-Key.
2. A xFlow aplica a regra de roteamento da sua conta e escolhe a adquirente.
3. Se a adquirente não responde, a xFlow tenta de novo ou passa para a próxima da cadeia.
4. A API devolve 201 com a cobrança pending, o pix.copyPaste e o pix.qrCodeBase64.
5. Você mostra o QR Code ou o copia e cola ao pagador.
6. O pagador paga, e a xFlow confere o pagamento na adquirente.
7. A cobrança vira paid, o líquido entra no saldo (e no saldo de cada recebedor do split, se houver) e o webhook transaction.paid chega ao seu endpoint, assinado com HMAC-SHA256.
8. Você dá baixa no pedido e, quando quiser, saca o saldo por Pix.

Exemplo de integração

A chamada é a mesma para qualquer adquirente. O roteamento e a retentativa acontecem do lado da xFlow.

curl -X POST https://app.xflowpayments.com/api/v1/charges \
  -u "pk_live_...:sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1234" \
  -d '{
    "amountCents": 1990,
    "customer": { "name": "Cliente Exemplo", "email": "cliente@exemplo.com", "document": "00000000000" },
    "description": "Pedido #1234",
    "external_reference": "pedido-1234"
  }'

A resposta traz a cobrança pronta para o pagador:

{
  "id": "clx...",
  "livemode": true,
  "status": "pending",
  "amountCents": 1990,
  "external_reference": "pedido-1234",
  "pix": {
    "copyPaste": "00020101br.gov.bcb.pix...",
    "qrCodeBase64": "data:image/png;base64,iVBORw0..."
  },
  "createdAt": "2026-07-19T21:00:00.000Z"
}

Se o seu sistema repetir a chamada com o mesmo Idempotency-Key e o mesmo corpo, a API devolve a mesma cobrança em vez de gerar outro Pix. Com a mesma chave e um corpo diferente, a resposta é 409 idempotency_conflict.

O que fica com a xFlow e o que fica com o seu sistema

Boas práticas para orquestrar bem

A orquestração faz o trabalho pesado, mas alguns cuidados na sua integração evitam problemas no dia a dia:

• Use webhooks em vez de consultar o status sem parar. O transaction.paid avisa o pagamento assim que ele é confirmado. A consulta por GET /api/v1/charges/{id} fica como plano B.
• Valide a assinatura de todo webhook. O cabeçalho x-webhook-signature traz o HMAC-SHA256 do corpo cru, calculado com o segredo do endpoint. O guia de webhook Pix mostra o código.
• Filtre o livemode. Eventos do ambiente de teste chegam com livemode: false. Não dê baixa em pedido real com eles.
• Respeite o limite de requisições. O limite é por conta. Toda resposta autenticada traz x-ratelimit-limit, x-ratelimit-remaining e x-ratelimit-reset. Se receber 429, espere o tempo do retry-after.
• Guarde o request_id. Com ele, você acha a chamada em Logs da API e o suporte localiza o caso sem pedir prints.

Orquestração, gateway e multiadquirência

Os três termos aparecem juntos, mas não são sinônimos. Um gateway liga a sua loja a um processador de pagamento. Multiadquirência é trabalhar com mais de uma adquirente ao mesmo tempo. Orquestração é a lógica que decide entre elas e reage a falhas. A xFlow junta os três: é a API por onde você cobra, conecta 11 adquirentes e decide entre elas por regra. A comparação completa está em orquestração de pagamentos x gateway, e a diferença entre a multiadquirência online e a de maquininha está em multiadquirência.

Orquestração e conciliação

Quando as cobranças passam por várias adquirentes, a conciliação costuma ser a primeira preocupação. Na xFlow, toda cobrança volta no mesmo formato: o id da xFlow, o seu external_reference, o pix.endToEnd (o identificador do Pix na liquidação) e os dados de quem de fato pagou em payer. A listagem GET /api/v1/charges filtra por status, período e referência do pedido, com paginação por cursor. Veja o passo a passo em conciliação de pagamentos com várias adquirentes.

Para quem a orquestração faz sentido

• Subadquirentes e operações white label, que não podem parar quando um provedor cai. Veja xFlow para subadquirentes.
• Marketplaces, que precisam dividir cada venda entre vendedores e a plataforma. Veja xFlow para marketplaces.
• Fintechs e plataformas financeiras, que movimentam Pix de entrada e de saída por API. Veja xFlow para fintechs.
• Infoprodutores e e-commerce de alto volume, que querem redundância entre adquirentes sem manter várias integrações.

Como começar

1. Crie sua conta na xFlow.
2. No painel, em Desenvolvedores > Chaves de API, crie uma chave de teste (pk_test_ e sk_test_). Ela pode ser criada antes da aprovação do cadastro.
3. Crie cobranças no ambiente de teste e simule o pagamento com POST /api/v1/test/charges/{id}/pay. O webhook transaction.paid chega com livemode: false.
4. Cadastre o seu endpoint de webhook em Integrações > Webhooks e valide a assinatura.
5. Com o cadastro aprovado, troque para a chave de produção e defina com a equipe da xFlow as regras de roteamento da sua conta.

A central do desenvolvedor reúne os guias de integração, e o atendimento é feito por uma pessoa, pelo WhatsApp ou por e-mail, do começo ao fim. Os canais estão na página de contato.

Limites que você precisa conhecer

• Hoje a API trabalha com Pix: cobrança, estorno total e saque. Cartão e checkout hospedado ainda não estão na API.
• No ambiente de teste, split e saques não estão disponíveis (a API responde 400 e 403 test_mode_unsupported).
• O estorno é total, uma vez por cobrança, até 90 dias após o pagamento. Ele é pedido à adquirente que gerou a cobrança e, se ela não oferecer estorno pela API, a resposta é 422 refund_not_supported. Veja o fluxo completo em estorno Pix por API.
• O saque por QR Code funciona só em algumas adquirentes. Nas outras, a API responde 422 transfer_failed e nada é debitado.
• Cada conta tem um valor mínimo e um máximo por cobrança, que você vê em Empresa > Limites e taxas. Fora da faixa, a API responde 400 validation e nada é criado na adquirente.