IDs
- Bridge resource IDs (
customerId, wallet id, loanId) are UUIDs or opaque strings — store them as-is.
- Some read responses include
externalData / engine fields (integer id, statuses like loanStatusType.active). Those reflect the underlying core-banking engine; use the Bridge IDs for your calls.
Response shapes
x-bridge returns a clean, normalized view — build against that. A few read endpoints also surface the raw core-banking engine data alongside it; treat that as internal.
Lean on items and avoid fineractItems for now (the raw core-engine data on GET /v1/wms/wallets/{walletId}/transactions). Other raw engine fields (such as a customer’s externalData) are internal too — prefer the documented clean fields.
Idempotency
Money-moving calls are idempotent on a reference you supply — reuse the same reference to safely retry:
| Endpoint | Idempotency key |
|---|
POST /v1/lms/loans/{id}/repayments | receiptNumber |
POST /v1/lms/loans/{id}/submit-payment | gatewayReference |
POST /v1/wms/wallets/{id}/submit-deposit | gatewayReference |
POST /v1/wms/wallets/{id}/reserve | reference |
POST /collection/mobile | transactionId |
Environments
Your token carries environment: "sandbox" | "production". Build against sandbox; switch by using a production key after approval. Resource IDs do not transfer between environments.
Dates
Dates are yyyy-MM-dd (e.g. 2026-03-15). Timestamps are ISO 8601.
