Workflows

Deposit accounts mapping

To use a deposit account from Mambu Core within Mambu Payments, you must first create a corresponding internal_account including:

• The account_number used for payment routing used to route payments across partner banks and payment schemes
• The cbs_account_id used to book payments in the relevant deposit account in Mambu Core

ℹ️

The internal_account ID is deterministically generated from the cbs_account_id and your Mambu Payments tenant ID eliminating the need to store the mapping: internal_account.id=UUIDv5(namespace =legal_entity_id, name = cbs_account_id)

🗓️

Automatic synchronisation of your Mambu Core deposit accounts with Mambu Payments internal_account is planned for release in early 2026.

Payments flows

Outbound payments:mambu_authorization validation

When you create a payment_order from an internal_account linked to Mambu Core, Mambu Payments automatically triggers a mambu_authorization validation to check the corresponding deposit account:

• Status to validate that the account is active and not frozen or closed
• Balance to validate that the account has the funds to settle the payment
• Authorized operations to validate that the account is authorised to perform the requested type of payment

If these checks are valid, the payment proceeds to the next step. If any check fails, the payment_order is automatically moved to a canceled status with a detailed failure reason, preventing any transactions to be booked incorrectly.

Incoming payments: real-time approval

When an incoming payment is received on an internal_account, Mambu Payments performs a real-time query to Mambu Core to determine if the payment should be accepted or rejected.

Based on the status and configuration of the deposit account in Mambu, Mambu Payments will automatically accept or reject the payment and book the corresponding transaction on the deposit account if applicable.

Direct debits

Payment order is canceled because Mambu Core did not allow it (closed account, unauthorised operation, insufficient funds, etc.). No transaction is booked on the deposit account.

sequenceDiagram

participant C as You
participant N as Mambu Payments
participant M as Mambu Core
participant S as Payment scheme
C->>N: Initiate payment order
N-->>C: pending_approval
N->>+M: Create authorization hold
M->>-N: Block payment
N->>N:Cancel payment
N-->>C: canceled

Payment order is rejected by the sponsor bank or the scheme. No transaction is booked on the deposit account.

sequenceDiagram

participant C as You
participant N as Mambu Payments
participant M as Mambu Core
participant S as Payment scheme
C->>N: Initiate payment
N-->>C: pending_approval
N->>+M: Create authorization hold
M->>-N: Validate payment
N-->>C: approved
N-->>C: processing
N->>+S: Forward payment
N-->>C: sent
S->>-N: Reject payment
N-->>C: rejected
N->>M: Cancel authorization

Payment order is successfully executed by the sponsor bank or the scheme. The authorization hold is settled.

sequenceDiagram

participant C as You
participant N as Mambu Payments
participant M as Mambu
participant S as Payment scheme
C->>N: Initiate payment
N-->>C: pending_approval
N->>+M: Create authorization hold
M->>-N: Validate payment
N-->>C: approved
N-->>C: processing
N->>+S: Forward payment
N-->>C: sent
S->>-N: Notify payment execution
N-->>C: executed
N->>M: Settle authorization

Credit transfer / instant payment received

Incoming payment is rejected because Mambu Core did not allow it (account closed, operation not authorized, funds insufficient, etc.)

sequenceDiagram

participant C as You
participant N as Mambu Payments
participant M as Mambu
participant S as Payment scheme
S->>N: Forward incoming payment
N-->>C: pending_approval
N->>+M: Create authorization hold
M->>-N: Block payment
N-->>C: rejected
N->>S: Reject payment

Incoming payment is received and booked on an internal account.

sequenceDiagram

participant C as You
participant N as Mambu Payments
participant M as Mambu
participant S as Payment scheme
S->>N: Forward incoming payment
N-->>C: pending_approval
N->>+M: Create authorization hold
M->>-N: Validate payment
N->>S: Confirm payment
N-->>C: received
N->>M: Settle authorization

Internal transfer

If the originating and receiving accounts of a payment are deposit accounts both managed in Mambu Core, Mambu Payments will book them directly in the relevant deposit accounts in Mambu Core and execute an end-to-end payment on the scheme.

sequenceDiagram

participant C as You
participant N as Mambu Payments
participant M as Mambu Core
participant S as Payment scheme
C->>N: Initiate payment order
N-->>C: payment_order:pending_approval
N->>+M: Create authorization holds
M->>-N: Validate payment
N->>N:Settle authorization
N-->>C: payment_order:executed

Technical architecture and configuration

Mambu Payments and Mambu Core integrate using their respective public APIs and webhooks.

To configure your Mambu Core integration, you will need to:

• Generate a dedicated API key in Mambu Core
• Whitelist the IPs of your Mambu Payments tenant
• Configure Mambu Core transaction channels
• If applicable, configure a Mambu Core suspense account

Mambu Core API key

We recommend creating a new API consumer named Mambu Payments with following the permissions:

• Deposit accounts
  • View deposit account details
  • Make deposit
  • Make withdrawal
  • Make intra-clients transfers
  • Make inter-clients transfers
  • Apply deposit account adjustments
  • Backdate deposit transactions
  • Bulk deposit corrections
  • Make early withdrawals
• Holds
  • Create holds
  • Edit account holds
  • View account holds

Whitelisting the IP addresses of your Mambu Payments tenant

In order to make your Mambu Core tenant reachable from Mambu Payments, you need to whitelist the IP addresses of your Mambu Payments tenant in your Mambu Core tenant. Learn how to whitelist IP addresses in Mambu Core.

Mambu Core transaction channels

Transaction channels are used to book transactions in Mambu Core. Mambu Core transaction channels can be mapped with the following payment attributes in Mambu Payments:

• Connected account
• Payment type (SEPA, Swift, FPS…)
• Direction (debit or credit)
• Currency

Mambu Core suspense account

If you would like to use suspense accounts, you will need to configure a suspense account in Mambu Core and Mambu Payments.