This guide explains how to integrate with Mambu Payments using ISO 20022 messages. It covers supported payment types and schemes, payment and message flows, connectivity options, and how to send and receive messages using SFTP or API endpoints.

This approach gives the flexibility to connect your existing systems to Mambu Payments and support partner banks, clearing houses, or last-mile connectivity providers that are not natively supported by Mambu Payments, while enjoying the benefits of our payments hub.

The integration is based on the exchange of ISO 20022 messages for payment initiation, payment status reports, and account statements over SFTP, API, or webhook.

1. Payment types and schemes

The integration supports a wide range of payment types and schemes and their related payment flows that can be represented using ISO 20022 messages:

• Credit transfers
• Direct debits
• Real-time payments
• RTGS / high-value payments

Any scheme with a compatible ISO 20022 message structure can be supported on demand. Learn more about payment schemes currently supported.

2. Payment flows and ISO 20022 messages

Mambu Payments supports the most common payment flows using ISO 20022 messages.

Incoming messages are parsed and converted into the corresponding Mambu Payments-native objects (e.g., incoming payment, balances, transactions, status updates…). They must conform to the ISO 20022 XSD schemas and business logics below.

Outgoing messages are generated from Mambu Payments-native objects (e.g., payment orders). They also conform to the ISO 20022 XSD schemas and business logics below.

3. Supported connectivity options

3.1. Customer to Mambu Payments

3.2. Mambu Payments to customer

4. High-level integration flows

4.1. Customer to Mambu Payments

sequenceDiagram
autonumber
participant C1 as Customer<br/>via unified Mambu<br/>Payments API
box
  participant M as Mambu Payments
  participant C2 as Customer<br/>via ISO 20022<br/>integration
end
participant PBCH as Partner bank / clearing house

PBCH ->> C2: Forward message<br/>from another participant
C2 ->> C2: Format message into<br/>Mambu Payments ISO<br/>20022 compliant message
C2 ->> M: Send message<br/>to SFTP / API
M ->> M: Validate message against<br/>XSD schema
M ->> M: Parse message into Mambu Payments<br/>objects (incoming payments, return requests, <br/>balances, transactions…)
M ->> C1: Send event to webhook

4.2. Mambu Payments to customer

sequenceDiagram
autonumber
participant C1 as Customer<br/>via unified Mambu<br/>Payments API
box
  participant M as Mambu Payments
  participant C2 as Customer<br/>via ISO 20022<br/>integration
end
participant PBCH as Partner bank / clearing house

C1 ->> C1: Create resource (payment order, return request…)
C1 ->> M: Send corresponding API request
M ->> M: Process API request
M ->> M: Create or update object<br/>(payment order, return request…)
M ->> C1: Send event to webhook
M ->> M: Batch object(s) into<br/>Mambu Payments ISO<br/>20022 compliant message
M ->> C2: Send message to SFTP / API
M ->> C1: Send event to webhook
C2 ->> C2: Format message into partner bank<br/>/ clearing house compliant format
C2 ->> PBCH: Send message

loop
PBCH ->> C2: Report
C2 ->> C2: Format message into<br/>Mambu Payments ISO<br/>20022 compliant message
C2 ->> M: Send message<br/>to SFTP / API
M ->> M: Validate message against<br/>XSD schema
M ->> M: Parse message into Mambu Payments<br/>objects (payment status report, result of investigation…)
M ->> C1: Send event to webhook
end

5. ISO 20022 message library

Below are the ISO 20022 messages supported as well as associated specifications.

6. ISO 20022 message ack / nack

The HTTP status code for API or webhook requests or the SFTP status code for SFTP requests is used to determine the success or failure of reception by Mambu Payments or the customer. The table below summarises the different codes: