Testing in the Sandbox

Use the Sandbox to validate the creation of bill payments, the handling of API responses, and the receipt of Webhooks without moving real funds.

Before you start

You need to:

• use a Sandbox account and API key;
• have an available balance to make the payment;
• create a bank slip (boleto) charge in the same Sandbox account;
• obtain the digitable line of that charge.

If you need to generate balance for the test, see Adding balance to a Sandbox account.

How to test

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
A["Prepare balance in the Sandbox"] --> B["Create a bank slip charge"]
B --> C["Obtain the digitable line"]
C --> D["Create the bill payment"]
D --> E["Store the ID"]
E --> F["Receive the Webhooks"]
F --> G["Validate the integration handling"]

classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px

class A inicio
class B,C,D,E,F validacao
class G sucesso

linkStyle default stroke:#94A3B8,stroke-width:2px

1. Create a bank slip in the Sandbox

Create a charge with billingType equal to BOLETO in the same Sandbox account used to test Bill Payment.

Then, obtain the digitable line of the charge.

• Create new payment
• Get digitable bill line

2. Create the bill payment

Send the digitable line in the identificationField field to:

POST /v3/bill

Example:

{
"identificationField": "34191090570404959480975279260006611980000081488",
"externalReference": "teste-sandbox-001"
}

Replace identificationField with the digitable line of the bank slip created in your own Sandbox account.

See the Create a bill payment endpoint.

3. Validate processing via Webhook

Store the ID returned on creation and use the Bill Payment Webhooks to validate changes to the operation.

In the Sandbox, the payment does not go through real bank clearing. Therefore, the final FAILED status after creation is expected in this environment.

When you receive BILL_FAILED, validate that your application:

• identifies the operation by bill.id;
• updates the status correctly;
• interprets bill.failReasons;
• handles the event idempotently.

Do not use periodic API queries as the main mechanism to track status changes.

See the Bill Payment events.

How to validate the test

Consider the flow approved when your application is able to:

• create the payment and store its ID;
• receive and process the Webhooks;
• update the internal state of the operation;
• handle the FAILED status expected in the Sandbox without interpreting it as real bank clearing.

The Sandbox behavior validates the technical integration, but does not represent the clearing of a bank slip in Production.

If the payment is not created

Check that:

• the bank slip was created in the Sandbox;
• the digitable line belongs to the bank slip used in the test;
• the account has an available balance;
• the request uses https://api-sandbox.asaas.com/v3;
• the API key belongs to the Sandbox.

For other responses, see Common errors and exceptions — Bill Payment.

Next steps

• See the Bill Payment statuses
• Configure Webhook event handling
• See the common errors and exceptions
• See the Create a bill payment endpoint