Cancel a Transfer

Overview

Cancel an in-progress funding transfer with DELETE /api/transfers/{transfer_guid}. Cancellation
is best-effort: the platform attempts to stop the transfer before it settles, but the outcome
depends on how far the transfer has already progressed at the payment provider.

A cancellation request moves an eligible transfer to the cancelling state. The transfer then
resolves to one of two terminal states — failed (cancelled successfully) or completed (the
transfer settled before the cancellation took effect).

ℹ️

API version required

This operation is available from API version 2026-04-01. Send the Accept-Version: 2026-04-01
header (or a later version) on the request. Earlier versions do not expose this operation and
return 404. See API Versioning.

Which transfers can be cancelled

Only funding transfers can be cancelled, and only while they are in an early state. The platform
accepts a cancellation request when both of these conditions are met:

This operation supports funding transfers only. Other transfer types — such as instant_funding,
book, and crypto — are not supported by this endpoint; where those types support cancellation,
they use a different flow (for example, see
Instant funding). An eligible funding transfer
must also be in storing, pending, or reviewing; one already in holding, completed, or
failed cannot be cancelled. A request against a transfer that does not meet both conditions
returns 422 transfer_not_cancellable.

Request a cancellation

Send a DELETE request with the transfer's GUID. No request body is required, and the token must
carry the transfers:execute scope:

DELETE /api/transfers/{transfer_guid}
Accept-Version: 2026-04-01
Authorization: Bearer YOUR_TOKEN

{
  "guid": "transfer_guid",
  "transfer_type": "funding",
  "customer_guid": "customer_guid",
  "quote_guid": "quote_guid",
  "asset": "USD",
  "side": "deposit",
  "state": "cancelling",
  "failure_code": null,
  "amount": 10000,
  "fee": 0
}

The 200 response returns the transfer in the cancelling state. This confirms the request was
accepted — not that the transfer was cancelled.

Best-effort cancellation and the race

cancelling is a transient state. When you request a cancellation, the platform records the
request and asks the running transfer workflow to stop. Whether the transfer can actually be
stopped depends on the payment provider, which is the final authority on the outcome.

Two outcomes are possible:

• Cancellation succeeds — the transfer transitions from cancelling to failed with
  failure_code: cancelled.
• Cancellation loses the race — the transfer settled at the provider before the cancellation
  took effect, so it transitions from cancelling to completed, as if it had not been
  cancelled.

⚠️

There is no cancelled transfer state

A successfully cancelled transfer ends in state: failed with failure_code: cancelled, not in
a cancelled state. Do not wait for a cancelled state — check for the terminal failed or
completed state instead.

Confirm the outcome

Because cancellation is asynchronous, confirm the terminal state after requesting it. Poll
GET /api/transfers/{transfer_guid} until the transfer leaves cancelling:

{
  "guid": "transfer_guid",
  "transfer_type": "funding",
  "state": "failed",
  "failure_code": "cancelled"
}

Alternatively, subscribe to webhooks. The platform emits a
transfer.cancelling event when the transfer enters cancelling, followed by a terminal
transfer.failed event (with failure_code: cancelled) or a transfer.completed event. There is
no transfer.cancelled event.

Errors

{
  "status": 422,
  "error_message": "Transfer cannot be cancelled in its current state",
  "message_code": "transfer_not_cancellable"
}

A 404 can also mean the request targeted an API version earlier than 2026-04-01, which does not
expose this operation. Confirm the Accept-Version header before treating a 404 as a missing
transfer.

Next steps

• Transfer Process — the full transfer lifecycle
  and states.
• Cancel Transfer API reference — the endpoint
  specification.
• API Versioning — target API version 2026-04-01.
• Webhooks — subscribe to transfer state changes.