api.numeral.io) that Mambu Payments is built on. It exposes 17 collections — connected, internal and external accounts, account holders, payment orders, transactions, balances, incoming and expected payments, direct debit mandates, events, files, returns, claims, reconciliations, payment captures and payee verification requests — with native relations, server-side filters, writes on the resources the API lets you create, and a set of opt-in plugins for extra relations and payment actions.
The datasource raises rather than approximates. Where Forest asks for something the API cannot answer — a filter on a field the endpoint does not filter, an
OR, a record count — it raises an error naming the reason instead of returning unfiltered or miscounted data.Installation
Install the gemforest_admin_datasource_mambu_payments.
datasource instance: the action plugins take it as their datasource option.
Configuration
api_key is mandatory: the datasource raises a ForestAdminDatasourceMambuPayments::ConfigurationError at boot when it is missing or blank. Nothing calls the API at boot, so a wrong key starts the agent and fails on the first list.
Requests use a 5-second connection timeout and a 30-second read timeout. These values are not configurable through Datasource.new.
Provided collections
Once the datasource is registered, 17 collections are added to your Forest project. Every collection uses the resourceid as its primary key.
Lifecycle operations such as approving or canceling a payment order and verifying an external account are not collection writes: the action plugins expose them.
Relationships
The following relationships are exposed automatically:MambuConnectedAccount.transactions→MambuTransaction(origin keyconnected_account_id)MambuConnectedAccount.payment_orders→MambuPaymentOrder(origin keyconnected_account_id)MambuConnectedAccount.balances→MambuBalance(origin keyconnected_account_id)MambuAccountHolder.internal_accounts→MambuInternalAccount(origin keyaccount_holder_id)MambuAccountHolder.external_accounts→MambuExternalAccount(origin keyaccount_holder_id)MambuInternalAccount.account_holderandMambuExternalAccount.account_holder→MambuAccountHolder(foreign keyaccount_holder_id)connected_account→MambuConnectedAccount(foreign keyconnected_account_id) onMambuPaymentOrder,MambuTransaction,MambuBalance,MambuIncomingPayment,MambuExpectedPayment,MambuDirectDebitMandate,MambuReturn,MambuClaim,MambuPaymentCaptureandMambuFileinternal_account→MambuInternalAccount(foreign keyinternal_account_id) onMambuTransaction,MambuIncomingPaymentandMambuExpectedPaymentexternal_account→MambuExternalAccount(foreign keyexternal_account_id) onMambuTransaction,MambuIncomingPayment,MambuExpectedPaymentandMambuDirectDebitMandateMambuPaymentOrder.external_account→MambuExternalAccount(foreign keyreceiving_account_id, the receiving account)MambuReconciliation.transaction→MambuTransaction(foreign keytransaction_id)MambuEvent.related_object→ polymorphic (foreign keyrelated_object_id, typerelated_object_type), resolving to a payment order, transaction, incoming payment, expected payment, direct debit mandate, balance, connected account, account holder, internal account or external account
GET per distinct id, since the API has no batch lookup — and only when the projection asks for that relation.
The reverse side of several of those links (for example the payment orders of an external account, or the transactions of a payment order) is not native: the relation plugins add it.
Capabilities
Filters
Each collection only advertises, on each column, the operators its Numeral list endpoint can serve, so the UI never offers a filter that would fail. Every server-side filter supportsEQUAL and IN, and an IN sends its values as a comma-separated list.
The following rules apply to every collection:
idsupportsEQUALandINand is served by the per-record endpoint (GET /<resource>/{id}), one request per id: the list endpoints have noidfilter.- An
idcondition cannot be combined with another condition.id equal X AND <field> equal Yraises an error rather than sending a parameter the API would ignore. ORis refused. The list endpoints have no generalOR, so anORcondition raises an error instead of being sent as anAND.- The same field cannot appear twice in an
AND, since the API takes each query parameter once. - An empty
INand anEQUALon anullvalue are refused rather than turned into a filter matching every record.
Search
The Numeral API has no free-text search. Forest emulates search by building anOR over the searchable columns, which the datasource refuses, so typing in the search bar of a Mambu collection returns an error. Install the DisableSearch plugin, as in the installation snippet, to remove the search bar from every Mambu collection.
Sorting
The datasource sends no sort parameter to the API: records come back in the order the API returns them, whatever order the UI requests.Pagination
Forest’s offset/limit window is translated into Numeral’s cursor pagination (starting_after, up to 100 records per request): the datasource walks the cursor forward until it has collected the requested window. A deep page therefore costs every page before it.
A read carrying no page — what an action reads through get_records, for example — returns the first 100 records only.
Aggregations
No collection is countable. Numeral exposes no count endpoint and no total, so the record count is not displayed, and an aggregation (a chart, for example) raises an error instead of returning a figure computed over a fraction of the records.Writes
Create, update and delete are supported as the collections table states. Each write is one API request per record: an update or a delete over a selection callsPATCH or DELETE once per id.
Read-only columns and relation fields are stripped from the payload before it is sent, based on the read-only flags of the collection’s schema.
Rate limits and retries
The datasource retries a request up to 3 times on429, 502, 503 and 504, with an exponential backoff starting at 200 ms. It relies on the faraday-retry defaults for the verbs it replays, which cover idempotent requests (GET, PUT, DELETE, HEAD, OPTIONS) only: a POST (a creation, an approval) or a PATCH is never sent twice.
Errors
Every class lives under
ForestAdminDatasourceMambuPayments:: — rescue ForestAdminDatasourceMambuPayments::APIError. A record lookup answered with 404 returns no record rather than raising.
Logging
The datasource usesRails.logger when available, and falls back to Logger.new($stderr). Override it explicitly:
Plugins
Theforest_admin_datasource_mambu_payments gem also ships opt-in plugins: DisableSearch, 16 relation plugins that add the reverse and transitive links the API does not expose natively, and 10 action plugins (create and update accounts and account holders, create, approve and cancel payment orders, trigger a payee verification). See the Mambu Payments plugins page for details.
Source code
This connector is open source. Browse the code or contribute on GitHub:forest_admin_datasource_mambu_payments