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
    participant Mambu Payments
    participant Customer
    participant Partner bank / clearing house
    
    Partner bank / clearing house-->>Customer:Forward message<br>from another participant
    Customer->>Customer:Format message into<br>Mambu Payments ISO<br>20022 compliant message
    Customer->>Mambu Payments:Send message<br>to SFTP / API
    Mambu Payments->>Mambu Payments: Validate message against<br>XSD schema
    Mambu Payments->>Mambu Payments: Parse message into Mambu Payments<br>objects (incoming payments, return requests, <br>balances, transactions…)
    Mambu Payments->>Customer: Send webhook event

4.2. Mambu Payments to customer

sequenceDiagram
    participant Mambu Payments
    participant Customer
    participant Partner bank / clearing house

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

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: