Skip to main content

​
Why this matters

Event publishing lets your systems react to transactions the moment they happen — trigger customer notifications, sync your ERP, feed analytics dashboards, or kick off compliance workflows. All of this without tightly coupling your systems together. The sections below cover the technical setup. For a business-oriented overview, see About Midaz.

​
Enabling transaction events

To activate this feature, set the following environment variable in the transaction application: 
RABBITMQ_TRANSACTION_EVENTS_ENABLED=true
Once enabled, Midaz starts publishing events to the following exchange in RabbitMQ: 
transaction.transaction_events.exchange

​
Event types

Midaz emits one of the following event types depending on the transaction lifecycle:
ActionDescription
APPROVEDThe transaction was successfully completed. This includes single-step transactions and two-phase transactions that have been committed.
PENDINGA two-phase transaction was created and is waiting for either a commit or cancellation.
CANCELEDA two-phase transaction was canceled before confirmation.
CREATEDA reversal transaction was initiated. This is a transient status that progresses to APPROVED once processing completes.
NOTEDAn annotation transaction was recorded. The transaction is logged in the ledger without affecting account balances.

​
Example event payload

{
  "source": "midaz",
  "eventType": "transaction",
  "action": "APPROVED",
  "timestamp": "0000-00-00T18:09:03.757330233Z",
  "version": "v3.0.0",
  "organizationId": "0198575d-f9fd-702b-bb15-fa4c980b32c7",
  "ledgerId": "0198575d-fa0b-7ac7-8b7d-9d3ab7dccafc",
  "payload": {
    "id": "0198575f-a8f9-7924-a6d7-8122f2c77ddd",
    "status": {
      "code": "APPROVED",
      "description": "APPROVED"
    },
    "amount": "1",
    "assetCode": "BRL",
    "source": ["account:1"],
    "destination": ["account:2"],
    "metadata": {
      "key": "value"
    },
    "operations": [
      {
        "type": "DEBIT",
        "amount": { "value": "1" },
        "accountAlias": "account:1"
      },
      {
        "type": "CREDIT",
        "amount": { "value": "1" },
        "accountAlias": "account:2"
      }
    ]
  }
}
The full payload includes timestamps, balance snapshots, and other identifiers used for auditing and traceability.

​
Event routing model

To ensure flexibility and scalability, Midaz uses a topic exchange to publish messages instead of sending them directly to specific queues. This means you control which events to receive by configuring your own bindings.

​
How routing works

Each event published by Midaz is tagged with a routingKey using the format: 
midaz.transaction.<status>
Where <status> corresponds to the current transaction status (APPROVED, PENDING, CANCELED, CREATED, or NOTED). To consume events, your application must:
1
Create a queue in RabbitMQ.
2
Bind your queue to the Midaz exchange using the routingKey pattern that matches your interest.

​
Visual overview

You can configure multiple queues with different bindings to serve specific teams or services independently.

​
Queue and binding example

​
Creating a new queue

{
  "queues": [
    {
      "name": "new_queue_name.queue",
      "vhost": "/",
      "durable": true
    }
  ]
}

​
Binding the queue to receive all events

{
  "bindings": [
    {
      "source": "transaction.transaction_events.exchange",
      "vhost": "/",
      "destination": "new_queue_name.queue",
      "destination_type": "queue",
      "routing_key": "midaz.transaction.*"
    }
  ]
}
The wildcard * matches all five statuses: APPROVED, PENDING, CANCELED, CREATED, and NOTED. To subscribe to specific events only, replace the wildcard with the exact status — for example, midaz.transaction.NOTED to receive only annotation events.
Midaz does not manage or create RabbitMQ queues for you. You are responsible for provisioning queues and setting up the correct bindings.