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

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

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-out-fulfillment",
    "amount": "3000.00",
    "phoneFrom": "+234 8123456781",
    "cashOutFulfillmentType": "cash",
    "cashOutFulfillmentID": "receipt-12345"
  }'

const axios = require('axios');

const response = await axios.post(
  'https://api.yourdomain.com/api/v1/distributors/36e48800-22ce-4ea0-b37a-198f7978cd53/operations',
  {
    operationType: 'cash-in',
    amount: '5000.00',
    phoneTo: '+234 8123456781'
  },
  {
    headers: {
      'Authorization': 'Bearer uwk_YOUR_API_KEY_HERE',
      'Content-Type': 'application/json'
    }
  }
);

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

const axios = require('axios');

const response = await axios.post(
  'https://api.yourdomain.com/api/v1/distributors/36e48800-22ce-4ea0-b37a-198f7978cd53/operations',
  {
    operationType: 'cash-in',
    amount: '25000.00',
    merchantToShortCode: '100000'
  },
  {
    headers: {
      'Authorization': 'Bearer uwk_YOUR_API_KEY_HERE',
      'Content-Type': 'application/json'
    }
  }
);

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

const axios = require('axios');

const response = await axios.post(
  'https://api.yourdomain.com/api/v1/distributors/36e48800-22ce-4ea0-b37a-198f7978cd53/operations',
  {
    operationType: 'cash-out-fulfillment',
    amount: '3000.00',
    phoneFrom: '+234 8123456781',
    cashOutFulfillmentType: 'cash',
    cashOutFulfillmentID: 'receipt-12345'
  },
  {
    headers: {
      'Authorization': 'Bearer uwk_YOUR_API_KEY_HERE',
      'Content-Type': 'application/json'
    }
  }
);

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

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

{
  "type": "/problems/input-validation-problems",
  "status": 400,
  "title": "There are some validation errors",
  "detail": "Please fix the validation issues and try again",
  "errors": [
    {
      "type": "/problems/input-validation-problems/invalid-field",
      "field": "amount",
      "detail": "Amount must be a valid decimal number"
    }
  ]
}

{
  "type": "/problems/access-forbidden",
  "status": 403,
  "title": "Access Forbidden",
  "detail": "API key does not have Perform Operations permission"
}

{
  "type": "/problems/transaction-limit-exceeded",
  "status": 403,
  "title": "Transaction Limit Exceeded",
  "detail": "This operation exceeds the maximum transaction amount allowed for this API key"
}

{
  "type": "/problems/daily-volume-exceeded",
  "status": 403,
  "title": "Daily Volume Limit Exceeded",
  "detail": "This operation would exceed the daily volume limit for this API key"
}

{
  "type": "/problems/insufficient-balance",
  "status": 403,
  "title": "Insufficient Balance",
  "detail": "Insufficient balance to complete this operation"
}

{
  "type": "/problems/input-validation-problems",
  "status": 400,
  "title": "There are some validation errors",
  "detail": "Please fix the validation issues and try again",
  "errors": [
    {
      "type": "/problems/input-validation-problems/invalid-field",
      "field": "merchantToShortCode",
      "detail": "Merchant with short code 999999 not found"
    }
  ]
}

{
  "type": "/problems/input-validation-problems",
  "status": 400,
  "title": "There are some validation errors",
  "detail": "Please fix the validation issues and try again",
  "errors": [
    {
      "type": "/problems/input-validation-problems/invalid-field",
      "field": "phoneTo",
      "detail": "Provide either phoneTo or merchantToShortCode, not both"
    }
  ]
}

POST

api

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

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

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-out-fulfillment",
    "amount": "3000.00",
    "phoneFrom": "+234 8123456781",
    "cashOutFulfillmentType": "cash",
    "cashOutFulfillmentID": "receipt-12345"
  }'

const axios = require('axios');

const response = await axios.post(
  'https://api.yourdomain.com/api/v1/distributors/36e48800-22ce-4ea0-b37a-198f7978cd53/operations',
  {
    operationType: 'cash-in',
    amount: '5000.00',
    phoneTo: '+234 8123456781'
  },
  {
    headers: {
      'Authorization': 'Bearer uwk_YOUR_API_KEY_HERE',
      'Content-Type': 'application/json'
    }
  }
);

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

const axios = require('axios');

const response = await axios.post(
  'https://api.yourdomain.com/api/v1/distributors/36e48800-22ce-4ea0-b37a-198f7978cd53/operations',
  {
    operationType: 'cash-in',
    amount: '25000.00',
    merchantToShortCode: '100000'
  },
  {
    headers: {
      'Authorization': 'Bearer uwk_YOUR_API_KEY_HERE',
      'Content-Type': 'application/json'
    }
  }
);

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

const axios = require('axios');

const response = await axios.post(
  'https://api.yourdomain.com/api/v1/distributors/36e48800-22ce-4ea0-b37a-198f7978cd53/operations',
  {
    operationType: 'cash-out-fulfillment',
    amount: '3000.00',
    phoneFrom: '+234 8123456781',
    cashOutFulfillmentType: 'cash',
    cashOutFulfillmentID: 'receipt-12345'
  },
  {
    headers: {
      'Authorization': 'Bearer uwk_YOUR_API_KEY_HERE',
      'Content-Type': 'application/json'
    }
  }
);

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

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

{
  "type": "/problems/input-validation-problems",
  "status": 400,
  "title": "There are some validation errors",
  "detail": "Please fix the validation issues and try again",
  "errors": [
    {
      "type": "/problems/input-validation-problems/invalid-field",
      "field": "amount",
      "detail": "Amount must be a valid decimal number"
    }
  ]
}

{
  "type": "/problems/access-forbidden",
  "status": 403,
  "title": "Access Forbidden",
  "detail": "API key does not have Perform Operations permission"
}

{
  "type": "/problems/transaction-limit-exceeded",
  "status": 403,
  "title": "Transaction Limit Exceeded",
  "detail": "This operation exceeds the maximum transaction amount allowed for this API key"
}

{
  "type": "/problems/daily-volume-exceeded",
  "status": 403,
  "title": "Daily Volume Limit Exceeded",
  "detail": "This operation would exceed the daily volume limit for this API key"
}

{
  "type": "/problems/insufficient-balance",
  "status": 403,
  "title": "Insufficient Balance",
  "detail": "Insufficient balance to complete this operation"
}

{
  "type": "/problems/input-validation-problems",
  "status": 400,
  "title": "There are some validation errors",
  "detail": "Please fix the validation issues and try again",
  "errors": [
    {
      "type": "/problems/input-validation-problems/invalid-field",
      "field": "merchantToShortCode",
      "detail": "Merchant with short code 999999 not found"
    }
  ]
}

{
  "type": "/problems/input-validation-problems",
  "status": 400,
  "title": "There are some validation errors",
  "detail": "Please fix the validation issues and try again",
  "errors": [
    {
      "type": "/problems/input-validation-problems/invalid-field",
      "field": "phoneTo",
      "detail": "Provide either phoneTo or merchantToShortCode, not both"
    }
  ]
}

Endpoint

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

Authentication

string

required

Bearer token with your API key. Must have Perform Operations permission.

string

required

Must be application/json

Path Parameters

string

required

The unique identifier of the distributor. Must match the distributor ID associated with the API key.

Request Body

Cash-In Operation

string

required

Must be "cash-in"

string

required

Amount to credit to the destination wallet (e.g., “5000.00”)

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.

string

Merchant’s short code number (e.g., “100000”). Required when cashing in to a merchant wallet. Cannot be used together with phoneTo.

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

string

required

Must be "cash-out-fulfillment"

string

required

Amount to debit from the user’s wallet (e.g., “3000.00”)

string

required

End user’s mobile phone number in international format (e.g., “+234 8123456781”)

string

required

Type of fulfillment. Currently only "cash" is supported.

string

required

Receipt or reference ID for the cash-out transaction

string

Optional reference note or description for the operation.

Response

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

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

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-out-fulfillment",
    "amount": "3000.00",
    "phoneFrom": "+234 8123456781",
    "cashOutFulfillmentType": "cash",
    "cashOutFulfillmentID": "receipt-12345"
  }'

const axios = require('axios');

const response = await axios.post(
  'https://api.yourdomain.com/api/v1/distributors/36e48800-22ce-4ea0-b37a-198f7978cd53/operations',
  {
    operationType: 'cash-in',
    amount: '5000.00',
    phoneTo: '+234 8123456781'
  },
  {
    headers: {
      'Authorization': 'Bearer uwk_YOUR_API_KEY_HERE',
      'Content-Type': 'application/json'
    }
  }
);

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

const axios = require('axios');

const response = await axios.post(
  'https://api.yourdomain.com/api/v1/distributors/36e48800-22ce-4ea0-b37a-198f7978cd53/operations',
  {
    operationType: 'cash-in',
    amount: '25000.00',
    merchantToShortCode: '100000'
  },
  {
    headers: {
      'Authorization': 'Bearer uwk_YOUR_API_KEY_HERE',
      'Content-Type': 'application/json'
    }
  }
);

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

const axios = require('axios');

const response = await axios.post(
  'https://api.yourdomain.com/api/v1/distributors/36e48800-22ce-4ea0-b37a-198f7978cd53/operations',
  {
    operationType: 'cash-out-fulfillment',
    amount: '3000.00',
    phoneFrom: '+234 8123456781',
    cashOutFulfillmentType: 'cash',
    cashOutFulfillmentID: 'receipt-12345'
  },
  {
    headers: {
      'Authorization': 'Bearer uwk_YOUR_API_KEY_HERE',
      'Content-Type': 'application/json'
    }
  }
);

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

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

{
  "type": "/problems/input-validation-problems",
  "status": 400,
  "title": "There are some validation errors",
  "detail": "Please fix the validation issues and try again",
  "errors": [
    {
      "type": "/problems/input-validation-problems/invalid-field",
      "field": "amount",
      "detail": "Amount must be a valid decimal number"
    }
  ]
}

{
  "type": "/problems/access-forbidden",
  "status": 403,
  "title": "Access Forbidden",
  "detail": "API key does not have Perform Operations permission"
}

{
  "type": "/problems/transaction-limit-exceeded",
  "status": 403,
  "title": "Transaction Limit Exceeded",
  "detail": "This operation exceeds the maximum transaction amount allowed for this API key"
}

{
  "type": "/problems/daily-volume-exceeded",
  "status": 403,
  "title": "Daily Volume Limit Exceeded",
  "detail": "This operation would exceed the daily volume limit for this API key"
}

{
  "type": "/problems/insufficient-balance",
  "status": 403,
  "title": "Insufficient Balance",
  "detail": "Insufficient balance to complete this operation"
}

{
  "type": "/problems/input-validation-problems",
  "status": 400,
  "title": "There are some validation errors",
  "detail": "Please fix the validation issues and try again",
  "errors": [
    {
      "type": "/problems/input-validation-problems/invalid-field",
      "field": "merchantToShortCode",
      "detail": "Merchant with short code 999999 not found"
    }
  ]
}

{
  "type": "/problems/input-validation-problems",
  "status": 400,
  "title": "There are some validation errors",
  "detail": "Please fix the validation issues and try again",
  "errors": [
    {
      "type": "/problems/input-validation-problems/invalid-field",
      "field": "phoneTo",
      "detail": "Provide either phoneTo or merchantToShortCode, not both"
    }
  ]
}

Validation Rules

The API validates the following before creating an operation:

API Key Permissions

Must have Perform Operations permission
Distributor ID must match the key’s associated distributor

Amount Validation

Must be a valid decimal number
Must be greater than 0
Cannot exceed API key’s max transaction amount (if set)

Daily Volume Limit

Sum of today’s operations + this operation cannot exceed key’s daily volume limit (if set)

Destination Validation

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

Balance Checks

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:

Operation is saved with status pending
A checker with appropriate permissions must approve it via the web interface
Once approved, the operation is executed on the blockchain
The operation status changes to completed or failed

Get Balance

Check distributor balance before creating operations

Get Operations

Query operation history and status

Distributor API

Merchant API

Endpoint

Authentication

Path Parameters

Request Body

Cash-In Operation

Cash-Out Operation

Response

Validation Rules

Maker-Checker Workflow

Get Balance

Get Operations

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Cash-In Operation

​Cash-Out Operation

​Response

​Validation Rules

​Maker-Checker Workflow

​Related Endpoints

Get Balance

Get Operations

Endpoint

Authentication

Path Parameters

Request Body

Cash-In Operation

Cash-Out Operation

Response

Validation Rules

Maker-Checker Workflow

Related Endpoints