Skip to main content
POST
/
api
/
v1
/
distributors
/
{distributorID}
/
operations
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",
    "memo": "Cash deposit - Receipt #1234"
  }'

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

​
Endpoint

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

​
Authentication

​
Authorization
string
required
Bearer token with your API key. Must have Perform Operations permission.
​
Content-Type
string
required
Must be application/json

​
Path Parameters

​
distributorID
string
required
The unique identifier of the distributor. Must match the distributor ID associated with the API key.

​
Request Body

​
Cash-In Operation

​
operationType
string
required
Must be "cash-in"
​
amount
string
required
Amount to credit to the destination wallet (e.g., “5000.00”)
​
phoneTo
string
End user’s mobile phone number in international format (e.g., “+234 8123456781”). Required when cashing in to an individual wallet. Cannot be used together with merchantToShortCode.
​
merchantToShortCode
string
Merchant’s short code number (e.g., “100000”). Required when cashing in to a merchant wallet. Cannot be used together with phoneTo.
​
memo
string
Optional reference note or description for the operation (e.g., “Receipt #1234”, “Customer deposit”).
For cash-in operations, you must provide either phoneTo (individual wallet) or merchantToShortCode (merchant wallet), but not both.

​
Cash-Out Operation

​
operationType
string
required
Must be "cash-out-fulfillment"
​
amount
string
required
Amount to debit from the user’s wallet (e.g., “3000.00”)
​
phoneFrom
string
required
End user’s mobile phone number in international format (e.g., “+234 8123456781”)
​
cashOutFulfillmentType
string
required
Type of fulfillment. Currently only "cash" is supported.
​
cashOutFulfillmentID
string
required
Receipt or reference ID for the cash-out transaction
​
memo
string
Optional reference note or description for the operation.

​
Response

​
operationID
string
Unique identifier for the created operation
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",
    "memo": "Cash deposit - Receipt #1234"
  }'

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

​
Validation Rules

The API validates the following before creating an operation:
  • Must have Perform Operations permission
  • Distributor ID must match the key’s associated distributor
  • Must be a valid decimal number
  • Must be greater than 0
  • Cannot exceed API key’s max transaction amount (if set)
  • Sum of today’s operations + this operation cannot exceed key’s daily volume limit (if set)
  • For individual wallets: phoneTo must be in international format (e.g., +234 8123456781) and belong to a registered user
  • For merchant wallets: merchantToShortCode must be a valid, existing merchant short code
  • You must provide exactly one of phoneTo or merchantToShortCode for cash-in operations
  • Cash-In: Distributor must have sufficient balance
  • Cash-Out: User must have sufficient wallet balance

​
Maker-Checker Workflow

Operations created via API follow the maker-checker approval pattern. The operation is created in a pending state and requires approval by a checker before execution.
After creating an operation:
  1. Operation is saved with status pending
  2. A checker with appropriate permissions must approve it via the web interface
  3. Once approved, the operation is executed on the blockchain
  4. The operation status changes to completed or failed

Get Balance

Check distributor balance before creating operations

Get Operations

Query operation history and status