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

# Cash-Out Operations via API

> Learn how to list pending cash-out requests and process them using the Distributor API

## Introduction

When a customer requests a cash withdrawal from their wallet, the request appears as a pending cash-out operation assigned to your distributor. You can list these pending requests and mark them as processed once you've provided the funds.

## Prerequisites

* An active API key with **Read Transactions** permission (to list) and **Perform Operations** permission (to process)

## Step 1: List Pending Cash-Outs

### Endpoint

```
GET /api/v1/distributors/{distributorID}/cashouts
```

### Query Parameters

| Parameter | Default  | Description                                                    |
| --------- | -------- | -------------------------------------------------------------- |
| `cursor`  | *(none)* | Pagination cursor from previous response. Omit for first page. |
| `limit`   | 100      | Number of results per page (max: 1000)                         |

### Code Example

```javascript theme={null}
const axios = require('axios');

const distributorID = '36e48800-22ce-4ea0-b37a-198f7978cd53';
const apiKey = 'uwk_YOUR_API_KEY_HERE';

async function listPendingCashOuts(cursor = '') {
  const params = { limit: 100 };
  if (cursor) params.cursor = cursor;

  const response = await axios.get(
    `https://api.yourdomain.com/api/v1/distributors/${distributorID}/cashouts`,
    {
      params,
      headers: { 'Authorization': `Bearer ${apiKey}` }
    }
  );

  console.log(`Found ${response.data.items.length} pending cash-outs`);
  for (const item of response.data.items) {
    console.log(`  ${item.operationID}: ${item.amount} from ${item.from}`);
  }

  // Paginate if there are more results
  if (response.data.nextCursor) {
    await listPendingCashOuts(response.data.nextCursor);
  }
}
```

### Response

```json theme={null}
{
  "items": [
    {
      "cursor": "MjAyNi0wMy0yOVQxMDowMDowMFp8b3AtMTIz",
      "operationID": "op-123",
      "type": "cash-out",
      "from": "+234 8123456781",
      "amount": "3000.00",
      "memo": "ATM withdrawal",
      "createdAt": "2026-03-29T10:00:00Z"
    }
  ],
  "nextCursor": "",
  "limit": 100
}
```

## Step 2: Process a Cash-Out

Once you've verified the customer and provided the funds, mark the operation as processed.

### Endpoint

```
PUT /api/v1/distributors/{distributorID}/cashouts/{operationID}/process
```

### Request Body

```json theme={null}
{
  "cashOutFulfillmentType": "cash",
  "transactionID": "TXN-12345",
  "memo": "Paid in cash at branch"
}
```

| Field                    | Required | Description                               |
| ------------------------ | -------- | ----------------------------------------- |
| `cashOutFulfillmentType` | Yes      | `"cash"` or `"bank-transfer"`             |
| `transactionID`          | No       | External transaction or receipt reference |
| `memo`                   | No       | Optional note about the fulfillment       |

### Code Example

```javascript theme={null}
async function processCashOut(operationID) {
  const response = await axios.put(
    `https://api.yourdomain.com/api/v1/distributors/${distributorID}/cashouts/${operationID}/process`,
    {
      cashOutFulfillmentType: 'cash',
      transactionID: 'RECEIPT-001',
      memo: 'Cash withdrawal fulfilled at main branch'
    },
    {
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      }
    }
  );

  console.log('Fulfillment Operation ID:', response.data.operationID);
}
```

### Response

```json theme={null}
{
  "operationID": "op_9c8d0e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f"
}
```

## Complete Example: Poll and Process

```javascript theme={null}
async function pollAndProcess() {
  const { data } = await axios.get(
    `https://api.yourdomain.com/api/v1/distributors/${distributorID}/cashouts`,
    { headers: { 'Authorization': `Bearer ${apiKey}` } }
  );

  for (const cashout of data.items) {
    console.log(`Processing ${cashout.operationID}: ${cashout.amount} from ${cashout.from}`);

    await axios.put(
      `https://api.yourdomain.com/api/v1/distributors/${distributorID}/cashouts/${cashout.operationID}/process`,
      { cashOutFulfillmentType: 'cash' },
      {
        headers: {
          'Authorization': `Bearer ${apiKey}`,
          'Content-Type': 'application/json'
        }
      }
    );

    console.log(`  Processed successfully`);
  }
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Query Operations" icon="list" href="/api-reference/distributors/operations">
    View operation history via API
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/distributors/authentication">
    Full API endpoint documentation
  </Card>
</CardGroup>