Skip to content

API

On this page

Cancel

Cancel a pending withdrawal before MPC 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). It is stored on the withdrawal, written to the audit log, and delivered on the withdrawal.cancelled webhook.

{
  "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

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