Incoming and Outgoing Messages
The Payments API is designed to handle messages coming from external sources such as clearing houses or other financial institutions, as well as to send XML-formatted payment instructions to your own clearing and settlement provider.
Incoming messages
For handling by the Payments API, all incoming messages must be routed to the /payments/incoming endpoint.
This endpoint accepts XML and responds with an HTTP status of 202 accepted, indicating that the message has been received and will be processed. The response includes a messageId, which can be used to later identify the transaction. For example, it can be used with getPaymentDetails or getCollectionDetails API requests to retrieve payment details and the current status of the transaction.
In case of any incoming message errors, the endpoint responds with a 4xx status code and an array of messages giving details on the errors encountered. Errors can range from invalid content type to individual fields within the message not conforming to the payment scheme specification. Errors will be reported using the TPPMessage model, and should be handled by your service.
As this endpoint may be exposed to external systems, we strongly recommend using a separate API key for each service calling this API. This is an industry best practice and makes debugging easier, it also allows you to rotate or invalidate keys for a particular service in cases of system error or during security incidents.
Outgoing messages
Example outgoing message
Content-Type: application/xml
Authorization: BASIC AuThKey==
Message-Type: urn:iso:std:iso:20022:tech:xsd:pacs.008.001.02
Message-Id: SCTORD156820211213000000012649
<?xml version="1.0" encoding="utf-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pacs.008.001.02">
<FIToFICstmrCdtTrf>
...
</FIToFICstmrCdtTrf>
</Document>
When you create payments or inquiries, the Mambu Payment Gateway generates the appropriate ISO 20022 XML message and schedules it to be sent to the webhook callout URL configured in the Mambu Payment Gateway UI. See the callout configuration section of the Mambu Payment Gateway system properties article in our User Guide for more information on configuring your callout URL, including authentication options.
Outgoing messages are XML formatted messages conforming to the ISO 20022 specification - specifically, the subset supported by the SEPA payment scheme. The Message-Type header includes the type of message sent, such as pacs.008.001.02 for a SEPA credit transfer or camt.056.001.01 for cancellation of a payment.
We strongly recommend that you implement a deduplication or idempotency mechanism on the service which is receiving the outgoing messages. Networks can be unstable and it is possible that the same payment message can be sent multiple times.
Parameters
| Name | Type | Description | In | Required |
|---|---|---|---|---|
| Content-Type | string | The encoding of the content in the body of the request. This will always be application/xml | Header | true |
| Authentication | string | BASIC authentication credentials. Base64 encoded representation of the credentials provided in webhook configuration in the Mambu Payment Gateway settings | Header | false |
| Message-Type | string | Message namespace URN. For example urn:iso:std:iso:20022:tech:xsd:pacs.008.001.02 | Header | true |
| Message-Id | string | Message ID, representing the GrpHdr>MsgId field of the message | Header | true |
| Body | XML | The actual, generated XML message. The content of the message will, depending on the source, include data provided in an API request, data from another payment or collection instruction, or a combination of both. Visit our User Guide for examples of selected messages or refer to the European Payments Council document library for more comprehensive descriptions of the message types supported by the SEPA payment scheme. | body | true |