Overview
Metadata is a developer-controlled extension field available on most API objects. It allows you to attach custom key-value pairs that Monime will store and return with the object, without interpreting them. This feature is designed to help you bridge the gap between Monime’s standard fields (like id, status, or amount) and the real-world business context your systems require for reconciliation, reporting, or debugging. When you create a payment code, payout, or checkout session in Monime, the API provides all the financial attributes needed for processing. But businesses, depending on their domain, may often ask questions such as:- Which order at the shop or restaurant does this payment code belong to?
- Which branch, kiosk, or agent in Waterloo or Kenema initiated this payout?
- Which campaign or promotion should this checkout session be tied to?
- Which customer from my database should I link this Monime object back to?
How it Works
Flat Structure Only
- Metadata is always flat keys map directly to values.
- Nested JSON
{"billingAddress": {"Chiefdom": "Nongowa"}}and arrays are not supported. - If you need hierarchy, encode it into the key itself (e.g., billing_address_chiefdom).
Partial Update Support
Metadata updates in Monime are incremental. You don’t need to resend the full set every time. Instead:- Omit a key → its value will remain unchanged.
- Send a key with a value → it will be created or updated.
- Send a key with null or "" (empty string) → the key will be removed if present.
Limitations
Metadata is powerful, but it has deliberate limitations to ensure Monime stays consistent, performant, and secure.| Limitation | Rule |
|---|---|
| Max pairs | 64 key-value entries per object |
| Max key length | 64 characters |
| Max value length | 100 characters |
| Allowed key characters | [a-zA-Z0-9_-] |
| Reserved prefix | Keys cannot begin with _, - or "monime" (case-insensitive) |
| Value length | Must be a string ≤ 100 chars; null or "" deletes the key |
| Nesting | Not supported; metadata is always flat |
If your request includes invalid metadata (e.g., key too long, invalid characters, or too many pairs),
the request will be rejected with the appropriate message
Use Cases
- Reconciliation:
Add your
order_idorinvoice_noto payments and payouts, so your finance system can line up with Monime. - Operational tags:
Tag payments by branch, e.g.
"branch": "Kenema-Kiosk-1234", or campaigns like"fund_raising_ref": "save-life-1234". - Flexible extensions:
Quickly add flags like
"priority": "high"or"batch": "salary-August"without waiting for schema changes.
Metadata is opaque to Monime. It has no semantic meaning to us. The only
enforcement done on them is on the limitations (key length, value length, allowed characters).
Best Practice
- Use Predictable Keys:
Define a clear convention (
order_id,customer_ref,kiosk,osusu_id). This makes reconciliation easier across systems. - Keep Values Concise: Values are capped at 100 characters. Use them for IDs, short tags, or labels, not descriptions or logs.
- Avoid Sensitive Data: Metadata is returned in API responses. Never store credentials, personal private data, or secrets here.
- Treat Metadata as Context, Not State: Use metadata for annotations and reconciliation. Do not rely on it as your system of record.
- Clean Up Over Time:
Remove keys with
nullor""when they’re no longer needed to keep your objects lean. - Flat-Only Design: If you need to represent hierarchy, encode it into the key name (contact_phone_number, contact_email_address).
- Leverage Metadata for Reconciliation:
Always attach your own IDs (
order_id,invoice_no) so Monime objects can be directly matched to your internal records without external tables.