Getting Messages

Outgoing messages (e.g. notifications generated for your client application) are retrieved by polling a "next message" endpoint and explicitly confirming each one you've processed.

1. Poll for the next message

GET /messages/next
Row-Version: {lastKnownRowVersion}   (optional)
Accept: application/xml

Authenticated via your mTLS client certificate. Behavior:

Response	Meaning
200 OK + XML body	The next available message for your client application, plus a Row-Version response header identifying it.
204 No Content	No new message is waiting.
500 Internal Server Error	Unexpected failure; body is a small <Error> XML document.

The XML body is a signed BusinessMessage envelope (bcon.002.001.01) that carries a head.001.001.02 Business Application Header and the message document, e.g. a pain.002.001.10 payment status report. The XSDs are published at altasoft.github.io/geo-iso20022 and can be downloaded from github.com/altasoft/geo-iso20022/tree/main/xsds; use them to parse and validate the message.

Pass the Row-Version header you received back on your next poll so the API knows your current cursor position.

2. Confirm the message

Once you've durably processed a message, confirm it so it's removed from the queue and the next poll advances:

POST /messages/confirm/{messageId}

Where {messageId} is the Row-Version value returned with that message. On success, the response body is <Result>Ok</Result>.

Suggested polling pattern

1. Poll

   Call GET /messages/next with your last stored Row-Version.

2. Process

   If you get a 200, parse and durably handle the message content before doing anything else.

3. Confirm

   Only after processing succeeds, call POST /messages/confirm/{messageId} with that message's row version, then repeat from step 1. If confirmation fails, retry it before polling again — don't re-poll past an unconfirmed message.