Failover de pagamentos: como sobreviver à queda de uma adquirente

Failover de pagamentos é trocar de provedor automaticamente quando o principal deixa de responder, para que as cobranças continuem sendo geradas. No Pix, uma queda de adquirente sem failover significa checkout parado: o cliente quer pagar e não recebe o QR Code. Com failover, a cobrança é gerada em outra adquirente e o pagador nem percebe a troca.

Na xFlow Payments, o failover é a retentativa automática: se a adquirente escolhida não responde, a xFlow tenta de novo e, se precisar, gera a cobrança na próxima adquirente da cadeia. A seguir, o que acontece numa queda, como desenhar o failover e o que o seu sistema precisa fazer.

O que acontece numa queda de adquirente

Uma adquirente fora do ar raramente avisa. Os sinais mais comuns são:

• pedidos de cobrança que demoram e terminam em timeout;
• erros na geração da cobrança;
• cobranças que não chegam ao pagador.

Para quem vende, o efeito é imediato: cada tentativa de compra sem QR Code é uma venda que pode não voltar. Quanto maior o volume, maior o custo de cada minuto parado.

Failover, retentativa e contingência

Os termos aparecem juntos e se completam:

Como desenhar failover de pagamentos

1. Tenha uma cadeia ordenada

Failover precisa de um plano B definido antes da falha. Cada regra deve dizer qual provedor vem primeiro, qual vem depois e assim por diante. Na xFlow, essa ordem faz parte do roteamento de pagamentos: cada regra, por valor, horário ou dia da semana, aponta para uma cadeia.

2. Defina quando desistir de um provedor

Esperar indefinidamente por uma resposta é o mesmo que estar parado. O failover precisa de um limite de espera por tentativa e de um número de novas tentativas antes de passar para o próximo. Na xFlow, isso é feito do lado da xFlow, por adquirente da cadeia.

3. Proteja contra duplicidade

Toda troca e todo retry carregam o risco de gerar duas cobranças para o mesmo pedido. A defesa é a idempotência: um identificador único por pedido, que faz o provedor devolver a mesma cobrança em vez de criar outra. Na API da xFlow, esse identificador é o cabeçalho Idempotency-Key.

4. Cuidado redobrado no dinheiro que sai

Na entrada, uma cobrança a mais fica pendente e expira sem pagamento. Na saída, um envio a mais é dinheiro que sai duas vezes. Por isso, no saque, a regra é nunca repetir sem idempotência: envie o Idempotency-Key em todo POST /api/v1/transfers e espere o webhook withdrawal.completed ou withdrawal.failed antes de concluir que algo deu errado.

5. Observe o que está acontecendo

Failover sem visibilidade esconde problemas. Acompanhe os códigos de erro, o tempo de resposta e a situação dos serviços.

Como a xFlow faz failover no Pix

1. Seu sistema chama POST /api/v1/charges com um Idempotency-Key.
2. A regra de roteamento da sua conta escolhe a primeira adquirente.
3. Se ela não responde, a xFlow tenta de novo.
4. Se continuar sem resposta, a xFlow gera a cobrança na próxima adquirente da cadeia.
5. A API devolve a cobrança com pix.copyPaste e pix.qrCodeBase64, no mesmo formato de sempre.
6. Se nenhuma adquirente da cadeia gerar a cobrança, a API responde 502 charge_failed.

O pagador recebe um único QR Code, o da cobrança que a API devolveu. O seu sistema não precisa saber qual adquirente gerou a cobrança.

O que o seu sistema deve fazer

Exemplo de retry seguro em Node.js

async function criarCobranca(pedido, tentativas = 3) {
  const cred = Buffer.from(process.env.XFLOW_PUBLIC_KEY + ":" + process.env.XFLOW_SECRET_KEY).toString("base64");
  for (let i = 0; i < tentativas; i++) {
    try {
      const res = await fetch("https://app.xflowpayments.com/api/v1/charges", {
        method: "POST",
        headers: {
          Authorization: "Basic " + cred,
          "Content-Type": "application/json",
          "Idempotency-Key": "pedido-" + pedido.id, // a mesma chave em todas as tentativas
        },
        body: JSON.stringify({
          amountCents: pedido.valorCentavos,
          customer: pedido.cliente,
          external_reference: "pedido-" + pedido.id,
        }),
      });
      if (res.status === 429) {
        const espera = Number(res.headers.get("retry-after") || 1);
        await new Promise((r) => setTimeout(r, espera * 1000));
        continue;
      }
      if (res.status === 502) {
        await new Promise((r) => setTimeout(r, 2000 * (i + 1)));
        continue;
      }
      return await res.json();
    } catch (erro) {
      // a conexão falhou do seu lado: repete com a mesma Idempotency-Key
      await new Promise((r) => setTimeout(r, 2000 * (i + 1)));
    }
  }
  throw new Error("Não foi possível gerar a cobrança agora.");
}

Como a chave é a mesma em todas as tentativas, a API devolve a mesma cobrança se uma delas já tiver sido criada. Os detalhes estão na documentação.

Como acompanhar a operação

• Página de status. A página de status mostra a situação da API, dos webhooks e do painel.
• Logs da API. Em Integrações > Logs da API, cada requisição aparece com status, duração e código de erro, por 30 dias.
• request_id. Toda resposta traz um request_id. Guarde-o nos seus logs para cruzar com os da xFlow e com o suporte.

Failover é uma das peças da orquestração de pagamentos. Se você ainda compara opções, veja a diferença entre orquestração e gateway.