Getting Started
  • 11 Apr 2023
  • 9 Minutes To Read
  • Dark
  • PDF

Getting Started

  • Dark
  • PDF

Article summary

Before you can start using the Payments API and the Mambu Payment Gateway (MPG) the following steps are required.

Mambu configuration

Below are some configuration steps to set up in Mambu.

1. Create API consumer and key for Payments API

All requests to the Payments API require an ApiKey header.

To generate an API key, you must create an API consumer that has the Manage Payments (MANAGE_PAYMENTS) permission . For more information, see API Consumers.

2. Create API consumer or API user for API v2

Next, you must create an API consumer or API user with appropriate details and permissions to perform withdrawal, deposit, and adjustment transactions using API v2. You will need this to integrate payments with Mambu core to execute deposit operations.

Please Note

We aim to transition to the use of API consumers as opposed to API users, therefore we recommend that you use an API consumer rather than an API user to access API v2.

Create an API consumer for API v2

If you decide to use an API consumer to access API v2 you must name it payments_integration and you must assign it all the relevant permissions. For more information, see Assign permissions for the payments API consumer or API user.

Create an API user for API v2

If you decide to create an API user for API v2, then upon creation you must provide the credentials (username and password) to the Mambu team so that they can be set up in the payments system.

For more about creating users, see Creating a User.

Please be Aware

You may not assign API access rights to a user upon creation, you must assign them when editing the user. For more information, see API Consumers - Access Rights.

Please be Aware

If you have assigned the user access rights using a predefined role, the Access Rights options will be greyed out. Make sure that API has been selected in the role configuration and that Mambu has not been selected, as this user account should not be used to interact with the Mambu UI. For more information, see Creating a User - Permissions.

Editing User dialog

Assign permissions for the payments API consumer or API user

An API consumer or user in Mambu may be assigned permissions either directly or through a role. We recommend assigning permissions through a role. This will allow you to apply the permissions to new API consumers or users, as well as to secure the transaction channel you will be using for SEPA payments against accidental use by other Mambu users. For more information, see Roles.

If you choose to assign permissions through a role, create a role with the appropriate permissions assigned to it.

Please be aware

When creating your role, you must select API under Access Rights.

If you choose to assign permissions directly, you may do so while creating or editing the API consumer or user.

For a list of permissions, see the table below.

Permission SetPermissionDetailsRequired
Deposit AccountsView Deposit Account DetailsNeeded for retrieving Mambu account and transaction details for accounts linked to a given IBAN, for example to update refunded payments with the details of the related Mambu transaction.Yes
Deposit AccountsMake DepositNeeded to create transactions in a Mambu account when a payment has been received for which the account holder is the creditor.Yes
Deposit AccountsMake WithdrawalNeeded to create transactions in a Mambu account when a payment has been received or created for which the account holder is the debtor.Yes
Deposit AccountsMake Intra-clients TransfersNeeded to process transactions where funds are being transferred between two accounts held by the same customer.Yes
Deposit AccountsMake Inter-clients TransfersNeeded to process transactions where funds are being transferred between two accounts held by customers at the same financial institution.Yes
Deposit AccountsApply Deposit Account AdjustmentsNeeded to adjust transactions in the case of recalls or reversals.Yes
Deposit AccountsBackdate Deposit TransactionsNeeded to apply the correct value date when a payment is received and the settlement date is in the past.Yes
Deposit AccountsBulk Deposit CorrectionsNeeded to apply the correct date to transactions or reverse them in certain cases.Yes
AccountingBooking Date Deposits Journal EntriesNeeded to apply the correct dates to journal entries when payments are received and the settlement date is in the past.Yes
Deposit AccountsMake Early WithdrawalsMandatory if you use fixed deposit accounts and want to allow customers to make SEPA payments from such an account before the end of the maturity period.No
HoldsCreate HoldsNeeded to create authorisation holds in a Mambu account when an instant payment has been received for which the account holder is the creditor, or when an instant payment has been received or created for which the account holder is the debtor. Required permission for instant payment processing.No
HoldsEdit Account HoldsNeeded to settle or revert authorisation holds in a Mambu account. Required permission for instant payment processing.No
HoldsView Account HoldsNeeded for retrieving authorisation holds details. Required permission for instant payment processing.No

3. Create the payment transaction channels

To initiate and receive incoming credit transfers, you must create a reserved transaction channel for each payment type, currency, and direction.

Transaction channels should be created using the pattern {BIC}-{PAYMENT-TYPE}-{SCHEME}-{CURRENCY-CODE}-{DIRECTION}. For example, for incoming SEPA credit transfers, the transaction channel ID might be FUBKDE71XXX-CT-SEPA-EUR-I.

BICYour BIC. Please note that you must use the BIC11 format, so any BIC8 codes must be padded with three X characters, for example, for an eight character BIC of NASSDE55, you should use NASSDE55XXX when creating your transaction channels.
PAYMENT_TYPEMust be either CT for credit transfers or DD for direct debits.
SCHEMEThe payment scheme supported by this transaction channel must be:
  • SEPA for SEPA payments
  • SEPA_INST for SEPA instant payments
  • ISO20022 for generic ISO payments
  • SIC for payments via the Swiss Interbank Clearing system
  • EUROSIC for Swiss Interbank Clearing system payments in Euros
  • SWIFT_MT for SWIFT payments via the European Central Bank's real-time gross settlement system
CURRENCY_CODEThe three-letter, ISO 4217 currency code. For SEPA payments, must be EUR.
DIRECTIONI for incoming payments and O for outgoing.
Please be aware

In the past, there was a different pattern for setting up transaction channels where the transaction channel ID for SEPA credit transfers was _payments_sepa and for direct debits it was _direct_debit_sepa.

Old transactions will continue to be associated to these transaction channels. However, for new transactions you must switch to the new ID naming pattern.

When switching over to the new ID naming pattern, we strongly recommend that you create entirely new transaction channels instead of renaming the existing _payments_sepa or _direct_debit_sepa transaction channels.

To create the payment transaction channel:

  1. Go to Mambu UI > Administration > Financial Setup > Transaction Channels > Add Channel.
  2. Enter a Channel name.
  3. Enter the Channel ID. See the table above for details on how the pattern that the ID should follow.
  4. Under Usage Rights, if you assigned permission directly to your Mambu API user in the previous step then select All Users. If you assigned permissions to your Mambu API user through a role then select the role you created in the previous step.
  5. Select Save Changes.



For more information about transaction channels, see Transaction Channels.

4. Create the suspense account

When using Anti-Money Laundering (AML) flows, you will need an additional deposit product and account to be configured with specific general ledger (GL) accounts so that suspended amounts are tracked accurately in accounting.

4.1 Create the Suspense GL Account

Add a new Liability GL Account from: Mambu UI > Accounting > Chart of Accounts > Add A New Account
Screenshot 2020-10-13 at 12.46.52

4.2 Create the Suspense Product

Add a new active Current Account (Deposit Product) from: Mambu UI > Administration > Products > Deposits > New Deposit Product.
The product must have the following Accounting Rules: at least one account of type Asset, one Expense and one Income. For help on creating a chart of accounts you can check out how to add Accounts to your Chart of Accounts.

4.3 Create a Suspense Account

Create a Deposit Account with the product defined at step 2.

4.4 Optional: Map to IBAN

If you need to initiate payments out of the suspense account, it will have to be mapped to an IBAN, using the External Account Representation API.

Mambu Payment Gateway Configuration

5. Register a user in Mambu Payment Gateway

To register a user, use the registration form, at

Your password must have at least eight characters and include at least one of the following: uppercase letter, lowercase letter, number, and a special character.

For more information about additional password settings, see Extra System Properties.

Once registered, contact the Mambu team to confirm and grant the user you created administrator permissions. You will only need to do this once. Afterwards, the newly created admin can add and approve other new users. For more information, see User Administration and Audit Trail.


Once your account has been created, you can proceed with the configuration of the Mambu Payment Gateway by accessing the Configuration menu.

6. Go through the system properties

The configuration menu item contains the system properties configuration which consists of various configuration sections. You should go through each configuration section and enter the relevant information in the fields. The table provides a list of the configuration sections along with a description of each, select the section title for more information about the settings in each section. For more information, see System Properties.

Configuration sectionDescription
Basic ConfigurationSpecify the BIC of your bank and the automated clearing house (ACH) as well as the ACH system.
Callout ConfigurationSpecify the settings for the system where your payment messages will be sent.
Message Processing ConfigurationConfigure settings related to processing payment messages.
Extra System PropertiesConfigure a number of parameters related to security.
Incoming Direct Debit configurationSpecify the maximum number of days to retry failed debit transactions before returning the direct debit transaction.
AML ConfigurationConfigure settings related to your AML system.
SMS ConfigurationSet up an SMS gateway for multi-factor authentication (MFA).

Along with the system properties configuration you must also set up your schedulers configuration.

7. Set incoming and outgoing schedulers configuration

Payments are processed in bulk, according to a configurable schedule. In order to configure this schedule, go to Mambu Payment Gateway UI > Configuration > Schedulers. For more information, see Schedulers.

For each channel you use (SEPA Credit Transfers, SEPA Direct Debit, SEPA Direct Debit Business to Business etc.), you will need to set up at least two schedulers for:

  1. Incoming (to receive payment information) and
  2. Outgoing (to send payment information)

To run a scheduler, select the button in the Start/Stop column.

For some channels you will also need to create additional schedulers to process retries and returns.


Please note
More than one outgoing or incoming scheduler can be configured for a given channel. However, you cannot create schedulers with overlapping schedules.

8. Optional: Configure holidays

It is possible to define holidays that will be used to enable or disable payments on certain dates, when the local clearing house is not operating. For more information, see Holidays.


Was this article helpful?


Eddy, a generative AI, facilitating knowledge discovery through conversational intelligence