Getting Started

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

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

Assign permissions for the 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.

If you choose to assign permissions directly, you may do so while creating or editing the user in the following step.

Create the payments API user

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 Permissions for payments API user. 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.

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.

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

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 https://gateway.TENANT_NAME.sandbox.mambu.com/user/registration/.

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.

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.

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.