Getting Started
  • 17 Nov 2022
  • 13 Minutes To Read
  • Dark
  • PDF

Getting Started

  • Dark
  • PDF

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

Mambu Configuration:

  1. Create API consumer & generate key
  2. Create Mambu API user
  3. Create the payments transaction channels
  4. Create the Suspense Account (optional)

Mambu Payment Gateway Configuration

  1. Mambu Payment Gateway first user registration
  2. BIC configuration
  3. Webhook configuration
  4. Set up anti-money laundering (AML)
  5. Schedulers configuration
  6. Enable SMS Gateway for multi-factor authentication (optional)
  7. Configure holidays (optional)
  8. Create additional Mambu Payment Gateway users (recommended)

Mambu configuration

Create API consumer and key

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 steps on how to create an API consumer, see Creating API consumers and for more general information about API consumers, see API Consumers.

For more information on generating API keys, see Generating API keys.

Mambu API user

Next, you must create a Mambu API user with appropriate permissions and access rights. This user account is used to perform withdrawal, deposit, and adjustment transactions. For more information, see Creating a User.

Permissions for payments API user

You may assign permissions either directly to the user when creating or editing the user. Or you may create a role with the appropriate permissions assigned and then assign the role to the user.

We recommend assigning permissions through a role. This will allow you to apply the permissions to new API 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. For a list of permissions, see the table below.

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 user in the following step.

Permission Set Permission Required Details
Deposit Accounts View Deposit Account Details Needed 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 transcaction.
Deposit Accounts Make Deposit Needed to create transactions in a Mambu account when a payment has been received for which the account holder is the creditor.
Deposit Accounts Make Withdrawal Needed to create transactions in a Mambu account when a payment has been received or created for which the account holder is the debtor.
Deposit Accounts Make Intra-clients Transfers Needed to process transactions where funds are being transferred between two accounts held by the same customer.
Deposit Accounts Make Inter-clients Transfers Needed to process transactions where funds are being transferred between two accounts held by customers at the same financial institution.
Deposit Accounts Apply Deposit Account Adjustments Needed to adjust transactions in the case of recalls or reversals.
Deposit Accounts Backdate Deposit Transactions Needed to apply the correct value date when a payment is received and the settlement date is in the past.
Deposit Accounts Bulk Deposit Corrections Needed to apply the correct date to transactions or reverse them in certain cases.
Accounting Booking Date Deposits Journal Entries Needed to apply the correct dates to journal entries when payments are received and the settlement date is in the past.
Deposit Accounts Make Early Withdrawals Mandatory 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.
Holds Create Holds Needed 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.
Holds Edit Account Holds Needed to settle or revert authorisation holds in a Mambu account. Required permission for instant payment processing.
Holds View Account Holds Needed for retrieving authorisation holds details. Required permission for instant payment processing.

Creating the payments API user

Please be Aware

You may not assign API access rights to a user upon creation, you must assign them when editing the user. Follow all the below steps to assign appropriate access rights.

To create a Mambu API user:

  1. Go to Mambu UI > Administration > Access > Users and select Create New User.
  2. Enter all the necessary details. If you have chosen to assign permissions directly to a user (as opposed to through a role) then select them under Permissions. If you have chosen to assign permissions through a role then make sure to select it using the Role dropdown. For a list of permissions, see the table above. For more information on the other available fields, see Creating A User.
  3. Select Save User to create the user.
  4. Find your user in the list of users and select Actions > Edit.
  5. Under Access Rights, select API.
  6. Select Save User.

Editing User dialog

Please be Aware
Please provide the credentials (username and password) to the Mambu team so that they can be set up in the payments system.

Create payment transaction channels

To initiate and receive incoming credit transfers, you must create a reserved transaction channel with ID _payments_sepa_.

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 _payments_sepa_ as the Channel ID. It is important the Channel ID is exactly _payments_sepa_.
  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.



In case you are initiating or receiving direct debits as well, repeat the previous steps in order to create a new transaction channel with a Channel ID of _direct_debit_sepa_.

For more information about transaction channels, see Managing Transaction Channels.

Create the Suspense Account

When using 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.

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

  2. 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.

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

  4. In case there will be a 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

Please Note

This guide covers the basic settings you'll need to apply to get started with the Mambu Payment Gateway. For a more detailed explanation of the available settings, see System Properties.

Mambu Payment Gateway first user registration

To register a user, use the registration form, at

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

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

Once registered, contact the Mambu team to confirm and grant the user you created admin permissions (one time operation). Afterwards the newly created admin can add and approve other new users. For more information, see User Administration below.


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

BIC Configuration

To complete the BIC configuration go to Mambu Payment Gateway UI > Configuration > System Properties > Basic Configuration.

Your BIC is the ISO 9362 identification code made up of a four letter bank code, two letter country code, two character location code and, if you are not using your main branch to process payments, a three character branch code. For example, the BIC for the main branch of the Banque Commerciale du Burkina in Ouagadougou, Burkina Faso is the eight-character BNCFBFBF, while the Le Lamentin branch of Credit Agricole in, Martinique is identified by the eleven-character AGRIMQMXLEL

Field Description Required
Bank BIC The identifier of your bank.
ACH BIC The identifier of the clearing house used to process payments.
ACH Clearing system The channel through which the payment instruction is processed. Maximum of six characters.
Please Note

The MPG will not work properly without these three values.


Please be Aware
Once your tenant Bank BIC has been configured, you must provide the Bank BIC and local bank codes to the Mambu team so that they can finish setting up the payments system.

The AML BIC Sender and AML BIC Receiver fields do not need to be filled out, these have been deprecated and will be removed in an upcoming release.

Callout (webhook) configuration

To complete the Callout configuration go to Mambu Payment Gateway UI > Configuration > System Properties > Callout Configuration

Field Description and recommended inputs
Target URL The webhook URL which is the URL for the gateway to send the outgoing files. It must support POST or PUT requests with an application/xml body.
HTTP Method Select the POST method.
Content Type Must be set to application/xml.
Authorization type If you select Basic authorization, you must provide a username and password.


Retry policy

The retry policy for all Mambu Payment Gateway callouts (i.e SEPA & AML) is as follows:

When a callout fails (responded with 4xx, 5xx or timed out) then an alarm is raised in the MPG alerts section, that contains the following information:

  • Failure reason
  • Number of retries executed so far

The callout will be automatically sent out again on the next outgoing scheduler run, as per your configuration. For example, if outgoing scheduler is configured to run twice a day and it failed the first time, then the callout will be retried only once on that day, and twice the every following day, until it succeeds.

Please Note
Due to the importance of these callouts, the number of retries is unlimited, or better said, retries will continue until the callout is acknowledged by the designated target.

Anti-money laundering (AML) configuration

If AML is enabled, the Mambu Payment Gateway will send the incoming credit instruction to your AML service for a compliance check.

The check should be performed in the external system and the results should be delivered via API. It is possible to configure multiple AML statuses that can be reflected in the screen to show the current state of the transaction.


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 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)

After being configured, they must be started using the button from 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/incoming scheduler can be configured for a given channel. However, you will not be able to create schedulers with overlapping scheduless.

Extra System Properties

In this section you can set a number of parameters related to security in order to meet your company's own internal requirements or national guidelines.


Field Description
Password Expiration Days Set an expiration, in days, after which the user will be prompted to change their password.
Failed login attempts A rule for the number of times a user can fail authentication before their account is locked and must be reenabled by an administrator.
Number of password history to keep The number of passwords which will be retained by the system so a user can not use them again.
Password Minimum Length The minimum amoutn of characters for a user's password.
Test code This field is currently DEPRECATED and will be removed in an upcoming release
Outgoing transactions limit A limit for the number of outgoing transactions that will be bulked into a single message to the clearing house. For example, if you set a limit of 5 and there are 10 transactions picked up by the scheduler, the system will generate two outgoing messages to the clearing house, containing 5 payments each.

SMS gateway settings for multi-factor authentication (MFA)

If you would like to use multi-factor authentication (in which users will be prompted to enter a one time passcode when logging in to the Mambu Payment Gateway), you will need to provide account authentication credentials for your SMS service provider, as well as the number from which messages will be sent. Currently Twilio and Infobip are supported.


For more information about SMS settings and our supported providers, see SMS Setup.

Please note

Only user accounts which have an associated phone number will be able to use MFA, as the one time password must be sent to a mobile phone.


It is possible to define a holidays calendar that will be used to enable or disable payments on certain dates, when the local clearing house is not operating.



The Security menu enables users to:

  1. Create new users
  2. Assign roles
  3. View the audit trail

User Administration

The Mambu Payment Gateway enables the following features for admin users:

  • Create User
  • Modify User
  • Resend Confirmation Mail
  • Enable/Disable Multi-factor Authentication (MFA)

To create a new user:

  1. On the main menu, go to Security > Users.
  2. Select Create user.
  3. Enter all the necessary information. If using MFA, a phone number is mandatory.
  4. Select Create user.

The new user will receive an email containing a link with which they can confirm their account and will be required to set a new password at first login.


To update user information:

  1. On the main menu, go to Security > Users.
  2. Edit the information directly from the list. For example, you may assign roles, remove roles or enable MFA (see video below).
  3. Save the information by selecting the checkmark icon.


Please Note

In order for MFA to function correctly, it is necessary to provide a valid phone number for all new and existing users.

To reset the password:

  1. Click the Send button in the Resend confirmation email column
  2. User will receive an email with a link to reset their password
Please be Aware

To ensure a high level of security for user accounts we enforce a strong password policy for all MPG accounts.
Passwords will need to contain at least one digit, one upper case letter, one special character and have length between 8 and 128 characters. It is also highly recommended to use a password generator to create truly random passwords.

Was this article helpful?