Queues & routing

The hub runs on a dual messaging fabric: IBM MQ (via the Spring Cloud Stream sjms2 binder) carries the mission-critical SWIFT/enterprise queues, while Apache Kafka carries inter-service events, fallbacks, idempotency, and the dead-letter stream. One cross-border channel uses AWS SQS. Destination names are literal strings in each module's application-bindings.yml; the IBM MQ queue manager must have a matching DEFINE QLOCAL for each (see docker/mq/20-config.mqsc).

Destination types

Type	Binder	Carries
IBM MQ queue	sjms2	SWIFT in/out, CBS/TMS/ERP exchange, screening (SSC), fraud, archiving, statements
Kafka topic	kafka	DLQ stream, per-service *.idempotent, S3-fallback notices, cross-border events, observability, STP/ISO mirrors
SQS queue	aws2-sqs	Inbound Mastercard cross-border status webhook

Inbound channels (IBM MQ)

Queue	Consumer binding	Module
SWIFT.OUT.MT.ALLINCOMING	swiftMTProcessor-in-0	processor
SWIFT.OUT.ISO.ALLINCOMING	incomingISO2CBSProcessor-in-0	processor
SWIFT.OUT.MT.ALLACKS / SWIFT.OUT.ISO.ALLACKS	ackMTProcessor-in-0 / incomingACKSISOProcessor-in-0	processor
SWIFT.OUT.NON.DELIVERY.NOTICE	nonDeliveryNoticeProcessor-in-0	processor
SSC.INWARD.SCREENED	mtIncomingProcessor-in-0	processor
SWIFT.IN.CLEARED.ISO	clearedISOProcessor-in-0	processor
CBS.MT.OUT / TMS.MT.OUT,TMS.MT.OUT.UAT / ERP.MT.OUT / TRACKER.MT.OUT	cbsMTProcessor / tmsMTProcessor / sapMTProcessor / trackerMTProcessor	processor
CBS.ISO.OUT / TMS.ISO.OUT.UAT / ERP.ISO.OUT / ERP.XML.OUT	PDU converters (mxToISOPDUProcessor, tmsISOPDUProcessor, erpToMxPDUProcessor, sapXmlProcessor)	processor
MT.DOS.PCC.QUEUE,MT.RJE.QUEUE,SAA.MOD.QUEUE	ofacProcessor-in-0	manager

Downstream / outbound (IBM MQ)

Queue	Purpose
CBS.MT.IN.CORE · CBS.MT.IN.PAYMENT · CBS.MT.IN.OTHERS	Core-banking inbound by category
CBS.MT.IN.CORE.FALLBACK · CBS.MT.IN.PAYMENT.FALLBACK (Kafka)	S3-fallback notices when MQ publish fails
TMS.MT.IN.UAT · TMS.ISO.IN.UAT	Treasury inbound
ERP.STATEMENTS.IN (prod: CBS.MT.IN.STATEMENTS)	Statements to ERP/CBS
SWIFT.IN.ISO · SWIFT.IN.MT · SWIFT.IN.DOS	Cleared messages back to SWIFT
SWIFT.IN.ISO.CBS.STP · SWIFT.IN.ISO.TMS.STP · SWIFT.IN.MT.CBS.STP · SWIFT.IN.MT.SAP.STP	Straight-through-processing lanes
FRAUD.ISO.IN.QUEUE · FRAUD.MT.IN.QUEUE	Fraud screening
SSC.IN.QUEUE · SSC.IN.BYPASS · SSC.DECISION.QUEUE · SSC.INWARD.SCREENED · SSC.OUT.REJECTED · SSC.INWARD.REJECTED	Sanctions-screening (OFAC) pipeline
ARCHIVING.QUEUE · ARCHIVING.ISO.QUEUE · SWIFTWAREHOUSE.IN.QUEUE · SWIFTWAREHOUSE.IN.ISO.QUEUE · STATEMENTS.ISO.QUEUE	Archival & warehousing
SWIFT.MT.CROSSBORDER · SWIFT.MT.CROSSBORDER.STATUS	Cross-border in/out

Kafka topics

Topic	Role
MESSAGE.HUB.EXCEPTION.DLQ	Central dead-letter stream (every module produces; afpay-message-dlq consumes)
DLQ.ALERT.QUEUE	Operator alerts raised by the DLQ service
<app-name>.idempotent	Per-service idempotency log (KafkaIdempotentRepository)
CBS.MT.IN.CORE.FALLBACK · CBS.MT.IN.PAYMENT.FALLBACK	SFTP→S3 fallback notices
MC.PAYMENT.OUTGOING · MC.PAYMENT.FEEDBACK	Mastercard cross-border events
ARCHIVING.COPY.MT.TOPIC · ARCHIVING.COPY.ISO.TOPIC	Archive copy stream
MT199.TRACKER.MT.OUT · OPS.MANUAL.MT199.TRACKER	GPI tracker MT199 status
mhub.observability.messages.{lifecycle,errors,compliance}	Message observability events

SQS

Queue	Binding	Producer
message-hub-crossborder-webhook	mcStatusWebhookProcessor-in-0 (crossborder)	crossborder-webhook-lambda (Quarkus on AWS Lambda)

Routing rules

Inbound MT after screening → CBS fan-out (SSC.INWARD.SCREENED → handleIncomingMT):

• MT category 1 or 2 → CBS.MT.IN.PAYMENT (prod remaps to CBS.MT.IN.CORE)
• MT 940 / 950 → ERP.STATEMENTS.IN (prod: CBS.MT.IN.STATEMENTS)
• otherwise → CBS.MT.IN.CORE
• always also copied to ARCHIVING.QUEUE + SWIFTWAREHOUSE.IN.QUEUE
• types 3xx/5xx or 199/999/940/942/950 → also TMS.MT.IN.UAT

Outbound MT fan-in → SWIFT — CBS.MT.OUT, TMS.MT.OUT(.UAT), ERP.MT.OUT, TRACKER.MT.OUT all converge on handleOutgoingMT (a route is created per CSV destination).

Inbound ISO / PDU conversion (handleMxToISOPDU): if the formatted type is pacs.008 / pacs.009 → route to FRAUD.ISO.IN.QUEUE; otherwise straight to handleClearedISO.

Cleared-ISO STP decision (SWIFT.IN.CLEARED.ISO → handleClearedISO): STP is eligible when enabled and type is pacs.008/009 and amount ≤ the currency/origin threshold. Then:

• STP + origin TMS → SWIFT.IN.ISO.TMS.STP
• STP + origin CBS/SAP → SWIFT.IN.ISO.CBS.STP
• non-STP → SWIFT.IN.ISO (queue + Kafka mirror)

MT screening & STP (manager): MT 103/202 → FRAUD.MT.IN.QUEUE; else SWIFT.IN.CLEARED.MT. Cleared SAP-origin → SWIFT.IN.MT.SAP.STP, else SWIFT.IN.MT.CBS.STP; non-STP → SWIFT.IN.MT (+ SWIFT.IN.DOS).

ACKs / non-delivery — ACKs consumed off SWIFT.OUT.*.ALLACKS; non-delivery notices consumed off MQ and republished to Kafka under the same name.

SFTP fallback — CBS.MT.IN.CORE/PAYMENT are also consumed by the SFTP module; on an MQ publish failure the payload is stored in S3 and a notice is emitted to the Kafka *.FALLBACK topic.

DLQ — every route uses a Camel deadLetterChannel("seda:dlq") (3 redeliveries, 5 s delay, original message preserved). Failures land on MESSAGE.HUB.EXCEPTION.DLQ → afpay-message-dlq persists to DynamoDB, raises a Jira ticket, and emits DLQ.ALERT.QUEUE.

:::note Idempotency (three layers)

1. Kafka — <app-name>.idempotent log per service (key JMSMessageID-CamelMessageTimestamp).
2. Redis — file-level dedup in the SFTP module (35-day TTL).
3. DynamoDB — UUID + auto-versioning in tracker / archive / DLQ. :::