Skip to main content

​
Introduction

Cash-in operations allow distributors to credit wallets in exchange for physical cash. Distributors can cash-in to two types of destinations:
  • Individual wallets — identified by the end user’s phone number
  • Merchant wallets — identified by the merchant’s short code

​
Prerequisites

  • An active API key with Perform Operations permission
  • Sufficient distributor balance to cover the cash-in amount
  • End user’s mobile phone number or merchant’s short code
Cash-in operations follow the maker-checker pattern. API requests create pending operations that require approval before execution.

​
Cash-In to Individual Wallet

Send a cash-in with the phoneTo field to credit an individual wallet.

​
Request Body

{
  "operationType": "cash-in",
  "amount": "5000.00",
  "phoneTo": "+234 8123456781"
}

​
Code Examples

curl -X POST "https://api.yourdomain.com/api/v1/distributors/36e48800-22ce-4ea0-b37a-198f7978cd53/operations" \
  -H "Authorization: Bearer uwk_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "operationType": "cash-in",
    "amount": "5000.00",
    "phoneTo": "+234 8123456781"
  }'

​
Cash-In to Merchant Wallet

Send a cash-in with the merchantToShortCode field to credit a merchant wallet. The merchant is identified by their short code (e.g., 100000).

​
Request Body

{
  "operationType": "cash-in",
  "amount": "25000.00",
  "merchantToShortCode": "100000"
}

​
Code Examples

curl -X POST "https://api.yourdomain.com/api/v1/distributors/36e48800-22ce-4ea0-b37a-198f7978cd53/operations" \
  -H "Authorization: Bearer uwk_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "operationType": "cash-in",
    "amount": "25000.00",
    "merchantToShortCode": "100000"
  }'
You must provide either phoneTo or merchantToShortCode, but not both. The API will return a validation error if both fields are provided or if neither is provided.

​
Response

​
Success Response (200 OK)

{
  "operationID": "op_8b7c9d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e"
}

​
Parameters

​
Endpoint

POST /api/v1/distributors/{distributorID}/operations

​
Request Headers

Authorization: Bearer uwk_YOUR_API_KEY_HERE
Content-Type: application/json

​
Fields

​
operationType
string
required
Type of operation. Must be "cash-in" for cash-in operations.
​
amount
string
required
Amount to credit to the destination wallet. Must be a valid decimal string (e.g., “1000.00”).
​
phoneTo
string
End user’s mobile phone number in international format (e.g., “+234 8123456781”). Required when cashing in to an individual wallet.
​
merchantToShortCode
string
Merchant’s short code number (e.g., “100000”). Required when cashing in to a merchant wallet.
​
memo
string
Optional reference note or description (e.g., “Cash deposit - Receipt #1234”).

​
Next Steps

Cash-Out via API

Learn how to process cash-out operations

API Reference

Full API endpoint documentation