Skip to content

API

On this page

Cancel

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

POST/v1/withdrawals/:withdrawal_id/cancel

API key: Payout

Cancel a withdrawal that has not started executing yet. The window closes the moment Paymos begins working the payout — which happens while the withdrawal is still created, before anything is signed. A created status therefore does not by itself guarantee the withdrawal is still cancellable: once execution has started the call returns 409. 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.

Get Withdrawal Simulate Withdrawal Completion