Boas práticas gerais

Boas práticas para integrar o Pague Contas, incluindo fluxo recomendado, payload mínimo, regras de agendamento, idempotência e webhooks.

Use estas boas práticas para integrar o Pague Contas com menos duplicidades, menos falhas operacionais e mais previsibilidade no processamento de boletos.

Quando usar o Pague Contas

Use o Pague Contas quando sua aplicação precisar pagar boletos pela API do Asaas a partir da linha digitável do título. Essa funcionalidade é indicada para fluxos em que você quer automatizar contas recorrentes, centralizar pagamentos operacionais ou programar pagamentos sem depender de execução manual.

O campo obrigatório da operação é identificationField (linha digitável do boleto). Com ele, você pode iniciar um pagamento imediato ou programar o pagamento para uma data futura, respeitando as regras de horário limite e dia útil.

Fluxo recomendado de integração

Receba ou capture a linha digitável do boleto. Armazene o valor que será enviado em identificationField e evite transformar o campo sem necessidade.
Monte o payload final. Envie somente os campos necessários para a operação, incluindo scheduleDate apenas quando o pagamento for agendado.
Registre o payload antes do envio. Salve o corpo final da requisição para auditoria, suporte e investigação de falhas.
Aplique idempotência na sua aplicação. Antes de reenviar uma tentativa, verifique se a mesma conta já foi enviada para evitar pagamentos duplicados.
Envie a requisição para pagamento. Para pagamento imediato, não envie scheduleDate; para pagamento agendado, informe uma data válida.
Acompanhe o resultado da operação. Monitore webhooks e configure alertas para identificar falhas, atrasos ou comportamentos inesperados.

Exemplo de payload mínimo

Use este formato quando quiser solicitar um pagamento sem agendamento explícito:

{
  "identificationField": "83660000001084301380074119002551100010601813"
}

O payload final deve conter apenas os campos exigidos para o cenário que você está executando. Se sua aplicação adicionar campos opcionais, registre o corpo final enviado para facilitar a comparação entre o que foi planejado e o que chegou à API.

Regras de pagamento imediato e agendado

Cenário	Como enviar	Comportamento esperado
Pagamento imediato	Envie `identificationField` sem `scheduleDate`.	O pagamento é processado no momento da requisição, respeitando as regras operacionais do boleto.
Pagamento agendado	Envie `identificationField` com a data de agendamento.	O pagamento é programado para a data informada, desde que ela respeite a regra de dia útil.
Envio após o horário limite	Verifique se a operação ocorre depois das 14h.	Considere o horário limite (14h) e a regra de +1 dia útil para evitar agendamentos inválidos.

Checklist antes de enviar

Envie somente o que for necessário para o cenário.
Sempre logue o payload final antes do envio.
Implemente idempotência para evitar duplicidades.
Monitore seus webhooks e configure alertas para falhas.
Em produção, evite testes com boletos reais de terceiros.
Lembre-se do horário limite (14h) e da regra de +1 dia útil para agendamentos.

Comportamentos que exigem atenção