Skip to main content

​
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

ParameterDefaultDescription
cursor(none)Pagination cursor from previous response. Omit for first page.
limit100Number of results per page (max: 1000)

​
Code Example

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

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

{
  "cashOutFulfillmentType": "cash",
  "transactionID": "TXN-12345",
  "memo": "Paid in cash at branch"
}
FieldRequiredDescription
cashOutFulfillmentTypeYes"cash" or "bank-transfer"
transactionIDNoExternal transaction or receipt reference
memoNoOptional note about the fulfillment

​
Code Example

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

{
  "operationID": "op_9c8d0e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f"
}

​
Complete Example: Poll and Process

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

Query Operations

View operation history via API

API Reference

Full API endpoint documentation