Skip to main content

​
At a glance

ConventionFormatExampleNotes
CurrencyISO 4217KESDefault currency for all endpoints
AmountsInteger (smallest unit)150000 = KES 1,500.00Always in cents; 100 = KES 1.00
Phone numbersE.164+254712345678Kenyan format: +2547XXXXXXXX or +2541XXXXXXXX
TimestampsISO 8601 / Unix2025-08-15T12:34:56ZSome fields use Unix milliseconds
StringsUTF-8Invoice #1234narration max 140 chars
MetadataKey-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 formatExampleAccepted
E.164 (recommended)+254712345678Yes
Without plus254712345678Yes
Local format0712345678Yes

​
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.