> ## Documentation Index
> Fetch the complete documentation index at: https://docs.forest.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Mambu Payments plugins

> Add reverse relations, disable search and expose payment operations as actions on top of the Mambu Payments datasource

The Mambu Payments connector ships three families of plugins on top of the [Mambu Payments datasource](https://docs.forest.app/get-started/connect/data-sources/mambu-payments.md): `DisableSearch`, relation plugins that add the links the Numeral API does not expose natively, and action plugins that expose payment operations (create, approve, cancel, verify) as actions.

> [!WARNING]
>
> The Mambu Payments connector is only available for Ruby (gem `forest_admin_datasource_mambu_payments`).

Nothing is registered automatically: opt each plugin in. `DisableSearch` and the relation plugins install **at the datasource level** (`@create_agent.use`), and raise an `ArgumentError` when installed on a single collection. The action plugins install **at the collection level** (`collection.use`) and take the registered `Datasource` instance as their `datasource` option.

```ruby theme={null}
# app/lib/forest_admin_rails/create_agent.rb
mambu = ForestAdminDatasourceMambuPayments::Datasource.new(api_key: ENV['MAMBU_PAYMENTS_API_KEY'])
@create_agent = ForestAdminAgent::Builder::AgentFactory.instance.add_datasource(mambu, {})

plugins = ForestAdminDatasourceMambuPayments::Plugins

# Datasource level
@create_agent.use(plugins::DisableSearch, {})
@create_agent.use(plugins::Relations::LinkExternalAccountToPaymentOrders, {})
@create_agent.use(plugins::Relations::LinkPaymentOrderToTransactions, {})

# Collection level
@create_agent.customize_collection('MambuPaymentOrder') do |collection|
  collection.use(plugins::SmartActions::ApprovePaymentOrder, { datasource: mambu, record_id_field: 'id' })
  collection.use(plugins::SmartActions::CancelPaymentOrder, { datasource: mambu, record_id_field: 'id' })
end
```

## Disable search

`ForestAdminDatasourceMambuPayments::Plugins::DisableSearch` removes the search bar from all 17 Mambu collections. The Numeral API has no free-text search, and the `OR` condition Forest builds to emulate one is refused by the datasource, so without this plugin a search returns an error.

```ruby theme={null}
@create_agent.use(ForestAdminDatasourceMambuPayments::Plugins::DisableSearch, {})
```

## Relation plugins

Every relation plugin lives under `ForestAdminDatasourceMambuPayments::Plugins::Relations` and takes no option: `@create_agent.use(<plugin>, {})`. Install only the links you need — each one adds API calls when the relation is displayed.

### Direct links

The target collection already carries the foreign key, so these plugins only declare the one-to-many relation on the host.

| Plugin | Adds |
| - | - |
| `LinkExternalAccountToPaymentOrders` | `MambuExternalAccount.payment_orders` (origin key `receiving_account_id`) |
| `LinkExternalAccountToIncomingPayments` | `MambuExternalAccount.incoming_payments` (origin key `external_account_id`) |
| `LinkExternalAccountToDirectDebitMandates` | `MambuExternalAccount.direct_debit_mandates` (origin key `external_account_id`) |
| `LinkInternalAccountToIncomingPayments` | `MambuInternalAccount.incoming_payments` (origin key `internal_account_id`) |
| `LinkPaymentOrderToEvents` | `MambuPaymentOrder.events` (origin key `MambuEvent.related_object_id`) |
| `LinkPaymentOrderToReturns` | `MambuPaymentOrder.returns` (origin key `MambuReturn.related_payment_id`) |
| `LinkIncomingPaymentToEvents` | `MambuIncomingPayment.events` (origin key `MambuEvent.related_object_id`) |
| `LinkIncomingPaymentToReturns` | `MambuIncomingPayment.returns` (origin key `MambuReturn.related_payment_id`) |

### Account holder links

An account holder is reached through an account. These plugins import `account_holder_id` from the related account (read-only), add a many-to-one to `MambuAccountHolder` on the host, and add the reverse one-to-many on `MambuAccountHolder`. A filter on the holder is resolved by listing the intermediate accounts of that holder first.

| Plugin | Adds on the host | Adds on `MambuAccountHolder` | Through |
| - | - | - | - |
| `LinkAccountHolderToIncomingPayments` | `MambuIncomingPayment.account_holder` | `incoming_payments` | the internal account |
| `LinkAccountHolderToDirectDebitMandates` | `MambuDirectDebitMandate.account_holder` | `direct_debit_mandates` | the external account |
| `LinkPaymentOrderToReceivingAccountHolder` | `MambuPaymentOrder.receiving_account_holder` | `payment_orders` | the receiving external account |

### Links resolved through an intermediate collection

The target collection has no foreign key to the host at all. These plugins add a virtual foreign key column on the target — always empty on a record, filterable with `EQUAL` and `IN` only — and the one-to-many on the host. Opening the relation lists the intermediate collection first, then filters the target on the ids it found.

| Plugin | Adds | Resolved through |
| - | - | - |
| `LinkPaymentOrderToTransactions` | `MambuPaymentOrder.transactions` | `MambuReconciliation` (reconciliations of the payment order) |
| `LinkIncomingPaymentToTransactions` | `MambuIncomingPayment.transactions` | `MambuReconciliation` (reconciliations of the incoming payment) |
| `LinkIncomingPaymentToExpectedPayments` | `MambuIncomingPayment.matched_expected_payments` | `MambuReconciliation`, twice: the transactions reconciled with the incoming payment, then the expected payments reconciled with those transactions |
| `LinkInternalAccountToBalances` | `MambuInternalAccount.balances` | the internal account's `connected_account_ids` |
| `LinkInternalAccountToPaymentOrders` | `MambuInternalAccount.payment_orders` | the internal account's `connected_account_ids` |

> [!NOTE]
>
> `LinkInternalAccountToBalances` and `LinkInternalAccountToPaymentOrders` resolve through the connected accounts: they list every balance or payment order of the connected accounts the internal account belongs to, not only the ones tied to that internal account.

A resolution reads at most 10,000 intermediate records and logs a warning when it reaches that cap.

## Action plugins

Every action plugin lives under `ForestAdminDatasourceMambuPayments::Plugins::SmartActions`, installs on any collection with `collection.use`, and requires the `datasource` option. The host collection does not need to be a Mambu collection: an action plugin reads the Mambu id from the column you name in `record_id_field`, so a collection of your own database that stores a Mambu id works as well as the Mambu collection itself.

| Option | Applies to | Description |
| - | - | - |
| `datasource` | all | **Required.** The `ForestAdminDatasourceMambuPayments::Datasource` instance. |
| `record_id_field` | update, approve, cancel, verify | **Required.** Column of the host collection holding the Mambu id to act on — `'id'` on the Mambu collection itself. |
| `action_name` | create, update | Overrides the action label. |
| `result_field` | create | Writable column of the host record that receives the id of the created resource. Best-effort: a failed write-back is logged and reported in the success message, without rolling back the creation. |
| `scopes` | approve, cancel, verify | `[:single]`, `[:bulk]` or both (default). Registers one action per scope. |

### Create actions

`Single`-scope actions that create a resource from the values of their form.

| Plugin | Default label | Form fields (all required) |
| - | - | - |
| `CreateAccountHolder` | `Create Mambu account holder` | Name |
| `CreateInternalAccount` | `Create Mambu internal account` | Type (`own` or `virtual`), Name, Holder name, Account number |
| `CreateExternalAccount` | `Create Mambu external account` | Holder name, Account number, Bank code (BIC, UK sort code, US routing number or local equivalent) |
| `CreatePaymentOrder` | `Create Mambu payment order` | Type (for example `sepa_credit_transfer`), Direction (`credit` or `debit`), Amount (integer, in the currency's smallest unit), Currency (ISO 4217), Reference, Connected account id |

```ruby theme={null}
@create_agent.customize_collection('Customer') do |collection|
  collection.use(
    ForestAdminDatasourceMambuPayments::Plugins::SmartActions::CreateAccountHolder,
    { datasource: mambu, result_field: 'mambu_account_holder_id' }
  )
end
```

### Update actions

`Single`-scope actions that update the resource whose id is in `record_id_field`. Every form field is optional: an empty field keeps the current value, and an empty form is refused.

| Plugin | Default label | Form fields |
| - | - | - |
| `UpdateAccountHolder` | `Update Mambu account holder` | Name |
| `UpdateInternalAccount` | `Update Mambu internal account` | Name, Holder name, Account number |
| `UpdateExternalAccount` | `Update Mambu external account` | Holder name, Account number, Bank code |

### Payment order and verification actions

These actions act on every selected record and call the API once per id. A failure on one id does not stop the others: the success message counts the records processed and lists the ids that failed (the failure details go to the log). The action reports an error only when every id failed, and that error carries the API's message for the first failure.

| Plugin | Labels (single / bulk) | Behavior |
| - | - | - |
| `ApprovePaymentOrder` | `Approve Mambu payment order` / `Approve selected Mambu payment orders` | Calls `POST /payment_orders/{id}/approve`. The API only approves orders in status `pending_approval`. |
| `CancelPaymentOrder` | `Cancel Mambu payment order` / `Cancel selected Mambu payment orders` | Calls `POST /payment_orders/{id}/cancel`. Optional form field: Reason, a reason code used for SEPA direct debits only. |
| `TriggerPayeeVerification` | `Trigger payee verification` / `Trigger payee verification on selected accounts` | Calls `POST /external_accounts/{id}/verify`. The verification is asynchronous: the account moves to `pending_verification` and the result arrives later through Mambu Payments. |

```ruby theme={null}
@create_agent.customize_collection('MambuExternalAccount') do |collection|
  collection.use(
    ForestAdminDatasourceMambuPayments::Plugins::SmartActions::TriggerPayeeVerification,
    { datasource: mambu, record_id_field: 'id', scopes: [:single] }
  )
end
```

Update actions follow the same per-id behavior. A create action makes a single call: when the API rejects it, the action fails with the API's own error message.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.