Testing Bill Payment

The Sandbox environment allows you to homologate integrations related to bill payments without the need to use real boletos or perform actual financial transactions.

To perform the tests, use the digitable line from a boleto generated in your own Asaas Sandbox account.

This flow allows you to validate payment creation, operation processing, and application behavior before using it in production.

When to use

This scenario is recommended for integrations that need to:

• perform bill payments via API;
• validate automated financial flows;
• homologate accounts payable processes;
• test business rules related to payments;
• validate API responses and error handling.

Prerequisites

Before starting the tests, you must:

1. Have a Sandbox account.
2. Have available balance for testing in the account.
3. Generate a boleto in the Sandbox environment.
4. Obtain the digitable line of that boleto.
5. Use the bill payment endpoint.

If you do not yet have available balance for testing, see the guide on adding balance in Sandbox.

How the test works

The payment is made using the digitable line of a boleto created in the Sandbox account itself.

Simplified flow:

Generate boleto
in Sandbox
        ↓
Obtain digitable line
        ↓
Create payment
via API
        ↓
Process payment
        ↓
Validate integration
result

This makes it possible to homologate the complete flow without relying on external boletos or real banking operations.

Important operation fields

When creating a bill payment, some data plays a fundamental role in the flow:

📘

Important

The complete request parameters are available in the endpoint documentation.

The purpose of this page is to demonstrate how to homologate this feature in Sandbox.

Homologation example

A common scenario consists of:

1. Creating a charge in Sandbox.
2. Copying the generated digitable line.
3. Using that digitable line in the bill payment request.
4. Validating the API response.
5. Confirming that your application correctly processed the operation result.

This flow allows you to validate the integration end-to-end before using it in the production environment.

Expected behavior

During Sandbox tests:

• no real funds are moved;
• no financial institution is contacted;
• processing occurs solely for homologation purposes;
• the results are intended for integration validation.

The goal is to allow the application to test its financial flows without operational risks.

Differences between Sandbox and Production

For this reason, it is recommended to carefully validate your application's behavior before going live in production.

Possible difficulties

If the payment is not processed as expected, check whether:

• the digitable line was copied correctly;
• the boleto used was created in Sandbox;
• there is available balance for the test;
• the required request fields were provided correctly;
• authentication is being performed using a Sandbox API Key.

Best practices

📘

Recommended

• Use boletos generated in the Sandbox account itself.
• Validate both success and failure scenarios during homologation.
• Log and monitor API responses during testing.
• Test application behavior in processing failure scenarios.
• Do not use production data during testing.

Operational impacts

Homologating bill payments allows you to validate in advance:

• accounts payable rules;
• financial automations;
• ERP system integrations;
• API response handling;
• internal application flows.

Proper validation reduces operational failures after going live in production.

API Reference

See the call to create a bill payment:

Create a bill payment