Como implementar retentativas no fluxo de Pix Out

O fluxo de retentativas no Pix Request é útil em cenários em que uma tentativa de Pix Out falha por um erro elegível retornado pela instituição recebedora. Nesses casos, é possível realizar uma nova tentativa para concluir o pagamento, por exemplo, quando há uma intermitência temporária e o Pix é devolvido. Este artigo explica quando e como realizar retentativas (retries) no fluxo de Pix Out, evitando duplicidade de pagamentos e erros operacionais.

Visão geral

Nem todos os erros permitem retentativa no Pix Out. Uma nova tentativa só deve ser feita após a confirmação explícita de falha da tentativa anterior.

Ou seja: retry não é automático para qualquer erro.

Quando é permitido fazer retentativa?

A retentativa só deve ocorrer quando a tentativa anterior for finalizada como falha, seja por resposta síncrona de erro ou por webhook de falha.

Os únicos erros elegíveis para retry são:

• settlementFailed

• settlementTimeout

• insufficientFunds

• internalSenderError

• internalReceiverError

Em todos esses casos, a tentativa anterior já foi encerrada como failed, então uma nova tentativa é segura.

Quando não fazer retentativa?

Você não deve realizar retry se:

• O erro foi apenas um timeout sem confirmação de falha

• Você não recebeu webhook de falha

• O status da transação ainda pode estar em processamento

Nesses cenários, a transação original pode ainda ser concluída, e um retry pode gerar pagamento duplicado.

Como funciona o retry na prática?

Cada retentativa deve ser tratada como uma nova tentativa de pagamento, o que exige novos identificadores.

Primeira tentativa (Pix Out)

EndToEndId: E10000202025101402500000
ExternalId: transfer/0

Retentativa após falha confirmada

EndToEndId: E20000202025101402511111
ExternalId: transfer/01

E o risco de pagamento duplicado?

Esse risco é evitado seguindo esta regra fundamental:

Só faça retry após confirmação explícita de falha.

Se não houve confirmação de falha (erro ou webhook), não retente.
Isso garante que duas transações válidas não sejam processadas para o mesmo pagamento.

Em caso de dúvidas, nosso time está à disposição.