Orquestração de pagamentos x gateway: qual a diferença

A diferença entre orquestração de pagamentos e gateway está em quantos caminhos existem e em quem escolhe entre eles. Um gateway liga o seu sistema a um processador de pagamento e transmite cada transação. A orquestração fica um nível acima: conversa com vários processadores, decide qual usar em cada cobrança, troca de caminho quando um falha e devolve tudo num formato só.

Na xFlow Payments, os dois papéis estão juntos. A API Pix é o ponto por onde você cobra, e a orquestração de pagamentos decide, por trás dela, entre 11 adquirentes.

O que é um gateway de pagamento

Um gateway é a ponte técnica entre quem vende e quem processa o pagamento. O seu sistema manda os dados da cobrança ao gateway, o gateway repassa ao processador e devolve a resposta: cobrança criada, paga, recusada ou expirada.

No Pix, o gateway entrega o QR Code e o copia e cola, avisa quando o pagamento entra e, em geral, oferece estorno e saque. O que define um gateway simples é o caminho único: cada cobrança vai sempre para o mesmo provedor.

O que é orquestração de pagamentos

Orquestração é a camada que gerencia vários processadores ao mesmo tempo. Ela faz três coisas que um gateway de caminho único não faz:

1. Roteia. Escolhe o processador de cada cobrança conforme regras, como valor, horário e dia da semana.
2. Contorna falhas. Se o processador escolhido não responde, passa a cobrança para o próximo de uma cadeia.
3. Padroniza. Entrega respostas, webhooks e dados de conciliação no mesmo formato, qualquer que seja o processador.

Diferenças lado a lado

Onde entram as adquirentes

As adquirentes (no Pix, os provedores que geram a cobrança e liquidam o pagamento) são quem processa de fato. O gateway e o orquestrador são camadas de tecnologia entre você e elas. Quanto mais adquirentes uma operação usa, mais importante fica ter uma camada que decida entre elas sem que o seu sistema precise conhecer cada uma. Essa é a ideia de multiadquirência online.

Quando um gateway basta

Um gateway de caminho único costuma ser suficiente quando:

• o volume é baixo e algumas horas de indisponibilidade não comprometem o negócio;
• você não precisa separar cobranças por faixa de valor ou horário;
• a operação aceita depender de um provedor só.

Quando você precisa de orquestração

Os sinais mais comuns são estes:

• Uma queda de provedor já parou as suas vendas. Ou você não pode correr esse risco.
• O volume é alto. Cada minuto sem gerar cobrança tem custo direto.
• Você já integra mais de um provedor por conta própria. E mantém a lógica de troca no seu código.
• Condições diferentes por faixa de valor ou horário. E você quer usar a adquirente certa para cada caso.
• A conciliação ficou complexa. Porque cada provedor devolve dados de um jeito.

Se dois ou mais desses sinais aparecem na sua operação, a orquestração tende a se pagar em menos trabalho de manutenção e menos tempo parado.

A mesma queda, dois cenários

Imagine uma loja online que recebe por Pix, numa sexta-feira à noite, quando o provedor principal fica sem responder.

Com um gateway de caminho único, cada cliente que chega ao checkout espera o QR Code e recebe um erro. O time técnico é acionado, mas não tem para onde mandar as cobranças: a única saída é esperar o provedor voltar. As vendas desse período ficam pelo caminho.

Com orquestração, a primeira tentativa falha, a camada tenta de novo e, sem resposta, gera a cobrança no próximo provedor da cadeia. O cliente recebe o QR Code e paga. O time técnico vê o problema nos logs e na página de status, mas o checkout continua funcionando.

A diferença não está no dia em que tudo funciona. Está no dia em que um provedor falha.

Gateway e orquestração juntos: o modelo da xFlow

Na xFlow, você não precisa escolher entre um e outro. A integração é uma API REST única, com JSON e valores em centavos. Por trás dela:

• o roteamento por regras escolhe a adquirente de cada cobrança, por valor, horário e dia da semana;
• a retentativa automática tenta de novo e, se precisar, gera a cobrança Pix na próxima adquirente da cadeia;
• cada pagamento é conferido na adquirente antes de cair no saldo;
• o split de pagamento divide a venda entre contas da xFlow, por porcentagem ou valor fixo;
• os webhooks chegam assinados com HMAC-SHA256, no mesmo formato para todas as adquirentes.

Para o seu código, a xFlow se comporta como um gateway: você chama POST /api/v1/charges e recebe o QR Code. Para a sua operação, ela se comporta como um orquestrador: a cobrança segue a regra e tem contingência.

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","email":"cliente@exemplo.com","document":"00000000000"}}'

Perguntas para fazer antes de escolher

1. Quantos provedores existem por trás da API?
2. O que acontece com a cobrança quando o provedor escolhido não responde?
3. As regras de escolha do provedor podem mudar sem mexer no meu código?
4. O formato das respostas e dos webhooks é o mesmo para todos os provedores?
5. Existe proteção contra cobrança duplicada num retry, como um Idempotency-Key?
6. Existe ambiente de teste com os mesmos endpoints de produção?
7. O pagamento é conferido no provedor antes de virar saldo?

Na xFlow, as respostas estão na documentação: 11 adquirentes, retentativa para a próxima da cadeia, regras do lado da xFlow, formato único, Idempotency-Key em cobranças e saques, sandbox com chaves pk_test_ e conferência do pagamento na adquirente.

Um último ponto: hoje a API da xFlow trabalha com Pix. Cartão e checkout hospedado ainda não estão na API. Se a sua operação é Pix e não pode depender de um provedor só, o artigo sobre failover de pagamentos mostra como preparar a integração para quedas de adquirente.