Internal account configuration

Internal account configuration is a set of payment rules on an internal account that automatically allows or denies payments.

How it works

Add a configuration object to an internal_account. The object has two independent sections, one for payment orders and one for incoming payments. Each section is either null or a rule set.

A rule set has a mode and one rule. The mode sets the default policy for the section. The rule is the exception to that default.

When you create a payment order or receive an incoming payment, Mambu Payments runs the internal_account_configuration validation. The validation reads the section that matches the payment's resource type and checks the payment against the rule. If the payment fails the check, payment_validation.status is failed and payment_validation.status_details is payment type denied.

For more information about payment validation, please read the dedicated guide.

Key concepts

Section. A part of configuration that applies to one resource type. The payment_order section evaluates outgoing payment orders. The incoming_payment section evaluates received payments. A null section applies no restrictions.

Mode. The default policy for a section. Set mode to allowlist or denylist.

Rule. The condition that a payment matches or does not match. Each rule can set payment_type, direction, and external_accounts. A field set to null matches any value.

Counterparty. The account on the other side of the payment. For a payment order, the counterparty is the receiving_account. For an incoming payment, the counterparty is the originating_account.

Modes

Mode	Payment matches the rule	Payment does not match the rule
`denylist`	Validation fails.	Validation passes.
`allowlist`	Validation passes.	Validation fails.

You can use a different mode in each section. For example, set payment_order to denylist and incoming_payment to allowlist on the same account.

Rule fields

A rule matches a payment when every field that is not null matches the payment.

Field	Type	Required	Description
`payment_type`	enum	Optional	The payment scheme, such as `sepa`, `sepa_instant`, `bacs`, `fps`, `chaps`, `swift`, `target2`, `us_ach`, `us_rtp`, or `us_wire`. Default: `null`, which matches all types.
`direction`	enum	Optional	`credit` or `debit`. Default: `null`, which matches both directions.
`external_accounts`	array	Optional	Up to 100 counterparty accounts. Default: `null`, which matches all counterparties.

Set at least one of payment_type, direction, or external_accounts on every rule.

Direction

The direction value is always from the point of view of the internal account.

Section	`credit`	`debit`
`payment_order`	The account holder sends money, for example a SEPA credit transfer.	The account holder collects money, for example a SEPA Direct Debit collection.
`incoming_payment`	The account receives money.	A third party takes money from the account, for example a received SEPA Direct Debit.

External accounts

Each entry in external_accounts identifies one counterparty account.

Field	Type	Required	Description
`account_number_format`	enum	Required	The format of the account number, such as `iban` or `uk_account_number`.
`account_number`	string	Required	The counterparty account number.
`bank_code_format`	enum	Optional	The format of the bank code, such as `bic` or `uk_sort_code`. Set together with `bank_code`.
`bank_code`	string	Optional	The counterparty bank code. Set together with `bank_code_format`.

An entry matches when the counterparty's account number and account number format equal the entry's values. If the entry sets a bank code, the counterparty's bank code and bank code format must also match. Comparisons are exact string matches.

If the counterparty account number is empty, a rule that sets external_accounts does not match.

Examples

Deny outgoing payments to a scheme

To block all SWIFT payment orders from an internal account, set the payment_order section to denylist with a rule for swift.

Send a POST /internal_accounts/<internal_account_id> request with the following body.

{
  "configuration": {
    "payment_order": {
      "mode": "denylist",
      "rules": [
        {
          "payment_type": "swift",
          "direction": null,
          "external_accounts": null
        }
      ]
    },
    "incoming_payment": null
  }
}

Check the response. The configuration object shows both sections.

{
  "id": "ia_01HXYZ",
  "object": "internal_account",
  "configuration": {
    "payment_order": {
      "mode": "denylist",
      "rules": [
        {
          "payment_type": "swift",
          "direction": null,
          "external_accounts": null
        }
      ]
    },
    "incoming_payment": null
  },
  "created_at": "2026-01-15T09:30:00Z"
}

Accept incoming payments from approved accounts only

To accept SEPA credit transfers only from a known counterparty, set the incoming_payment section to allowlist.

Send a POST /internal_accounts/<internal_account_id> request with the following body.

{
  "configuration": {
    "payment_order": null,
    "incoming_payment": {
      "mode": "allowlist",
      "rules": [
        {
          "payment_type": "sepa",
          "direction": "credit",
          "external_accounts": [
            {
              "account_number_format": "iban",
              "account_number": "FR7630006000011234567890189",
              "bank_code_format": "bic",
              "bank_code": "AGRIFRPP"
            }
          ]
        }
      ]
    }
  }
}

Check that the response contains the same configuration object.

Mambu Payments fails the validation for every incoming payment that does not match this rule. This includes SEPA credit transfers from other counterparties and payments that use other schemes.

Update or remove a configuration

The configuration you send replaces the whole existing configuration. Mambu Payments clears any section that you omit or set to null.

To remove all restrictions for a resource type, set its section to null. Do not send an empty rules array.

Caution: Changing mode from denylist to allowlist keeps the existing rule but reverses its meaning. Review the rule before you save the change.

Changes apply to payments created or received after you save. Mambu Payments does not re-evaluate payments that already exist.

Configure rules in the dashboard

To manage rules without the API, use the internal account pages in the dashboard.

Open the internal account.
Select Edit.
For each of Payment orders and Incoming payments, turn the section on or off.
Choose Allowlist or Denylist.
Edit the rule.
Select Save.

The form describes the default behavior of the mode you select. The dashboard asks you to confirm before you save a mode change on a section that has an existing rule.

The internal account detail page shows both sections with their mode and rule.

Limits and constraints

Configuration applies to internal accounts of type own.
Each section contains exactly one rule.
Each external_accounts array contains between one and 100 entries.
The validation does not check the internal account status. The internal_account_is_active validation handles blocked and disabled accounts.
The validation is skipped when the payment has no receiving_account_id or originating_account_id.
Mambu Payments does not check payment_type against the payment types that the connected account supports.
Mambu Payments does not block direct debit mandates when the validation fails.