Retentativa automática

Retentativa de pagamento, na xFlow Payments, é o que acontece quando a adquirente escolhida não responde ao pedido de uma cobrança Pix: a xFlow tenta de novo e, se precisar, gera a cobrança na próxima adquirente da cadeia. Para o seu sistema, nada muda. Você faz a mesma chamada e recebe uma cobrança pronta, com QR Code e copia e cola. É o que o mercado também chama de fallback de adquirente.

A retentativa trabalha junto com o roteamento de pagamentos: o roteamento escolhe a primeira adquirente, e a retentativa define o que fazer se ela falhar. As duas fazem parte da orquestração de pagamentos da xFlow, que conecta a sua operação a 11 adquirentes por uma API só.

Retentativa de pagamento: dois usos da mesma expressão

A expressão aparece em dois contextos diferentes, e vale separar:

A retentativa da xFlow não cobra o pagador de novo. Ela atua num ponto anterior: fazer a cobrança ser gerada mesmo quando uma adquirente não responde.

Como funciona o fallback de adquirente na xFlow

1. Seu sistema chama POST /api/v1/charges.
2. A regra de roteamento da sua conta escolhe a primeira adquirente da cadeia.
3. A xFlow pede a cobrança Pix a essa adquirente.
4. Se ela não responde, a xFlow tenta de novo.
5. Se continuar sem resposta, a xFlow passa para a próxima adquirente da cadeia e pede a cobrança a ela.
6. Quando uma adquirente gera a cobrança, a API devolve 201 com pix.copyPaste e pix.qrCodeBase64.
7. Se nenhuma adquirente da cadeia gerar a cobrança, a API responde 502 charge_failed.

O pagador vê um único QR Code: o da cobrança que a API devolveu. Ele não percebe que houve troca de adquirente.

Quando a retentativa entra em ação

A retentativa é acionada quando a adquirente não entrega a cobrança. Na prática, isso acontece em três situações:

• A adquirente está fora do ar. O pedido não recebe resposta.
• A adquirente está lenta demais. A resposta não chega dentro do tempo de espera definido para aquela adquirente na cadeia.
• A adquirente devolve erro. A cobrança não é gerada.

Nos três casos, o tratamento é o mesmo: nova tentativa e, se precisar, a próxima adquirente da cadeia. A ordem da cadeia vem da regra de roteamento da sua conta.

Retentativa e idempotência

A retentativa da xFlow cuida da falha entre a xFlow e a adquirente. Do seu lado, também pode haver falha: uma conexão que cai entre o seu servidor e a API, por exemplo. Para esse caso, use o Idempotency-Key, explicado em detalhe no guia de idempotência em API de pagamento.

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"}}'

Se o seu sistema repetir a chamada com a mesma chave 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. Use uma chave única por pedido, como o número do pedido no seu sistema.

O que a retentativa cobre e o que não cobre

Como acompanhar a operação

• Logs da API. Em Integrações > Logs da API, cada requisição autenticada aparece com status, duração e código de erro, por 30 dias. Toda resposta traz um request_id para localizar a chamada.
• Webhooks. O evento transaction.pending avisa que a cobrança foi criada, e o transaction.paid avisa que ela foi paga e conferida na adquirente. Veja o guia de webhook Pix.
• Página de status. A página de status mostra a situação da API, dos webhooks e do painel.

Retentativa em operações de alto volume

Quanto maior o volume, maior o custo de uma adquirente fora do ar. Sem fallback, cada minuto de indisponibilidade é um minuto sem gerar cobranças. Com a cadeia de contingência, a próxima adquirente assume e a venda continua. O artigo sobre failover de pagamentos mostra como desenhar a sua integração para conviver com quedas de adquirente.