Refund Guide

Check the refund guide for more information.

This endpoint allows you to refund an installment paid by credit card, as long as it has been received or confirmed.

When performing the refund, the corresponding balance will be debited from the Asaas account responsible for receiving the payment, and the charge will be canceled on the customer's card. The cancellation may take up to 10 business days to appear on the payer's statement, as this timeframe depends on the card operator's processing.

When to use this endpoint

Use this endpoint when your integration needs to:

• fully or partially cancel an installment paid by credit card;
• return the amount of an installment purchase to the customer;
• refund only part of the installment amount;
• refund amounts linked to splits, when the installment has payment splitting;
• correct an installment charge created or paid with an incorrect amount.

To refund a standalone charge, use the specific charge refund endpoint. This endpoint should be used only when the charge is linked to an installment.

Full or partial refund

The refund behavior depends on the fields sent in the request body:

• To refund the full installment amount, do not inform the value or splitRefunds fields.
• To refund only part of the installment, inform the value field with the desired amount.
• To refund specific split amounts, inform the splitRefunds array.
• To combine a split refund with a refund from the main charge, inform value and splitRefunds in the same request.

Request examples

Refund the full installment amount

To perform a full refund, send the request without a body or with an empty body.

curl --request POST \
  --url https://api-sandbox.asaas.com/v3/installments/{id}/refund \
  --header 'accept: application/json' \
  --header 'access_token: $ASAAS_API_KEY' \
  --header 'content-type: application/json' \
  --data '{}'

Refund a partial amount

In this example, only R$ 50.00 of the installment will be refunded.

{
  "value": 50.00
}

Refund specific split amounts

In this example, the refund will be made only from the informed splits.

{
  "splitRefunds": [
    {
      "id": "6fba235c-3726-4e32-b4e6-85f46e10cc2e",
      "value": 25.00
    },
    {
      "id": "cff860dd-148e-48ca-ac8e-849684175158",
      "value": 10.00
    }
  ]
}

Combine a split refund with a refund from the main charge

In this example, the total refund amount will be R$ 100.00. Of this total, R$ 40.00 will be refunded from a split, and the remaining R$ 60.00 will be deducted from the main charge.

{
  "value": 100.00,
  "splitRefunds": [
    {
      "id": "6fba235c-3726-4e32-b4e6-85f46e10cc2e",
      "value": 40.00
    }
  ]
}

Response example

In case of success, the response returns the updated installment data, including the refund information.

{
  "object": "installment",
  "id": "2765d086-c7c5-5cca-898a-4262d212587c",
  "value": 360.00,
  "paymentValue": 30.00,
  "installmentCount": 12,
  "billingType": "CREDIT_CARD",
  "refunds": [
    {
      "status": "DONE",
      "value": 100.00,
      "description": null,
      "refundedSplits": [
        {
          "id": "6fba235c-3726-4e32-b4e6-85f46e10cc2e",
          "value": 40.00,
          "done": true
        }
      ]
    }
  ]
}

Integration best practices

Before requesting the refund, validate whether the installment is actually eligible for refund and whether the informed amount does not exceed the amount available for return.

For partial refunds, store the amount already refunded in your system to avoid duplicate attempts or amounts greater than allowed.

When using splitRefunds, validate whether the informed IDs correspond to the splits linked to the installment. Each item in the array must inform the split identifier and the amount that will be refunded from it.

If the request returns a 400 error, review the sent amounts, the installment status, and the informed split data. For 401 errors, validate the API key used. For 404 errors, confirm whether the installment identifier is correct.

Avoid performing automatic retries without validating the previous result. Before trying again, check the installment to confirm whether the refund was registered, especially in timeout or network instability scenarios.

Refund impacts

After the refund is processed:

• the corresponding amount will be debited from the Asaas account;
• the cancellation will be requested from the card operator;
• the timeframe for the customer to view the cancellation on the statement may take up to 10 business days;
• in refunds with split, the amounts informed in splitRefunds will be refunded from the respective splits;
• if the refund is partial, the installment may keep a history of paid and refunded amounts.