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
Method | Description |
---|---|
API | Send ISO 20022 messages through API |
SFTP | Upload ISO 20022 messages as files |
3.2. Mambu Payments to customer
Method | Description |
---|---|
API | Retrieve ISO 20022 messages generated by Mambu Payments through API |
SFTP | Download ISO 20022 messages uploaded in customer-specific SFTP directory |
Webhook | For 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 ID | Message name | Specifications |
---|---|---|
pacs.008.001.08 | FIToFICustomerCreditTransferV08 | pacs.008.001.08 XSD schema and business logic |
pain.001.001.03 | CustomerCreditTransferInitiationV03 | Link |
pacs.003.001.08 | FIToFICustomerDirectDebitV08 | Link |
pain.008.001.02 | CustomerDirectDebitInitiationV02 | Link |
pacs.002.001.10 | FIToFIPaymentStatusReportV10 | Link |
pain.002.001.10 | CustomerPaymentStatusReportV10 | Link |
camt.053.001.02 | BankToCustomerStatementV02 | Link |
pacs.004.001.09 | PaymentReturnV09 | Link |
camt.029.001.09 | ResolutionOfInvestigationV09 | Link |
camt.056.001.08 | FIToFIPaymentCancellationRequestV08 | Link |
pacs.007.001.09 | FIToFIPaymentReversalV09 | Link |
pacs.028.001.03 | FIToFIPaymentStatusRequestV03 | Link |
camt.027.001.07 | ClaimNonReceiptV07 | Link |
camt.087.001.06 | RequestToModifyPaymentV06 | Link |
Updated about 16 hours ago