Skip to main content

Cancelling a Payout

Which statuses allow cancellation, and how to cancel via the portal and API.

Written by Ryan O
Updated today

Overview

Sometimes you need to cancel a payout after creating it. Anton allows cancellation, but only during certain stages of the payout lifecycle. This article explains when cancellation is possible and how to do it.

When Can You Cancel?

A payout can only be cancelled before it reaches processing status. Once a payout has been submitted to the payment rail provider, it cannot be cancelled.

Specifically, cancellation is allowed when the payout is in one of these statuses:

  • created

  • pending_screening

  • screening_failed

  • pending_approval

  • manual_review

When Can You Not Cancel?

Cancellation is not possible once the payout reaches any of these statuses:

  • processing -- Already submitted to the rail provider

  • sent -- Rail provider has dispatched the funds

  • completed -- Funds delivered (terminal status)

  • failed -- Delivery failed (terminal status)

  • returned -- Funds returned (terminal status)

  • cancelled -- Already cancelled (terminal status)

If you attempt to cancel a payout in one of these statuses, the API will return an error.

Cancelling via the API

To cancel a payout, send a POST request to the cancel endpoint:

curl https://api.antonpayments.dev/v1/payouts/pay_abc123/cancel \
  -X POST \
  -H "Authorization: Bearer ak_test_..."

If the cancellation succeeds, the payout status changes to cancelled and the response confirms the updated status. Reserved funds are released back to your available balance immediately.

If the payout cannot be cancelled (because it has already reached processing or a terminal status), you will receive an error response indicating the current status and explaining why cancellation is not possible.

Cancelling via the Portal

To cancel a payout from the merchant portal:

  1. Navigate to Payouts.

  2. Find the payout you want to cancel and click on it to open the detail view.

  3. If the payout is in a cancellable status, you will see a Cancel Payout button.

  4. Click the button and confirm the cancellation.

If the Cancel Payout button is not visible, the payout has already progressed past the point where cancellation is possible.

What Happens After Cancellation

  • Status changes to cancelled -- This is a terminal status. The payout will not be processed or retried.

  • Funds are released -- Any amount that was held from your available balance is released immediately and becomes available for new payouts.

  • Webhook notification -- If you have subscribed to payout events, you will receive a webhook notification for the cancellation.

  • Audit trail -- The cancellation is recorded in the payout history, including who cancelled it and when.

Handling Failed Payouts vs Cancelling

It is important to understand the difference between a cancelled payout and a failed payout:

  • Cancelled -- You chose to stop the payout before it was processed. Funds are released immediately.

  • Failed -- The payout was submitted to the rail but could not be delivered (e.g., wrong account number, bank rejection). Funds are typically released after the rail confirms the failure.

  • Returned -- The payout was sent and the funds reached the destination, but were returned (e.g., account closed). The timeline for fund release depends on the rail.

Best Practices

  • Act quickly -- Payouts move through screening fast (especially in production). If you need to cancel, do it as soon as possible after creation.

  • Use idempotency keys -- This prevents accidental duplicate payouts in the first place, reducing the need for cancellations.

  • Verify before submitting -- Double-check payee details, amounts, and currencies before creating a payout, especially in production where processing happens quickly.

Did this answer your question?