Cash-Out Operations via 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

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

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

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`);
  }
}

Introduction

Prerequisites

Step 1: List Pending Cash-Outs

Endpoint

Query Parameters

Code Example

Response

Step 2: Process a Cash-Out

Endpoint

Request Body

Code Example

Response

Complete Example: Poll and Process

Next Steps

Query Operations

API Reference

Documentation Index

​Introduction

​Prerequisites

​Step 1: List Pending Cash-Outs

​Endpoint

​Query Parameters

​Code Example

​Response

​Step 2: Process a Cash-Out

​Endpoint

​Request Body

​Code Example

​Response

​Complete Example: Poll and Process

​Next Steps

Query Operations

API Reference

Introduction

Prerequisites

Step 1: List Pending Cash-Outs

Endpoint

Query Parameters

Code Example

Response

Step 2: Process a Cash-Out

Endpoint

Request Body

Code Example

Response

Complete Example: Poll and Process

Next Steps