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.

{
  "reason": "Customer requested cancellation"
}

Response (200 OK)

{
  "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 for the full catalogue. The type URI in every error response deep-links to the matching row.