> ## Documentation Index
> Fetch the complete documentation index at: https://docs-openpay.nipuntheekshana.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Withdrawal Management

> Review, approve, reject, and complete merchant withdrawal requests

## List All Withdrawals

<ParamField query="page" type="integer" default="1">
  Page number for pagination.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Items per page (max 100).
</ParamField>

<ParamField query="status" type="string">
  Filter by withdrawal status. One of `pending`, `approved`, `rejected`, `processing`, `completed`, `failed`.
</ParamField>

<ParamField query="merchantId" type="string">
  Filter withdrawals by a specific merchant.
</ParamField>

<ParamField query="fromDate" type="string">
  Filter withdrawals created on or after this date (ISO 8601).
</ParamField>

<ParamField query="toDate" type="string">
  Filter withdrawals created on or before this date (ISO 8601).
</ParamField>

### Example Request

```bash theme={null}
curl -X GET "https://olp-api.nipuntheekshana.com/v1/admin/withdrawals?status=pending&page=1&limit=10" \
  -H "Authorization: Bearer <admin_token>"
```

### Example Response (200)

```json theme={null}
{
  "data": [
    {
      "id": "wd_xyz789",
      "merchantId": "merch_abc123",
      "merchantName": "Acme Payments Ltd",
      "amount": "500.00",
      "currency": "USDT",
      "destinationAddress": "0xabcd...1234",
      "network": "BSC",
      "status": "pending",
      "requestedAt": "2026-03-25T12:00:00Z",
      "updatedAt": "2026-03-25T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 8,
    "totalPages": 1
  }
}
```

***

## Get Withdrawal Details

<ParamField path="id" type="string" required>
  The unique withdrawal identifier.
</ParamField>

### Example Request

```bash theme={null}
curl -X GET "https://olp-api.nipuntheekshana.com/v1/admin/withdrawals/wd_xyz789" \
  -H "Authorization: Bearer <admin_token>"
```

### Example Response (200)

```json theme={null}
{
  "id": "wd_xyz789",
  "merchantId": "merch_abc123",
  "merchantName": "Acme Payments Ltd",
  "amount": "500.00",
  "fee": "2.50",
  "netAmount": "497.50",
  "currency": "USDT",
  "destinationAddress": "0xabcd...1234",
  "network": "BSC",
  "status": "pending",
  "txHash": null,
  "requestedAt": "2026-03-25T12:00:00Z",
  "reviewedAt": null,
  "completedAt": null,
  "reviewedBy": null,
  "notes": null
}
```

***

## Approve Withdrawal

Approve a pending withdrawal request for processing.

<ParamField path="id" type="string" required>
  The unique withdrawal identifier.
</ParamField>

<ParamField body="notes" type="string">
  Optional internal notes for the approval.
</ParamField>

### Example Request

```bash theme={null}
curl -X POST "https://olp-api.nipuntheekshana.com/v1/admin/withdrawals/wd_xyz789/approve" \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{"notes": "Verified merchant identity and destination address"}'
```

### Example Response (200)

```json theme={null}
{
  "id": "wd_xyz789",
  "status": "approved",
  "reviewedBy": "admin_user_001",
  "reviewedAt": "2026-03-26T09:15:00Z",
  "message": "Withdrawal approved successfully"
}
```

***

## Reject Withdrawal

Reject a pending withdrawal request. The funds are returned to the merchant's balance.

<ParamField path="id" type="string" required>
  The unique withdrawal identifier.
</ParamField>

<ParamField body="reason" type="string" required>
  The reason for rejecting the withdrawal.
</ParamField>

### Example Request

```bash theme={null}
curl -X POST "https://olp-api.nipuntheekshana.com/v1/admin/withdrawals/wd_xyz789/reject" \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Destination address does not match verified wallet"}'
```

### Example Response (200)

```json theme={null}
{
  "id": "wd_xyz789",
  "status": "rejected",
  "reviewedBy": "admin_user_001",
  "reviewedAt": "2026-03-26T09:20:00Z",
  "message": "Withdrawal rejected successfully"
}
```

***

## Mark Withdrawal as Completed

Mark an approved withdrawal as completed after the on-chain transfer has been confirmed.

<ParamField path="id" type="string" required>
  The unique withdrawal identifier.
</ParamField>

<ParamField body="txHash" type="string" required>
  The blockchain transaction hash confirming the transfer.
</ParamField>

<ParamField body="notes" type="string">
  Optional internal notes.
</ParamField>

### Example Request

```bash theme={null}
curl -X POST "https://olp-api.nipuntheekshana.com/v1/admin/withdrawals/wd_xyz789/complete" \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "txHash": "0x9f8e7d6c5b4a3210fedcba9876543210abcdef01234567890abcdef012345678",
    "notes": "Confirmed on BscScan"
  }'
```

### Example Response (200)

```json theme={null}
{
  "id": "wd_xyz789",
  "status": "completed",
  "txHash": "0x9f8e7d6c5b4a3210fedcba9876543210abcdef01234567890abcdef012345678",
  "completedAt": "2026-03-26T10:00:00Z",
  "message": "Withdrawal marked as completed"
}
```

### Error Responses

```json 404 Not Found theme={null}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Withdrawal not found"
  }
}
```

```json 409 Conflict theme={null}
{
  "error": {
    "code": "CONFLICT",
    "message": "Withdrawal is not in a valid state for this action"
  }
}
```