Skip to main content

Integrations & requirements

The hub depends on several external systems. Each section lists what it's used for, the integration library, and the required configuration (config keys / environment variables). Credential values live in each module's application*.yml or dedicated property/keystore files — supply your own per environment.

:::warning Secrets Config keys and env-var names are documented here; never commit real secret values. The Mastercard sandbox keystore, consumer key, and encryption fingerprint ship in the repo for sandbox only and must be replaced for any non-sandbox use. :::

AWS Bedrock — AI address restructuring​

  • Used for: AI-powered restructuring/cleanup of party addresses during MT ↔ ISO 20022 translation and cross-border payload assembly (afpay-message-aitools → AddressRestructuringService, on a bounded bedrockAddressExecutor).
  • Library: Spring AI spring-ai-starter-model-bedrock-converse + AWS SDK bedrock (Spring AI 1.1.7).
  • Model: spring.ai.bedrock.converse.chat.options.model = ${BEDROCK_MODEL_ID}. The in-code default is Amazon Nova (eu.amazon.nova-2-lite-v1:0); the dev/uat overrides use Anthropic Claude 3.5 Sonnet (eu.anthropic.claude-3-5-sonnet-20240620-v1:0) via the EU cross-region inference profile.
  • Required: BEDROCK_MODEL_ID, BEDROCK_REGION (default eu-west-1), BEDROCK_ACCESS_KEY_ID, BEDROCK_SECRET_ACCESS_KEY, BEDROCK_TIMEOUT. If the keys are blank it falls back to the default AWS credential chain (IAM role / IRSA). Tuning: temperature 0.2, top-p 0.9, max-tokens 1500.

Mastercard Cross-Border​

  • Used for: cross-border payments (quote, payment, retrieve, cancel, FX rates, balances) and account/IBAN/bank/address validation (afpay-message-crossborder). MT103 → Mastercard RemittanceRequest.
  • Libraries: Mastercard client-encryption 1.8.8 + oauth1-signer 1.6.0, Apache Oltu JWT, Spring Cloud OpenFeign (+ feign-okhttp), Resilience4j. The SDK is generated by OpenAPI Generator 7.12.0 from four specs in src/main/resources/openapi/: Crossborder, Bank Account Validation, Address Validation Service, Consolidated Status Change.
  • Config (mastercard-api.properties, sandbox base https://sandbox.api.mastercard.com, partner ARE_SANDBOX01ok): consumerKey, OAuth1 signing keystore (.p12 + keyalias + password, signatureType=JWS, TLSv1.3), and client-encryption (certificateFile, fingerPrint, decryption key). Values redacted — supply your own.
  • Endpoints called (templated with {partner-id}): POST …/crossborder/payment, …/crossborder/quotes, GET …/crossborder/{payment-id}, …/crossborder/rates, POST …/{payment-id}/cancel, account balances, IBAN generate/validate, bank details, and …/address-validation-service/addresses/validations.
  • Status webhook: Mastercard status callbacks → crossborder-webhook-lambda (Quarkus on AWS Lambda) → SQS message-hub-crossborder-webhook → consumed by the crossborder service.

IBM MQ (SWIFT Alliance Access feed)​

  • Used for: the mission-critical SWIFT/enterprise queues (all sjms2 bindings). Primary ingress for the SWIFT Alliance Access feed.
  • Library: mq-jms-spring-boot-starter 3.5.13 + Camel sjms2.
  • Required: IBMMQ_HOST, IBMMQ_PORT, IBMMQ_USER, IBMMQ_PASSWORD, IBMMQ_QUEUE_MANAGER, IBMMQ_CHANNEL (plus optional pool/recovery tuning). Dev: QM1 / DEV.APP.SVRCONN on localhost:1414. The queue manager must declare a QLOCAL for every queue the hub uses (authoritative local list in docker/mq/20-config.mqsc).

Conductor (SWIFT GPI tracking)​

  • Used for: orchestrating GPI inflow/outflow tracking (afpay-message-tracker).
  • Library: Orkes/Netflix Conductor client 4.1.3 (worker.all.domain: gpitracking).
  • Required: CONDUCTOR_API_SERVER_URL (default http://localhost:9090/api; local server orkesio/orkes-conductor-community-standalone).
  • Workflows (_workflows/): gpi_inflow_sameday_wf, gpi_inflow_nextday_wf, gpi_outflow_sameday_wf, gpi_outflow_nextday_wf, fina_task_status_check_workflow.

Jira (DLQ ticketing)​

  • Used for: raising/ watching Jira issues for dead-lettered messages (afpay-message-dlq, Camel jira:// component, OAuth1a).
  • Required: JIRA_SERVICEDESK_URL, JIRA_SERVICEDESK_CONSUMER_KEY, JIRA_SERVICEDESK_ACCESS_TOKEN, JIRA_SERVICEDESK_PRIVATE_KEY, JIRA_SERVICEDESK_VERIFICATION_CODE; project key, priority, and issue-type id.

SFTP (CBS / Finacle / statements)​

  • Used for: file-based exchange with CBS/Finacle and statement delivery (afpay-message-sftp; lightweight fallback in afpay-message-emergency). Spring Integration SFTP with Redis file-level idempotency, Quartz retry scheduling, and S3 fallback.
  • Three servers: cbs-incoming (APP_PROPS_SFTP_*), mt-finacle (MT_FINACLE_SFTP_*), mt-statement (MT_STATEMENTS_SFTP_*) — each with HOST/PORT/USER/PASSWORD/PRIVATEKEY/PRIVATEKEY_PASSPHRASE/WITH_PRIVATEKEY.
  • Required also: REDIS_HOST/PORT/PASSWORD/DATABASE/TLS_ENABLED, QUARTZ_THREAD_COUNT, and the SFTP_* feature flags (S3 archive, Redis metadata store, JMS transaction manager, max file size).

AWS — DynamoDB · S3 · SQS · SES​

  • DynamoDB — message persistence in tracker/archive/DLQ (table names resolved at runtime from entity classes). Required: DYNAMODB_REGION, DYNAMODB_ACCESS_KEY, DYNAMODB_SECRET_KEY, DYNAMODB_ENDPOINT.
  • S3 — SFTP archive + MQ/SFTP retry store. Required: S3_ARCHIVE_BUCKET (default afpay-sftp-archive), S3_REGION, S3_ENDPOINT, S3_ACCESS_KEY, S3_SECRET_KEY, S3_RETRY_*.
  • SQS — cross-border webhook queue. Required: SQS_QUEUE_ACCESS_KEY, SQS_QUEUE_SECRET_KEY, AWS_REGION, WEBHOOK_SQS_QUEUE_NAME.
  • SES (SMTP) — alerting mail (MAIL_HOST e.g. email-smtp.eu-west-1.amazonaws.com).

Observability​

  • OpenTelemetry (OTLP) — OTLP_EXPORTER_ENDPOINT (default http://localhost:4318, http/protobuf), OTLP_EXPORTER_LICENSE_KEY (UAT exports to New Relic). Resource: service.namespace=afreximbank.
  • Jaeger — local trace UI (docker/local-compose.yml).
  • Seq (GELF logs) — GELF_HOST / GELF_PORT (default localhost:12201).

Local development stack​

docker/Makefile → make local brings up: Redis (6379), IBM MQ QM1 (1414/9443/9157), LocalStack (4566 — s3/sqs/lambda/dynamodb), Seq (5341) + GELF input (12201/udp), PostgreSQL (5432), Jaeger (4317/4318/16686), and Redpanda Kafka (9092/29092) + console (8080). make mq and make conductor start those subsystems individually.