Event publisher

Enable the Midaz event publisher to stream approved, pending, canceled, and reversal transaction events to a RabbitMQ exchange for downstream integrations.

Why this matters

---

Published events let your systems react to a transaction the moment it happens. You can trigger customer notifications, sync your ERP, feed analytics dashboards, or start compliance workflows. Your systems stay loosely coupled.

The sections below cover the technical setup. For a business overview, see About Midaz.

Enabling transaction events

---

Midaz publishes transaction events by default. It treats the flag as enabled unless you set it to false. The bundled example configuration ships the flag set to false. On a stack that starts from that example, set the flag to true in the transaction application:

JSON

RABBITMQ_TRANSACTION_EVENTS_ENABLED=true

With the flag enabled, Midaz publishes events to this RabbitMQ exchange:

JSON

transaction.transaction_events.exchange

Event types

---

Midaz emits one of these event types, based on the transaction lifecycle stage:

Action	Description
APPROVED	The transaction was successfully completed. This includes single-step transactions and two-phase transactions that have been committed.
PENDING	A two-phase transaction was created and is waiting for either a commit or cancellation.
CANCELED	A two-phase transaction was canceled before confirmation.
CREATED	A reversal transaction was initiated. This is a transient status that progresses to APPROVED once processing completes.
NOTED	An annotation transaction was recorded. The transaction is logged in the ledger without affecting account balances.

Example event payload

---

JSON

{
  "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. You use these for audit and traceability.

Event routing model

---

Midaz uses a topic exchange to publish messages. It does not send messages directly to specific queues. You control which events you receive with your own bindings.

How routing works

Midaz tags each event with a routingKey. The routingKey uses this format:

midaz.transaction.<status>

The <status> value is 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 with a routingKey pattern for the events you want.

Visual overview

Figure 1. Visual representation of the event routing model.

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

Queue and binding example

---

Creating a new queue

JSON

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

Binding the queue to receive all events

JSON

{
  "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 one event type, replace the wildcard with the exact status. For example, midaz.transaction.NOTED receives only annotation events.

Midaz does not manage or create RabbitMQ queues for you. You must provision the queues and set up the correct bindings.