Boas práticas gerais

Use estas recomendações para reduzir pagamentos duplicados, manter rastreabilidade e tratar corretamente atualizações assíncronas do Pague Contas.

Evite pagamentos duplicados

Implemente o controle de idempotência na sua aplicação antes de enviar uma solicitação de pagamento.

Para cada operação:

• mantenha um identificador único no seu sistema;
• envie esse identificador em externalReference quando precisar correlacionar as operações;
• armazene o bill.id associado ao pagamento;
• antes de criar uma nova tentativa, verifique se a operação já foi registrada.

Em caso de timeout ou falha de comunicação, não reenvie a mesma conta imediatamente. Primeiro, verifique se o pagamento já foi criado por meio dos eventos recebidos. Utilize consultas à API apenas quando precisar reconciliar ou recuperar o estado da operação.

Mantenha o payload rastreável

Envie somente os campos necessários para o cenário executado e registre o payload final enviado à API.

Um pagamento sem campos opcionais pode ser criado apenas com identificationField:

{
  "identificationField": "83660000001084301380074119002551100010601813"
}

Inclua campos opcionais somente quando forem necessários para o pagamento.

Consulte o endpoint Criar um pagamento de conta.

Para facilitar auditorias e investigações, mantenha a associação entre:

• sua referência interna;
• externalReference, quando utilizado;
• bill.id;
• payload enviado;
• estado atual da operação.

Acompanhe o processamento por Webhooks

Utilize os Webhooks do Pague Contas como mecanismo principal para acompanhar mudanças no processamento.

Cada evento possui um id próprio. Como os Webhooks utilizam o modelo at least once, o mesmo evento pode ser entregue mais de uma vez. Persista esse id e impeça que uma nova entrega execute novamente a mesma regra de negócio.

Use bill.id para localizar o pagamento correspondente no seu sistema.

Ao receber BILL_FAILED, consulte bill.failReasons antes de decidir se uma nova tentativa deve ser realizada.

Consulte os eventos para Pague Contas.

Consulte como implementar idempotência em Webhooks.

Não faça retentativas sem identificar a causa

Uma nova tentativa deve considerar o resultado da operação anterior.

Antes de reenviar:

• confirme se o pagamento já foi criado;
• identifique a causa quando receber BILL_FAILED;
• corrija erros de dados, saldo ou condições do pagamento antes de tentar novamente;
• evite criar outra operação apenas porque sua aplicação não recebeu uma resposta conclusiva.

Para interpretar erros retornados durante a criação ou processamento, consulte Erros e exceções comuns — Pague Contas.

Não fixe um único horário de processamento

Horários e condições de processamento variam conforme o tipo e o valor do boleto e podem ser alterados.

Evite implementar um único horário-limite como regra global da integração. Mantenha essas validações atualizáveis e consulte as regras vigentes antes de definir o comportamento da aplicação.

Consulte Pagamento imediato x Pagamento agendado.

Homologue no Sandbox

Utilize o Sandbox para validar payloads, tratamento de erros e Webhooks.

Não utilize boletos reais de terceiros em Produção para testar comportamento da integração ou estratégias de retentativa.

O Sandbox possui comportamento próprio e não realiza compensação bancária real.

Consulte como testar o Pague Contas no Sandbox.

Próximos passos

• Entenda o pagamento imediato e o pagamento agendado
• Acompanhe o Pague Contas por Webhooks
• Implemente idempotência no recebimento de Webhooks
• Consulte os erros e exceções comuns
• Teste a integração no Sandbox
• Consulte a referência para criar um pagamento de conta