Skip to main content
POST
Cancel Payout
Cancels a payout with a status of pending or pending_approval. Supports both trading account withdrawals and virtual account-funded payouts.

Cancellation Behavior

  • The payout status changes to cancelled.
  • Any active approval requests are cancelled.
  • Held funds and fees are released back to their original balances.
  • Cancellation is final. A new payout must be created to initiate the payment again.

Request

No request body or Idempotency-Key header is required. Cancelling an already-cancelled payout returns 200 OK with the existing payout object. No additional funds are released or duplicate notifications sent. Requires an API key with write access to the payments scope.

Path Parameters

string
required
The account’s external ID (starts with acct_)
string
required
The payout’s external ID (starts with po_). Must belong to this account.

Response

Returns 200 with the payout in the same flat shape as Get Payout, with status set to cancelled. Subscribed webhook endpoints receive payout.failed with data.status set to cancelled.
string
Payout identifier (starts with po_)
string
Always returns "payout"
string
Account ID (starts with acct_)
string
Beneficiary ID (starts with bene_). null only on payouts Hop booked manually on your behalf.
string
Payout destination ID (starts with dest_). null only on payouts Hop booked manually on your behalf.
string
Blockchain network for a crypto payout, otherwise null
string
Blockchain transaction hash for a crypto payout, otherwise null. It appears once the payout is on chain, so it is null on a payout that has not been submitted yet.
string
Payout amount (decimal)
string
Currency code
string | null
Selected payout rail, using the lowercase values listed in Create Payout. Returned from creation onward when a rail was selected. null means no explicit selection, including on historical payouts. This field records the selection, not confirmation of the rail actually used by the provider.
string
Amount converted to USD, or null when no rate was available
object
Balance funding the payout, always present: {"type": "trading_account"} for a withdrawal, {"type": "virtual_account", "virtual_account_id": "va_…"} for a payout
object
Platform fee charged on top of amount (currency, amount), or null when none
string
Payout status, one of eight values:
  • pending: funded and queued, awaiting submission
  • pending_approval: waiting for approval in your portal under an approval policy (optional)
  • processing: submitted for processing
  • completed: processed by the bank or payout provider
  • failed: the payout could not be funded or was rejected; any held funds are released back to the originating balance
  • cancelled: cancelled before submission; the payout hold is released
  • returned: the payment is returned by the recipient’s bank
  • voided: a completed payout is reversed
Transitions: pending → pending_approval | processing | completed | failed | cancelled; pending_approval → pending | cancelled; processing → completed | failed; completed → returned | voided. failed, cancelled, returned and voided are terminal.Cancel Payout accepts pending and pending_approval and releases held funds and fees back to their original balances.
string
SWIFT UETR (unique end-to-end transaction reference) for a wire, or null. Also available as tracking_details.uetr; this top-level field remains for compatibility.
object
Payment-network tracking identifiers, populated as they become available. The object is always present; unavailable or inapplicable identifiers are null. The same object is included in payout webhooks.
string
ISO 8601 timestamp when the payout was initiated
string
ISO 8601 timestamp when Hop sent the payment command to the provider, or null
string
ISO 8601 timestamp when the payout completed, or null
string
ISO 8601 timestamp when the payout failed, or null
string
Reason for failure, or null
string
ISO 8601 timestamp when the payout was voided, or null
string
Reason the payout was voided, or null
string
Note carried on the payout, or null
string
ISO 8601 timestamp when created
string
ISO 8601 timestamp when last updated
string
Actor that created the payout: the API key id (starts with ak_), or hop_admin for a manual payout
string
Actor that last updated the payout, or null

Errors

Request Example

Response Example