ISO 20022 message-based integration

Integrate with Mambu Payments (formerly Numeral) using ISO 20022 messages over API or SFTP

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

MethodDescription
APISend ISO 20022 messages through API
SFTPUpload ISO 20022 messages as files

3.2. Mambu Payments to customer

MethodDescription
APIRetrieve ISO 20022 messages generated by Mambu Payments through API
SFTPDownload ISO 20022 messages uploaded in customer-specific SFTP directory
WebhookFor real-time payments, Mambu Payments will send messages to your webhook endpoint. You must respond with the appropriate status code and payload

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.

Message IDMessage nameSpecifications
pacs.008.001.08FIToFICustomerCreditTransferV08pacs.008.001.08 XSD schema and business logic
pain.001.001.03CustomerCreditTransferInitiationV03Link
pacs.003.001.08FIToFICustomerDirectDebitV08Link
pain.008.001.02CustomerDirectDebitInitiationV02Link
pacs.002.001.10FIToFIPaymentStatusReportV10Link
pain.002.001.10CustomerPaymentStatusReportV10Link
camt.053.001.02BankToCustomerStatementV02Link
pacs.004.001.09PaymentReturnV09Link
camt.029.001.09ResolutionOfInvestigationV09Link
camt.056.001.08FIToFIPaymentCancellationRequestV08Link
pacs.007.001.09FIToFIPaymentReversalV09Link
pacs.028.001.03FIToFIPaymentStatusRequestV03Link
camt.027.001.07ClaimNonReceiptV07Link
camt.087.001.06RequestToModifyPaymentV06Link