Cash-In Operations via API

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

const axios = require('axios');

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

const response = await axios.post(
  `https://api.yourdomain.com/api/v1/distributors/${distributorID}/operations`,
  {
    operationType: 'cash-in',
    amount: '5000.00',
    phoneTo: '+234 8123456781'
  },
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    }
  }
);

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

import requests

distributor_id = '36e48800-22ce-4ea0-b37a-198f7978cd53'
api_key = 'uwk_YOUR_API_KEY_HERE'

response = requests.post(
    f'https://api.yourdomain.com/api/v1/distributors/{distributor_id}/operations',
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    },
    json={
        'operationType': 'cash-in',
        'amount': '5000.00',
        'phoneTo': '+234 8123456781'
    }
)

print('Operation ID:', response.json()['operationID'])

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

const axios = require('axios');

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

const response = await axios.post(
  `https://api.yourdomain.com/api/v1/distributors/${distributorID}/operations`,
  {
    operationType: 'cash-in',
    amount: '25000.00',
    merchantToShortCode: '100000'
  },
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    }
  }
);

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

import requests

distributor_id = '36e48800-22ce-4ea0-b37a-198f7978cd53'
api_key = 'uwk_YOUR_API_KEY_HERE'

response = requests.post(
    f'https://api.yourdomain.com/api/v1/distributors/{distributor_id}/operations',
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    },
    json={
        'operationType': 'cash-in',
        'amount': '25000.00',
        'merchantToShortCode': '100000'
    }
)

print('Operation ID:', response.json()['operationID'])

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

string

required

Type of operation. Must be "cash-in" for cash-in operations.

string

required

Amount to credit to the destination wallet. Must be a valid decimal string (e.g., “1000.00”).

string

End user’s mobile phone number in international format (e.g., “+234 8123456781”). Required when cashing in to an individual wallet.

string

Merchant’s short code number (e.g., “100000”). Required when cashing in to a merchant wallet.

string

Optional reference note or description (e.g., “Cash deposit - Receipt #1234”).

Overview

API Tutorials

Introduction

Prerequisites

Cash-In to Individual Wallet

Request Body

Code Examples

Cash-In to Merchant Wallet

Request Body

Code Examples

Response

Success Response (200 OK)

Parameters

Endpoint

Request Headers

Fields

Next Steps

Cash-Out via API

API Reference

​Introduction

​Prerequisites

​Cash-In to Individual Wallet

​Request Body

​Code Examples

​Cash-In to Merchant Wallet

​Request Body

​Code Examples

​Response

​Success Response (200 OK)

​Parameters

​Endpoint

​Request Headers

​Fields

​Next Steps

Cash-Out via API

API Reference

Introduction

Prerequisites

Cash-In to Individual Wallet

Request Body

Code Examples

Cash-In to Merchant Wallet

Request Body

Code Examples

Response

Success Response (200 OK)

Parameters

Endpoint

Request Headers

Fields

Next Steps