Account types
The service supports two account types, controlled by theaccount_type field:
bank — a traditional bank account. The bank_details object holds the provider-specific fields (account number, bank code, account name, etc.).
momo — a mobile money wallet. The momo_details object is required for this type and holds the network and phone number.
Beneficiary types
beneficiary_type | Description |
|---|---|
payout_recipient | Default. Used for standard cross-border payouts. |
loan_client | Used by lending integrations (e.g. Sycamore) for loan disbursements. May carry additional loan_client_details metadata. |
Country–currency validation
When creating a beneficiary,currency is validated against country. The mapping is:
| Country | Allowed currency |
|---|---|
NG | NGN |
GH | GHS |
GB | GBP or EUR |
KE | KES |
US | USD |
ZA | ZAR |
AE | AED |
RW | RWF |
| Euro-zone (DE, FR, NL, ES, IT, BE, AT, IE, PT) | EUR |
Ownership and auth
All beneficiary endpoints require a Bearer token. TheX-User-Id request header identifies the calling user and is used both for ownership checks (on reads, updates, and deletes) and to automatically populate the beneficiary_of field on creation.
The /beneficiaries/all and /beneficiaries/loan-clients/{org_id} endpoints are admin-only — they require internal-admin or org-admin roles respectively.
Pagination
User-scoped list endpoints (GET /beneficiaries) and the admin list (GET /beneficiaries/all) both use DynamoDB cursor pagination. Pass the last_evaluated_key from one response as a query parameter in the next request. The GET /beneficiaries/all endpoint also accepts a page number parameter, but cursor-based pagination is preferred for performance.
The org-level list (GET /beneficiaries/loan-clients/{org_id}) uses a next_token parameter (a JSON-encoded DynamoDB key).