- Updated On 05 Mar 2021
- 9 Minutes To Read
Before tenants can start using the Payments APIs and the Payments Gateway the following steps are required:
- Create API Consumer & Generate Key
- Create Mambu API user
- Create the payments transaction channel
- Create the Suspense Account (optional)
- Payment Gateway 1st user registration
- BIC Configuration
- Webhook configuration
- Set up AML
- Schedulers configuration
- Enable SMS Gateway for Multi-factor Authentication (optional)
- Configure holidays (optional)
- Create additional payment gateway users (recommended)
Create Payment Api Consumer & Key
The Payments API requires an API Key to be included in the
ApiKey header of all requests made to the payments API.
In order to generate a new API Key, an API Consumer of type
payments needs to be created. To complete this step, go to Mambu -> Administration -> API Consumers -> Add Consumer.
Make sure you select
payments as the consumer type.
Once the consumer was created, in the API Consumers section go to that specific consumer, at the Actions -> Manage Keys section. Press the Generate button, and a new API Key should be generated. You can view it by pressing the Show button, or go to Actions -> Delete in order to delete it.
Mambu API User
A Mambu API user needs to be created in Mambu, which is used to perform withdrawal, deposit and adjustment transactions on the Mambu Accounts. To complete this step go to Mambu → Administration → Access → Users and check the box for 'API' under Access Rights.
Before saving make sure that the permissions listed below are enabled. We recommend bundling these permissions into a Role so that is easy to apply them to new API users, as well as secure the transaction channel you will be using for SEPA payments against accidental use by other Mambu users.
- Deposit Accounts > View Deposit Account Details
- Deposit Accounts > Make Deposit
- Deposit Accounts > Make Withdrawal
- Deposit Accounts > Make Intra-clients Transfers
- Deposit Accounts > Make Inter-clients Transfers
- Deposit Accounts > Apply Deposit Account Adjustments
- Deposit Accounts > Backdate Deposit Transactions
- Deposit Accounts > Bulk Deposit Corrections
- Accounting > Booking Date Deposits Journal Entries
Define a Username and Password and save the API user.
Create Payment Transaction Channels
In order to initiate and receive incoming Credit Transfers, a reserved transaction channel with ID
_payments_sepa_ needs to be configured. To complete this step go to Mambu → Administration → Financial Setup → Transaction Channels → Add Channel
Tenants can configure the Channel name accordingly with their preference however the Channel ID must be exactly:
_payments_sepa_. Additionally tick the box in the Usage Rights section that corresponds to the SEPA payments user role you created in the previous step.
In case you are initiating or receiving Direct Debits as well, repeat the previous steps in order to create a new channel with Channel ID being
Create the Suspense Account
The Suspension of funds for the AML flow requires an additional deposit product and account to be configured with specific GL accounts for accounting.
Suspense GL Account
Add a new Liablity GL Account from: Mambu → Accounting → Chart of Accounts → Add A New Account
Create a Deposit Account with the product defined at step 2.
In case there will be a need to initiate payments out of the suspense account, it will have to be mapped with a respective IBAN, using the External Account Representation API.
The ID of your Suspense Account Should be passed over to the Mambu support team, in order to configure it within the Mambu Payment Gateway.
Payment Gateway Configuration
Payment Gateway 1st User registration
Please use the registration form, located at
https://gateway.[tenant].sandbox.mambu.com/user/registration/ to register. You must use a strong password, that is at least 8 characters and includes at least one of the following; uppercase letter, lowercase letter, number and special character. You will also be able to set your own rules regarding password complexity and expiration in the settings.
Once registered, please contact the Mambu team to confirm and grant the created user admin privileges (one time operation). Afterwards the newly created admin can add and approve other new users.
Once your account has been created, you can proceed with the configuration of the payment gateway by accessing the Configuration menu.
To complete the BIC configuration go to 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
- Bank BIC: the identifier of your bank
- ACH BIC: the identifier of the clearing house used to process payments
- ACH Clearing system: max 6 chars. The channel through which the payment instruction is processed.
Keep in mind that the Payment Gateway will not work properly without these 3 values correctly completed.
If using an Anti Money Laundering service to monitor transactions and transaction sources, you will also need to provide the sending and receiving BICs for your provider.
Callout (webhook) Configuration
Gateway → Configuration → System Properties → Webhook Configuration
A webhook URL should be added, which supports POST or PUT with an
application/xml body. The webhook mechanism also offers support for basic authentication, so if your endpoint supports it, select Basic Authentication from the dropdown menu and input a user and a password.
- Webhook configuration (callout)
Target URL - Insert the Webhook URL - The URL expected for the gateway to send the outgoing files.
HTTP Method - Select POST
Content Type - Select application/xml
Authorization type - If using basic authentication please provide the username and password
The retry policy for all 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 payment gateway, 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.
If AML (Anti Money Laundering) is enabled, the Mambu Payment Gateway will send the incoming credit instruction for an AML 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 / Outgoing schedulers configuration
Payments are processed in bulk, according to a configurable schedule. In order to configure this schedule, go to Gateway → 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:
- Incoming (to receive payment information) and
- 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 a scheduler to process retries and returns.
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.
- Set an expiration, in days, after which the user will be prompted to change their password
- Add a rule for the number of times a user can fail authenitcation before their account is locked and must be reenabled by an administrator
- Set the number of passwords which will be retained by the system so a user can not use them again
Password Complexity- this field is currently DEPRECATED and will be removed in an upcoming release Test code- this field is currently DEPRECATED and will be removed in an upcoming release
- Set a limit to 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 Payment Gateway), you will need to provide account authentication credentials for your SMS service provider which must be one of Twilio or Infobip, as well as the number from which messages will be sent.
You can find more information on sms settings and our supported providers at this page.
Only user accounts which have an associated phone number will be able to use MFA, as the one time password will 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:
- Create new users
- Assign Roles
- View full audit trail
The 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:
Step 1: Open the Users list
Step 2: Click Create user
Step 3: Provide information for all fields, if using MFA, a phone number is mandatory.
Step 4: Click 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:
Step 1: Open the Users list
Step 2: Edit the information directly from the list, eg assign, remove roles, enable MFA (see video below)
Step 3: Save the information using the tick button
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:
Step 1: Click the Send button in the Resend confirmation email column
Step 2: User will receive an email with a link to reset their password
To ensure a high level of security for user accounts we enforce a strong password policy for all Payments Gateway 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.