# Cancel Withdrawal

> Cancel a pending withdrawal before transaction signing begins, understand which states allow cancellation, and process the updated response.

`POST /v1/withdrawals/:withdrawal_id/cancel`

:::endpoint
POST /v1/withdrawals/:withdrawal_id/cancel
:::

**API key:** `Payout`

Cancel a withdrawal while it is still `created`. The status alone is not enough: execution can start inside `created`, before anything is signed, and until it ends, the call returns `409 withdrawal_cannot_be_cancelled`. If execution ends without paying out, the withdrawal goes back to waiting and can be cancelled again. The exception is an earlier execution that may already have sent funds not yet confirmed: those funds can still reach the recipient, so the withdrawal cannot be cancelled and the amount stays on hold. If cancelling a `created` withdrawal keeps returning `409`, contact support. Cancelling an already-cancelled withdrawal is a no-op: it returns `200` with the same withdrawal, not an error.

## Request body

Send a `reason` (required, max 500 characters). Paymos stores it on the withdrawal and writes it to the audit log. It does not come back to you: the cancel response and the `withdrawal.cancelled` webhook both carry the status, not the reason.

```json
{
  "reason": "Customer requested cancellation"
}
```

## Response (200 OK)

```json
{
  "withdrawal_id": "wdr_2M8K6Q4P9X1Z7A3B",
  "external_order_id": "payout-001",
  "status": "cancelled",
  "is_final": true,
  "is_test": true,
  "amount": "100.00",
  "currency": "USDT",
  "network": "TRC20",
  "destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
  "created_at": 1739289600,
  "cancelled_at": 1739289660
}
```

## Errors

A Payment (`pk_`) key is rejected with `403 payout_key_required` — but only on a well-formed request: the body is parsed before the key type is checked, so a missing `reason` or an unparseable body returns `400` first. See [Error Codes](/docs/errors/codes.md) for the full catalogue. The `type` URI in every error response deep-links to the matching row.