Allows cancelling a bill payment that is still eligible for cancellation.

This endpoint should be used when it is necessary to prevent the execution of a previously created payment, provided that it has not yet been processed.

Before performing the cancellation, it is recommended to retrieve the payment and verify the canBeCancelled property of the bill object.

When to use

This endpoint is recommended in scenarios such as:

• cancellation requested by the user;
• identification of incorrect payment information;
• the need to prevent settlement before processing;
• internal operational adjustments.

If the payment has already been processed or is no longer eligible for cancellation, the operation may be rejected.

Dependency on payment retrieval

Before requesting the cancellation, it is recommended to retrieve the payment and verify the following attribute:

{
  "canBeCancelled": true
}

This field indicates whether the payment can still be cancelled.

📘

Important

The existence of a payment does not necessarily mean that it can still be cancelled.

Always validate the canBeCancelled attribute before performing this operation.

Recommended flow

In a typical integration, the cancellation flow is:

Retrieve payment
↓
Check canBeCancelled
↓
Execute cancellation
↓
Update status internally

Important behaviors

When a bill payment is cancelled:

• the payment will not be executed;
• the cancellation cannot be reversed through this endpoint;
• processed payments may no longer allow cancellation;
• it is recommended to update the payment status in the originating system after the operation is completed.

⚠️

Important

Cancellation prevents the payment from being executed, but it does not automatically create a new payment request.

If the payment still needs to be made, a new operation must be created.

Example flow

Retrieve the payment:

GET /v3/bill/{id}

Verify:

{
  "canBeCancelled": true
}

Execute:

POST /v3/bill/{id}/cancel

Common errors

400 Bad Request

This may occur when the payment does not meet the conditions required for cancellation.

401 Unauthorized

Indicates authentication failure or the use of an invalid API key.

404 Not Found

Indicates that the provided identifier does not correspond to an existing payment.

Best practices

📘

Recommended

• Retrieve the payment before requesting cancellation.
• Validate the canBeCancelled attribute.
• Update the payment status in the originating system after the operation.
• Do not assume that every payment can be cancelled.
• Handle error responses to maintain integration consistency.

Operational impacts

Cancellation prevents the payment from being executed.

If the operation is part of financial processes, it is recommended to update reconciliation systems, administrative interfaces, and user notifications to properly reflect the cancellation.

Related content

• Retrieve bill payment.
• Create bill payment.
• List bill payments.
• Update bill payment.