Refunds Guide

Check the refunds guide for more information.

POST /v3/payments/{id}/bankSlip/refund

Endpoint responsible for initiating the refund request for a charge paid by bank slip.

Unlike refunds performed through payment methods that allow direct return to the payment origin, a bank slip refund requires the paying customer to provide the bank account details of the account where they want to receive the amount. Therefore, when requesting the refund, the API returns a link that must be sent to the customer to fill in the bank details and submit identification documents.

This flow allows Asaas to validate the necessary information before completing the return of the amount.

When to use

Use this endpoint when your integration needs to request the return of a charge paid by bank slip.

Some common scenarios include:

• cancellation of a sale paid by bank slip;
• withdrawal from the purchase after payment;
• charge issued or paid incorrectly;
• return requested by the end customer;
• need to start the refund process of a bank slip through the API.

This endpoint should be used only for charges paid by bank slip. For refunds of other payment methods, use the endpoint corresponding to the charge type.

When not to use

Do not use this endpoint to:

• refund charges paid by credit card;
• refund Pix charges;
• cancel a charge that has not yet been paid;
• remove a charge;
• change data from the original charge;
• consider the amount returned immediately after the call.

If the charge has not yet been paid, evaluate whether the correct flow is to update, remove, or cancel the charge, according to the integration scenario.

Required permission

To use this endpoint, the API key must have permission to request refunds:

PAYMENT_REFUND:WRITE

If the key used does not have permission for this operation, the request may return an authorization error.

Bank slip refund flow

The bank slip refund depends on the participation of the paying customer to fill in the necessary data.

In a typical integration, the flow occurs as follows:

Identify the charge paid by bank slip
↓
Request the refund via API
↓
Receive the form link returned by Asaas
↓
Send the link to the paying customer
↓
Customer informs the bank details
↓
Customer sends the requested identification documents
↓
Asaas validates the received information
↓
Refund is processed according to the analysis result
↓
Integration tracks the refund status

The call to this endpoint does not complete the refund immediately. It starts the process and returns the link required for the customer to complete the mandatory information.

Request parameter

This endpoint uses only the charge identifier in the request path.

The id field must correspond to an existing charge in Asaas that is eligible for bank slip refund.

This endpoint does not require sending parameters in the request body.

Expected return

When the refund is successfully requested, the API returns the information required to continue the process, including the link that must be accessed by the paying customer.

This link is returned in the requestUrl field and allows the customer to:

• inform the bank details to receive the amount;
• send identification documents;
• prove that they are the holder of the informed bank account.

Request example

curl --request POST \
  --url https://api-sandbox.asaas.com/v3/payments/pay_123456789/bankSlip/refund \
  --header 'accept: application/json' \
  --header 'access_token: $ASAAS_API_KEY'

Response example

In case of success, the API returns the link that must be sent to the paying customer.

{
  "requestUrl": "https://sandbox.asaas.com/solicitar-estorno/37ij5mdxwo1234"
}

Important business rules

Before requesting the bank slip refund, consider the following rules:

• the charge must exist in Asaas;
• the charge must be a bank slip;
• the charge must be in a situation compatible with a refund request;
• the API key used must have permission for refund;
• the returned link must be filled in by the paying customer;
• the bank details must be informed by the customer in the provided link;
• the documents sent must prove the customer’s identity and the ownership of the informed bank account;
• the refund is not completed at the time of the call, as it depends on the sending and validation of the information by the customer.

If the charge is not eligible for bank slip refund, the API may return an error.

Relevant behaviors

When using this endpoint, consider the following behaviors:

• the refund request starts an asynchronous flow;
• the API return does not mean that the amount has already been returned to the customer;
• the customer needs to fill in the link for the process to move forward;
• invalid, incomplete, or inconsistent documents may prevent the refund from being completed;
• while the refund is not finalized, the integration must track the request status;
• the final refund situation should be considered only after processing confirmation.

Refund statuses can be tracked through the charge refund consultation resources.

Refund status

After the request, the refund may go through different statuses.

The main statuses returned in the refunds field are:

The integration must be prepared to track these statuses and update the order or internal record only when there is confirmation compatible with the operation’s business rule.

Operational impacts

A bank slip refund can directly impact the integration’s financial reconciliation.

When starting this process, evaluate:

• whether the order should be canceled immediately or only after the refund is completed;
• whether the internal sale status should remain as “refund requested” while the customer has not filled in the link;
• whether it will be necessary to send additional communications to the customer;
• whether the operation has split, transfer, or internal financial control flows related to the charge;
• how your platform will handle pending, completed, or canceled refunds.

If the charge is linked to other financial flows, such as payment split, also consider the effects of the refund on these resources.

Common errors

Some common errors when using this endpoint include:

In case of error, validate whether the charge ID is correct, whether the charge is a bank slip, and whether the API key has the required permission.

Best practices

For a safer implementation, it is recommended to:

• store the charge ID at the time of creation;
• validate whether the charge has been paid before requesting the refund;
• use this endpoint only for bank slip charges;
• send the returned link to the customer through a secure channel;
• instruct the customer to correctly fill in the bank details;
• track the refund status after the request;
• internally register the request date and the returned link;
• not consider the refund completed only by the initial API response;
• consult the charge refunds to update the internal status of the operation.

Sandbox precautions

This endpoint can be used in Sandbox to validate the refund request flow.

During tests, it is recommended to validate:

• whether the integration can request the refund;
• whether the link is returned correctly;
• whether the internal system registers the refund as pending;
• whether the status tracking flow is correctly implemented.

Avoid using real third-party data during tests.

Related content

See also:

• Refunds Guide;
• List refunds of a charge;
• Refund charge;
• Refund installment plan;
• Bank slip charges;
• Payment Split, when applicable to the operation;
• Webhooks for charges.