Skip to main content
The Mambu Payments datasource surfaces a Mambu Payments account as Forest collections, on top of the Numeral API (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 Mambu Payments datasource is only available for Ruby (gem forest_admin_datasource_mambu_payments). There is no Node.js equivalent yet.
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 gem forest_admin_datasource_mambu_payments.
Keep a reference to the 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 resource id 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 key connected_account_id)
  • MambuConnectedAccount.payment_orders → MambuPaymentOrder (origin key connected_account_id)
  • MambuConnectedAccount.balances → MambuBalance (origin key connected_account_id)
  • MambuAccountHolder.internal_accounts → MambuInternalAccount (origin key account_holder_id)
  • MambuAccountHolder.external_accounts → MambuExternalAccount (origin key account_holder_id)
  • MambuInternalAccount.account_holder and MambuExternalAccount.account_holder → MambuAccountHolder (foreign key account_holder_id)
  • connected_account → MambuConnectedAccount (foreign key connected_account_id) on MambuPaymentOrder, MambuTransaction, MambuBalance, MambuIncomingPayment, MambuExpectedPayment, MambuDirectDebitMandate, MambuReturn, MambuClaim, MambuPaymentCapture and MambuFile
  • internal_account → MambuInternalAccount (foreign key internal_account_id) on MambuTransaction, MambuIncomingPayment and MambuExpectedPayment
  • external_account → MambuExternalAccount (foreign key external_account_id) on MambuTransaction, MambuIncomingPayment, MambuExpectedPayment and MambuDirectDebitMandate
  • MambuPaymentOrder.external_account → MambuExternalAccount (foreign key receiving_account_id, the receiving account)
  • MambuReconciliation.transaction → MambuTransaction (foreign key transaction_id)
  • MambuEvent.related_object → polymorphic (foreign key related_object_id, type related_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
On a list, the datasource reads the related records of a many-to-one relation in one pass per relation — one 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 supports EQUAL and IN, and an IN sends its values as a comma-separated list. The following rules apply to every collection:
  • id supports EQUAL and IN and is served by the per-record endpoint (GET /<resource>/{id}), one request per id: the list endpoints have no id filter.
  • An id condition cannot be combined with another condition. id equal X AND <field> equal Y raises an error rather than sending a parameter the API would ignore.
  • OR is refused. The list endpoints have no general OR, so an OR condition raises an error instead of being sent as an AND.
  • The same field cannot appear twice in an AND, since the API takes each query parameter once.
  • An empty IN and an EQUAL on a null value are refused rather than turned into a filter matching every record.
The Numeral API has no free-text search. Forest emulates search by building an OR 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 calls PATCH 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 on 429, 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 uses Rails.logger when available, and falls back to Logger.new($stderr). Override it explicitly:

Plugins

The forest_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