Endpoint responsible for restoring a charge previously removed.

This call allows you to reactivate the charge using the same original identifier, as long as it is in a state compatible with restoration.

When to use

Use this endpoint when your integration needs to recover a charge previously removed and place it back into the operational flow.

Some common scenarios include:

• restoration of a charge removed by mistake;
• reversal of an operational deletion;
• recovery of records removed in tests;
• correction of synchronization between the source system and Asaas;
• reactivation of a charge that still needs to remain available for tracking, consultation, or payment.

When not to use

Do not use this endpoint to:

• create a new charge;
• update data of an existing charge;
• refund a paid charge;
• cancel a subscription;
• restore a removed installment plan;
• restore a removed customer;
• reactivate charges that do not belong to the authenticated account;
• correct charges that can still be updated by other endpoints.

If the intention is to change charge data, use the charge update endpoint.

If the intention is to return amounts to the payer, use the refund flow corresponding to the payment method.

Request parameter

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

Identifier example:

pay_123456789

The id must correspond to an existing charge in the authenticated Asaas account and previously removed.

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

Permission and authentication

To use this endpoint, the request must be authenticated with a valid API Key from the Asaas account.

The key used must belong to the same environment as the request:

• Sandbox API Key for Sandbox calls;
• Production API Key for Production calls.

If the API Key is missing, invalid, or belongs to another environment, the request may return an authorization error.

Restoration dependencies

Before requesting restoration, validate whether:

• the charge was previously created in Asaas;
• the charge belongs to the authenticated account;
• the charge id was correctly stored by the integration;
• the charge was previously removed;
• the customer linked to the charge still allows the flow to continue;
• the charge is in a state compatible with restoration;
• the integration is prepared to update the internal status after restoration.

How restoration works

Restoration reactivates a charge previously removed, keeping the same original id.

After a successful restoration:

• the charge becomes available for consultation again;
• the charge may return to the corresponding operational flow;
• the original charge identifier is maintained;
• the charge is not recreated;
• a new charge is not generated;
• the data linked to the charge must be consulted again by the integration.

Restoration does not automatically change other resources that your application keeps in the source system, such as order, sale, internal status, reconciliation, or synchronization history.

Important behaviors

When using this endpoint, consider the following behaviors:

• restoration applies only to charges previously removed;
• the call uses the same id as the original charge;
• the operation does not create a new charge;
• the operation does not refund amounts;
• the operation does not automatically change orders, sales, or internal records of the integration;
• the restored charge must be consulted again after the operation;
• the final state of the charge must be used to update the source system;
• repeated calls for a charge already restored may be refused by the API;
• if the charge is not eligible for restoration, the API may return an error.

Important business rules

Before implementing this endpoint, consider the following rules:

• the charge must exist in Asaas;
• the charge must have been previously removed;
• the informed id must belong to the authenticated account;
• the request must be authenticated with a valid API Key;
• the charge must be in a state compatible with restoration;
• restoration keeps the same charge identifier;
• restoration does not create a new charge;
• restoration does not automatically change the integration’s internal history;
• restoration does not replace refund, cancellation, or update flows;
• the API may refuse the operation if the charge is not eligible.

The public documentation of the endpoint does not inform a fixed maximum period for restoration. Therefore, treat eligibility as a validation performed by the API at the time of the request.

Request example

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

Expected return

In case of success, the API returns status 200 OK.

After receiving success in the restoration, it is recommended to consult the restored charge to retrieve its updated data and confirm the current status in Asaas.

Recommended flow after the 200 return:

Request charge restoration
↓
Receive 200 OK return
↓
Consult the charge by the same id
↓
Validate the current charge status
↓
Update the record in the source system
↓
Resume the operational flow, if applicable

Consultation example after restoration

After restoring the charge, your integration can consult the same id to validate the current state of the resource.

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

This consultation helps confirm whether the charge returned to the expected flow and which data should be reflected in the source system.

Idempotency and repeated calls

Do not treat this endpoint as an idempotent operation.

If the charge has already been restored, a new restoration attempt may return an error, because the charge may no longer be in the removed state.

To avoid unnecessary calls:

• internally register when the restoration is requested;
• consult the charge before trying to restore it again;
• handle errors safely;
• do not execute automatic retries without validating the current state of the charge.

Relationship with other resources

Charge restoration does not automatically update the records maintained by your application.

After restoring the charge, evaluate whether it is also necessary to update:

• order or sale in the source system;
• internal charge status;
• audit logs;
• financial reconciliation control;
• communications sent to the customer;
• charge, due date, or tracking rules;
• records related to split, subscription, or installment plan, when applicable.

If the restored charge is linked to other flows, consult the related resources before resuming the operation.

Operational impacts

Restoring a removed charge can directly impact the synchronization between Asaas and the source system.

Some important impacts:

• a charge that was marked as removed may appear again as active or available for tracking;
• the source system needs to stop treating the charge as removed;
• automatic flows may start considering the charge again in consultations or internal routines;
• internal or external communications may need to be reviewed;
• reports, dashboards, and reconciliations may need to reflect the restoration;
• future actions must consider the updated charge status in Asaas.

Therefore, always update the internal record after restoration and keep logs of the operation.

Common errors

Some common errors when using this endpoint include:

Best practices

For a safer implementation, it is recommended to:

• store the charge id at the time of creation;
• internally register when a charge is removed;
• restore only charges removed improperly;
• consult the charge before restoration when there is doubt about the current state;
• consult the charge again after the 200 return;
• update the charge status in the source system;
• avoid automatic retries without prior validation;
• differentiate restoration from update, removal, cancellation, and refund;
• register operation logs for auditing;
• test the flow in Sandbox before using it in Production.

Sandbox precautions

This endpoint can be used in Sandbox to validate the restoration flow of removed charges.

During tests, it is recommended to validate:

• creation of a fictitious charge;
• removal of the charge;
• restoration using the same id;
• consultation of the charge after restoration;
• update of the status in the source system;
• restoration attempt with invalid id;
• restoration attempt of a charge that was not removed;
• application behavior in case of 400, 401, or 404 error.

These tests help ensure that your integration correctly handles removal and restoration flows before operating in Production.

Related content

See also:

• Create new charge;
• Retrieve a single charge;
• Retrieve charge status;
• Update existing charge;
• Delete charge;
• Refund charge;
• Restore removed charge with summarized data in the response;
• List charges;
• Webhooks for charges.