Withdrawals

View your merchant withdrawal history and check the status of individual withdrawals.

List withdrawals

GET /api/v1/withdrawals

Returns a paginated list of withdrawals for the authenticated merchant.

Query parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number, starting from `1`
`per_page`	integer	`20`	Items per page, from `1` to `500`
`status`	string	—	Filter by withdrawal status: `pending`, `success`, `failed`, `cancelled`
`order`	string	`desc`	Sort by `created_at`: `desc` or `asc`

Example request

curl -X GET "https://api.ecca-ex.com/api/v1/withdrawals?page=1&per_page=10&status=success&order=desc" \
  -H "X-Api-Key: your_api_key_here"

Example response

{
  "successful": true,
  "page": 1,
  "per_page": 10,
  "total": 42,
  "total_pages": 5,
  "data": [
    {
      "withdraw_uuid": "b3f1a2c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
      "withdrawal_method_id": 1,
      "address": "TXqZ5nM3YwK8vR2pL7dFcJ6hG9bE4sA1uN",
      "address_memo": null,
      "amount": "150.00",
      "network_fee": "1.00",
      "amount_to_receive": "149.00",
      "status": "success",
      "substatus": null,
      "external_tx_id": "a1b2c3d4e5f6...",
      "created_at": "2026-02-26T14:30:00+00:00",
      "updated_at": "2026-02-26T14:35:00+00:00",
      "processed_at": "2026-02-26T14:35:00+00:00"
    }
  ]
}

Optional fields such as address_memo, substatus, external_tx_id, and processed_at can be omitted from the response when they are null.

Get withdrawal details

GET /api/v1/withdrawals/{withdraw_uuid}

Returns details of a specific withdrawal.

Path parameters

Parameter	Type	Description
`withdraw_uuid`	UUID	Withdrawal UUID returned by the API

Example request

curl -X GET https://api.ecca-ex.com/api/v1/withdrawals/b3f1a2c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c \
  -H "X-Api-Key: your_api_key_here"

Example response

{
  "successful": true,
  "data": {
    "withdraw_uuid": "b3f1a2c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
    "withdrawal_method_id": 1,
    "address": "TXqZ5nM3YwK8vR2pL7dFcJ6hG9bE4sA1uN",
    "address_memo": null,
    "amount": "150.00",
    "network_fee": "1.00",
    "amount_to_receive": "149.00",
    "status": "success",
    "substatus": null,
    "external_tx_id": "a1b2c3d4e5f6...",
    "created_at": "2026-02-26T14:30:00+00:00",
    "updated_at": "2026-02-26T14:35:00+00:00",
    "processed_at": "2026-02-26T14:35:00+00:00"
  }
}

Response fields

Field	Type	Description
`withdraw_uuid`	string	Unique withdrawal identifier (UUID)
`withdrawal_method_id`	integer	ID of the withdrawal method used
`address`	string	Destination wallet address
`address_memo`	string \| null	Optional memo or tag for networks that require it
`amount`	string	Requested withdrawal amount
`network_fee`	string	Network fee deducted from the withdrawal
`amount_to_receive`	string	Final amount sent after fee deduction
`status`	string	Top-level withdrawal status
`substatus`	string \| null	More detailed processing state, if available
`external_tx_id`	string \| null	Blockchain transaction hash after broadcast
`created_at`	string	Creation timestamp in ISO 8601 UTC
`updated_at`	string	Last update timestamp in ISO 8601 UTC
`processed_at`	string \| null	Final processing timestamp in ISO 8601 UTC

Withdrawal statuses

`status`

Status	Description
`pending`	Withdrawal was created and is waiting for processing
`success`	Withdrawal was completed successfully
`failed`	Withdrawal failed
`cancelled`	Withdrawal was cancelled

`substatus`

substatus is optional and gives more detail about the current or final state.

Known values:

Substatus	Description
`processing`	Withdrawal is currently being processed
`cancelled_by_user`	Withdrawal was cancelled by the user
`cancelled_by_admin`	Withdrawal was cancelled by an admin
`failed`	Withdrawal failed
`invalid_address`	Withdrawal failed because the address is invalid
`unknown`	Fallback value for unknown internal state

Withdrawal errors

HTTP	Code	Description
`404`	`WITHDRAWALS_NOT_FOUND`	No withdrawals were found for this merchant or the selected filter
`404`	`WITHDRAWAL_NOT_FOUND`	Withdrawal with the specified UUID was not found

Example error

{
  "successful": false,
  "request_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "error": {
    "code": "WITHDRAWAL_NOT_FOUND",
    "message": "Withdrawal not found",
    "details": {}
  }
}

Was this page helpful?

Last updated today

Built with Documentation.AI