General Best Practices

Best practices for integrating Bill Payment, including the recommended flow, minimal payload, scheduling rules, idempotency, and webhooks.

Use these best practices to integrate Bill Payment with fewer duplicates, fewer operational failures, and more predictability in bill processing.

When to Use Bill Payment

Use Bill Payment when your application needs to pay bills via the Asaas API using the bill's barcode/digitable line. This feature is recommended for flows where you want to automate recurring bills, centralize operational payments, or schedule payments without relying on manual execution.

The required field for the operation is identificationField (the bill's digitable line). With it, you can initiate an immediate payment or schedule the payment for a future date, following the cutoff time and business day rules.

Recommended Integration Flow

Receive or capture the bill's digitable line. Store the value that will be sent in identificationField and avoid transforming the field unnecessarily.
Build the final payload. Send only the fields necessary for the operation, including scheduleDate only when the payment is scheduled.
Log the payload before sending. Save the final request body for auditing, support, and failure investigation.
Apply idempotency in your application. Before resending an attempt, check whether the same bill has already been sent to avoid duplicate payments.
Send the payment request. For immediate payment, do not send scheduleDate; for scheduled payment, provide a valid date.
Track the operation's result. Monitor webhooks and set up alerts to identify failures, delays, or unexpected behavior.

Minimal Payload Example

Use this format when you want to request a payment without explicit scheduling:

{
  "identificationField": "83660000001084301380074119002551100010601813"
}

The final payload should contain only the fields required for the scenario you are executing. If your application adds optional fields, log the final body sent to make it easier to compare what was planned against what reached the API.

Immediate and Scheduled Payment Rules

Scenario	How to send it	Expected behavior
Immediate payment	Send `identificationField` without `scheduleDate`.	The payment is processed at the time of the request, following the bill's operational rules.
Scheduled payment	Send `identificationField` with the scheduling date.	The payment is scheduled for the provided date, as long as it follows the business day rule.
Sending after the cutoff time	Check whether the operation occurs after 2 PM.	Consider the cutoff time (2 PM) and the +1 business day rule to avoid invalid scheduling.

Checklist Before Sending

Send only what is necessary for the scenario.
Always log the final payload before sending.
Implement idempotency to avoid duplicates.
Monitor your webhooks and set up alerts for failures.
In production, avoid testing with real third-party bills.
Remember the cutoff time (2 PM) and the +1 business day rule for scheduling.

Behaviors That Require Attention

Duplicates: if an attempt fails due to a timeout or communication error, check your internal records before resending the same bill.
Invalid scheduling: validate the date before sending when using scheduleDate, especially in operations close to the cutoff time.
Webhook failures: set up alerts for missing expected events or error responses at your application's endpoint.
Testing in production: do not use real third-party bills to validate integration, payload, or retry behavior.