Data conventions

At a glance

Convention	Format	Example	Notes
Currency	ISO 4217	`KES`	Default currency for all endpoints
Amounts	Integer (smallest unit)	`150000` = KES 1,500.00	Always in cents; `100` = KES 1.00
Phone numbers	E.164	`+254712345678`	Kenyan format: `+2547XXXXXXXX` or `+2541XXXXXXXX`
Timestamps	ISO 8601 / Unix	`2025-08-15T12:34:56Z`	Some fields use Unix milliseconds
Strings	UTF-8	`Invoice #1234`	`narration` max 140 chars
Metadata	Key-value object	`{"orderId": "ORD-987"}`	Up to 20 keys, 500 chars per value

Amounts

All monetary amounts are integers in the smallest currency unit (cents for KES).

To convert a human-readable amount to the API format, multiply by 100. For example, KES 1,500.00 becomes 150000.

KES   10.00  →    1000
KES  150.00  →   15000
KES 1500.00  → 150000

For M-Pesa C2B charges, amounts must be divisible by 100 (whole KES). Fractional amounts are rejected.

Phone numbers

Phone numbers must be valid Kenyan MSISDNs. The API accepts multiple formats and normalizes internally:

Input format	Example	Accepted
E.164 (recommended)	`+254712345678`	Yes
Without plus	`254712345678`	Yes
Local format	`0712345678`	Yes

Metadata

The metadata field is an optional object of string key-value pairs you can attach to any transaction.

Max keys: 20
Key format: 1-64 characters (letters, numbers, ., _, -)
Value max length: 500 characters

{
  "metadata": {
    "orderId": "ORD-987",
    "customerId": "cust_abc123",
    "source": "checkout_v2"
  }
}

Metadata is returned unchanged in webhook payloads and transaction queries. Use it for reconciliation, tagging, or passing context through the payment lifecycle.

Sub-merchant details in metadata

For enterprise aggregator flows, you can include structured sub-merchant details using the reserved metadata key subMerchantDetails.

{
  "subMerchantId": "SM-NAIROBI-001",
  "metadata": {
    "subMerchantDetails": {
      "name": "Nairobi West Branch",
      "legalName": "Nairobi West Branch Limited",
      "riskLevel": "medium"
    }
  }
}

Supported riskLevel values are:

low
medium
high

If subMerchantId does not already exist for your organization, we auto-create it in active state and apply metadata.subMerchantDetails when provided.

Getting Started

Core Concepts

Release Notes

At a glance

Amounts

Phone numbers

Metadata

Sub-merchant details in metadata

​At a glance

​Amounts

​Phone numbers

​Metadata

​Sub-merchant details in metadata

At a glance

Amounts

Phone numbers

Metadata

Sub-merchant details in metadata