> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fingopay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Data conventions

> Standard formats for amounts, currencies, phone numbers, timestamps, and metadata

## 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).

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

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

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

## 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

```json theme={"dark"}
{
  "metadata": {
    "orderId": "ORD-987",
    "customerId": "cust_abc123",
    "source": "checkout_v2"
  }
}
```

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

## Sub-merchant details in metadata

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

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

Supported `riskLevel` values are:

* `low`
* `medium`
* `high`

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