Endpoint responsible for removing a charge registered in Asaas.

This operation should be used when the charge should no longer remain active in the integration flow, such as in cases of incorrect issuance, replacement by a new charge, or interruption of a charge that should not yet be made available for payment.

Deletion removes the charge from the active flow, but should not be treated as a reversal, refund, or confirmation of return of amounts already paid.

When to use this endpoint

Use this endpoint when your integration needs to:

• remove a charge created incorrectly;
• prevent a pending charge from remaining available for payment;
• clean up charges created in tests;
• correct an operation before generating a new charge;
• replace a charge with another one with adjusted data;
• remove a charge that should no longer be presented to the payer;
• synchronize the removal of a charge between Asaas and the source system.

This endpoint is more suitable for charges that have not yet been paid or that should no longer continue in the charge flow.

When not to use

Do not use this endpoint to:

• return amounts to the payer;
• reverse a paid charge;
• permanently cancel a subscription;
• remove all installments of an installment plan;
• change data of an existing charge;
• correct a charge that can still be updated;
• handle financial reconciliation of payments already received.

If the charge has already been paid and the intention is to return the amount to the customer, use the reversal flow corresponding to the payment method.

If the charge belongs to a subscription, installment plan, or other source resource, also evaluate the behavior of that resource before removing only the individual charge.

Request parameter

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

The id must correspond to a charge previously created in Asaas, normally in the format:

pay_pCczZjBBr6RL

This identifier is returned at the time the charge is created and can also be obtained in the listing or consultation of charges.

This endpoint does not use body parameters.

Prerequisites

Before removing a charge, check whether:

• the charge was previously created in Asaas;
• your application has the charge id;
• the charge belongs to the authenticated account;
• the API key used belongs to the correct account;
• the charge should still be removed from the active flow;
• the payer should no longer use this charge for payment;
• your application is prepared to update the charge status in the internal database.

Recommended flow

In a typical integration, the charge deletion should follow the flow below:

Identify the charge in the internal database
↓
Consult the charge in Asaas
↓
Validate whether it should still be removed
↓
Request deletion
↓
Validate the API response
↓
Update the charge status in the internal database
↓
Interrupt actions related to the removed charge

Before removing the charge, it is recommended to consult its current state to avoid deleting a charge that has already been paid, replaced, reversed, or linked to another operational flow.

Request example

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

Response example

In case of success, the API returns a summarized response confirming the deletion of the charge.

{
  "deleted": true,
  "id": "pay_pCczZjBBr6RL"
}

Deletion behavior

When deleting a charge:

• the charge no longer remains active in the integration flow;
• the original charge identifier is kept in the response;
• the charge link should no longer be sent to the payer;
• the charge should no longer be presented as an active charge in the source system;
• the operation does not create a new charge;
• the operation does not automatically change other charges;
• the operation does not automatically remove a source subscription or installment plan;
• the operation does not represent the return of paid amounts;
• the application must update its internal database to reflect that the charge was removed.

Depending on the scenario, a removed charge may later be restored through the specific restoration endpoint.

Deletion, update, and reversal

Charge deletion should not be confused with update or reversal.

Relationship with subscriptions and installment plans

A charge may have been created individually or generated automatically from another resource, such as a subscription or installment plan.

Before deleting a charge, check whether it is linked to:

• a subscription;
• an installment plan;
• an order in the source system;
• an invoice;
• a split flow;
• an internal reconciliation control;
• notifications or communications sent to the payer.

Deleting an individual charge does not necessarily mean that the source resource has been ended.

Examples:

• if the charge belongs to a subscription, new charges may continue to be generated according to the recurrence;
• if the charge belongs to an installment plan, other installments may remain active;
• if the charge has an invoice or associated fiscal control, evaluate the impacts before removal;
• if the charge is linked to an external order, update the order to avoid divergence between systems.

Restoring a removed charge

If the deletion was performed by mistake, evaluate the use of the removed charge restoration endpoint.

Restoration allows a previously removed charge to be reactivated, using the same original identifier, when the scenario is compatible.

Recommended flow:

Charge removed by mistake
↓
Request restoration
↓
Consult the restored charge
↓
Update the internal database
↓
Resume the operational flow

Idempotency and repeated calls

Do not treat this endpoint as an idempotent operation without validating the API response.

If deletion is requested more than once for the same charge, the behavior may vary according to the current state of the record.

Possible scenarios:

After a successful deletion, update your internal database to avoid unnecessary new attempts.

Important business rules

Before implementing this endpoint, consider the following rules:

• only existing charges belonging to the authenticated account can be removed;
• the id provided must correspond to a charge previously created in Asaas;
• deletion removes the charge from the active flow;
• deletion does not represent reversal, refund, or return of amounts;
• paid, confirmed, or charges linked to completed financial flows may require specific handling;
• charges linked to subscriptions or installment plans may have dependencies with the source resource;
• deletion does not automatically change the order status in the external system;
• deletion should not be used as a financial reconciliation mechanism;
• the application must internally register and synchronize the removal.

Common errors

Some common errors when using this endpoint include:

Best practices

When implementing charge deletion, it is recommended to:

• store the charge id returned by Asaas at the time of creation;
• consult the charge before deleting it;
• validate the current status of the charge;
• differentiate deletion, reversal, and update;
• avoid deleting paid charges without evaluating the correct financial flow;
• register logs of who requested the deletion and when it occurred;
• update the internal database after successful deletion;
• interrupt the sending of links or notifications related to the removed charge;
• validate related resources, such as subscription, installment plan, invoice, or external order;
• handle 400, 401, and 404 errors clearly;
• avoid automatic retries without consulting the current state of the charge;
• test the flow in Sandbox before making the feature available in Production.

Operational impacts

Deleting a charge can directly impact the financial operation and the customer experience.

Some possible impacts are:

• unavailability of the invoice link;
• interruption of the charge to the payer;
• need to update the order in the source system;
• divergence between Asaas and the external system if the database is not synchronized;
• risk of duplication if a new charge is created without properly removing or replacing the previous one;
• impact on internal financial reports;
• need to review linked subscriptions, installment plans, or invoices;
• increase in support contacts if the customer tries to pay a removed charge.

Therefore, treat deletion as a sensitive operation and maintain internal traceability.

Sandbox precautions

This endpoint can be tested in Sandbox.

It is recommended to validate the following scenarios:

• create a charge;
• consult the created charge;
• delete the charge;
• consult the charge after deletion;
• try to delete the same charge again;
• restore the removed charge, when applicable;
• try to delete a nonexistent ID;
• validate how your application updates the internal database in each response.

These tests help define the expected behavior before operating in Production.

Related content

See also:

• Create new charge;
• Retrieve a single charge;
• List charges;
• Update existing charge;
• Restore removed charge;
• Reverse charge;
• Create subscription;
• Remove subscription;
• Cancel charges of an installment plan;
• Webhooks;
• What can be tested in Sandbox.