Roteamento de pagamentos é decidir, antes de gerar a cobrança, qual adquirente vai processar aquele pagamento. Na xFlow Payments, a decisão segue regras que você define com três critérios: valor da cobrança, horário e dia da semana. A regra é aplicada do lado da xFlow a cada cobrança Pix, e o seu sistema continua chamando o mesmo endpoint.
O roteamento é uma das peças da orquestração de pagamentos da xFlow, ao lado da retentativa automática e do split. Juntos, eles deixam a sua operação ligada a 11 adquirentes por uma única API Pix.
Como funciona o roteamento por regras
Cada regra combina uma condição com uma cadeia de adquirentes. Quando uma cobrança chega, a xFlow avalia as condições e manda a cobrança para a primeira adquirente da cadeia que corresponde a ela.
| Critério | O que ele olha | Exemplo de uso |
|---|---|---|
| Valor | O valor da cobrança | Cobranças acima de um valor vão para uma adquirente; as menores, para outra |
| Horário | A hora em que a cobrança é criada, no horário de Brasília | Uma adquirente durante o dia, outra de madrugada |
| Dia da semana | O dia em que a cobrança é criada | Uma cadeia para dias úteis, outra para sábado e domingo |
Os critérios podem ser combinados. Uma faixa de horário também pode atravessar a meia-noite, como das 22h às 6h.
Exemplos de regras
Os nomes abaixo são genéricos. A xFlow trabalha com 11 adquirentes homologadas, e a escolha de quais entram em cada cadeia fica na configuração da sua conta.
- Por faixa de valor: cobranças até R$ 500,00 vão para a Adquirente A; acima disso, para a Adquirente B.
- Por horário: das 8h às 20h, Adquirente A; fora desse horário, Adquirente C.
- Por dia da semana: de segunda a sexta, Adquirente B; sábado e domingo, Adquirente A.
- Combinando critérios: nos dias úteis, cobranças acima de R$ 1.000,00 vão para a Adquirente B; o resto segue para a Adquirente A.
Em todos os casos, a regra tem uma ordem de contingência. Se a primeira adquirente não responder, a cobrança vai para a próxima.
A cadeia de contingência
O roteamento escolhe a primeira opção. A cadeia define o que acontece se ela falhar. Quando a adquirente escolhida 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 adquirente da cadeia. Isso é a retentativa automática. Com ela, uma regra de roteamento não precisa depender de uma adquirente só.
O que muda na sua integração
Nada. Você cria a cobrança com o mesmo POST /api/v1/charges e recebe a mesma resposta, com pix.copyPaste e pix.qrCodeBase64, seja qual for a adquirente. Os webhooks também chegam no mesmo formato. Quando a regra muda, o seu código continua igual.
curl -X POST https://app.xflowpayments.com/api/v1/charges \
-u "pk_live_...:sk_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pedido-5678" \
-d '{
"amountCents": 75000,
"customer": { "name": "Cliente", "email": "cliente@exemplo.com", "document": "00000000000" },
"external_reference": "pedido-5678"
}'Nesse exemplo, a cobrança de R$ 750,00 (75000 centavos) segue a regra de valor configurada na sua conta. Com o Idempotency-Key, um retry do seu lado devolve a mesma cobrança, sem gerar outro Pix. Os endpoints estão na documentação da API.
Quem define as regras
Você decide os critérios e a ordem das adquirentes, e as regras ficam na configuração da sua conta na xFlow. A montagem é feita com a equipe da xFlow, que você aciona pelos canais da página de contato. Mudar uma regra não exige deploy no seu sistema.
Por que rotear pagamentos
- Não depender de um provedor. Com mais de uma adquirente na cadeia, a queda de uma não para a geração de cobranças.
- Usar a adquirente certa para cada faixa de valor. As condições de cada adquirente variam, e a regra de valor separa o tíquete baixo do alto.
- Ajustar por horário e dia. Se faz sentido usar uma adquirente em certos horários ou dias, a regra leva as cobranças para ela nesse período.
- Trocar sem reescrever código. A regra fica na xFlow, não no seu sistema.
Roteamento e conciliação
Rotear entre várias adquirentes não complica a conciliação. 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 pagou em payer. Veja como conciliar em conciliação de pagamentos com várias adquirentes.
Se você quer entender o tema do ponto de vista técnico, o artigo sobre orquestração de Pix com vários PSPs mostra o que muda quando o Pix passa por mais de um provedor.
Perguntas frequentes
O que é roteamento de pagamentos?
É a regra que decide qual adquirente vai processar cada cobrança. Em vez de mandar tudo para o mesmo provedor, a regra olha o valor, o horário e o dia da semana e escolhe a adquirente certa para aquele pagamento.
Quais critérios o roteamento da xFlow usa?
Valor da cobrança, horário e dia da semana, no horário de Brasília. Os critérios podem ser combinados, e cada regra aponta para uma cadeia de adquirentes em ordem.
Preciso mudar o meu código para usar o roteamento?
Não. Você chama o mesmo endpoint de criação de cobrança e recebe a mesma resposta. A regra é aplicada do lado da xFlow, então mudar a regra não exige mudar o seu sistema.
O que acontece se a adquirente escolhida pela regra estiver fora do ar?
A xFlow tenta de novo e, se precisar, gera a cobrança Pix na próxima adquirente da cadeia daquela regra. Isso é a retentativa automática.
Quantas adquirentes posso usar no roteamento?
A xFlow tem 11 adquirentes integradas. A cadeia de cada regra é montada na configuração da sua conta, com a equipe da xFlow.