> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.hopnow.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel Payout

> Cancel a pending payout and release its held funds and fees

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

**account\_id** `string` *required*

The account's external ID (starts with `acct_`)

**payout\_id** `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](https://apidocs.hopnow.io/fx/api-reference/payouts/get-payout.md), with `status` set to `cancelled`.

Subscribed webhook endpoints receive `payout.failed` with `data.status` set to `cancelled`.

**id** `string`

Payout identifier (starts with `po_`)

**object** `string`

Always returns `"payout"`

**account\_id** `string`

Account ID (starts with `acct_`)

**beneficiary\_id** `string`

Beneficiary ID (starts with `bene_`). `null` only on payouts Hop booked manually on your behalf.

**payout\_destination\_id** `string`

Payout destination ID (starts with `dest_`). `null` only on payouts Hop booked manually on your behalf.

**network** `string`

Blockchain network for a crypto payout, otherwise `null`

**txn\_hash** `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.

**amount** `string`

Payout amount (decimal)

**currency** `string`

Currency code

**payment\_rail** `string | null`

Selected payout rail, using the lowercase values listed in [Create Payout](https://apidocs.hopnow.io/fx/api-reference/payouts/create-payout.md#param-payment-rail). 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.

**amount\_in\_usd** `string`

Amount converted to USD, or `null` when no rate was available

**funding\_source** `object`

Balance funding the payout, always present: `{"type": "trading_account"}` for a withdrawal, `{"type": "virtual_account", "virtual_account_id": "va_…"}` for a payout

**platform\_fee** `object`

Platform fee charged on top of `amount` (`currency`, `amount`), or `null` when none

**status** `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](https://apidocs.hopnow.io/fx/api-reference/payouts/cancel-payout.md) accepts `pending` and `pending_approval` and releases held funds and fees back to their original balances.

**uetr** `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.

**tracking\_details** `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.

**child attributes**

**uetr** `string | null`

SWIFT unique end-to-end transaction reference.

**imad** `string | null`

Fedwire input message accountability data.

**omad** `string | null`

Fedwire output message accountability data.

**trace\_number** `string | null`

ACH trace number.

**initiated\_at** `string`

ISO 8601 timestamp when the payout was initiated

**submitted\_at** `string`

ISO 8601 timestamp when Hop sent the payment command to the provider, or `null`

**completed\_at** `string`

ISO 8601 timestamp when the payout completed, or `null`

**failed\_at** `string`

ISO 8601 timestamp when the payout failed, or `null`

**failed\_reason** `string`

Reason for failure, or `null`

**voided\_at** `string`

ISO 8601 timestamp when the payout was voided, or `null`

**voided\_reason** `string`

Reason the payout was voided, or `null`

**note** `string`

Note carried on the payout, or `null`

**created** `string`

ISO 8601 timestamp when created

**updated** `string`

ISO 8601 timestamp when last updated

**created\_by** `string`

Actor that created the payout: the API key id (starts with `ak_`), or `hop_admin` for a manual payout

**updated\_by** `string`

Actor that last updated the payout, or `null`

## Errors

| Status | `code` | When |
| - | - | - |
| `403` | `ACCESS_DENIED` | The API key lacks write access on the payments scope |
| `404` | `RESOURCE_NOT_FOUND` | The account or payout is unknown, or the payout belongs to another account |
| `409` | `BUSINESS_RULE_VIOLATION` | The payout is no longer eligible for cancellation, including payouts in `processing`, `completed`, `failed`, `returned` or `voided` |
| `422` | `APPROVAL_CONCURRENT_UPDATE` | The payout changed concurrently; retrieve the payout and retry if it is still in `pending` or `pending_approval` |

## Request Example

```bash theme={null}
curl -X POST "https://api.hopnow.io/v1/accounts/acct_ka44qsvpo8q3wtzuwfqf0h6u/payouts/po_r4ft5s7cuvimpoloqd8gwksw/cancel" \
  -H "X-API-Key: your_api_key" \
  -H "X-Signature: hmac_signature" \
  -H "X-Timestamp: 1234567890" \
  -H "X-Nonce: abc123"
```

## Response Example

```json theme={null}
{
  "id": "po_r4ft5s7cuvimpoloqd8gwksw",
  "object": "payout",
  "account_id": "acct_ka44qsvpo8q3wtzuwfqf0h6u",
  "beneficiary_id": "bene_9gt1ummgx127biovlurm9mq2",
  "payout_destination_id": "dest_7h3n5q8v2c6b1m4x9z0j5k2l",
  "amount": "100.00",
  "currency": "USD",
  "payment_rail": null,
  "amount_in_usd": "100.00",
  "funding_source": {"type": "trading_account"},
  "platform_fee": null,
  "status": "cancelled",
  "uetr": null,
  "tracking_details": {
    "uetr": null,
    "imad": null,
    "omad": null,
    "trace_number": null
  },
  "network": null,
  "txn_hash": null,
  "initiated_at": "2026-01-15T10:00:00Z",
  "submitted_at": null,
  "completed_at": null,
  "failed_at": null,
  "failed_reason": "The payout was cancelled. Please contact support for more information.",
  "voided_at": null,
  "voided_reason": null,
  "note": "Monthly payment",
  "created": "2026-01-15T10:00:00Z",
  "updated": "2026-01-15T10:01:00Z",
  "created_by": "ak_3f7k9m2p5r8t1v4x6z0b3n5q",
  "updated_by": "ak_3f7k9m2p5r8t1v4x6z0b3n5q"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.