Notifications
Real-time notifications for transaction lifecycle events using NATS request-reply messaging.
Overview
The Transaction Notification Stream provides real-time notifications for transaction lifecycle events using NATS request-reply messaging. This system delivers events reliably with automatic retry and timeout handling.
Message Schema
Subject Pattern
Every notification is published to a subject that ends with the transaction's ID:
You don't know transaction IDs ahead of time, so subscribe with the wildcard to receive every transaction:
One exception: a REVERSAL_REQUEST has no transaction ID yet, so its subject ends with its retrieval_ref_number instead. The wildcard subscription receives it either way.
Examples:
Message Payload
All messages share this envelope. A created event carries the full transaction details:
End Events
succeeded and failed are status updates, not full snapshots. They carry only the transaction's ID, its account and a timestamp. transaction_type, amount, parent_transaction_id and card details appear only on created:
Store every created event
An end event on its own can't tell you what settled: a refund's succeeded looks the same as a purchase's. Store each created event keyed by transaction_id, and look it up when the end event arrives. If an end event ever arrives without its created, fetch the transaction with Get Transaction by ID.
Field Descriptions
| Field | Type | Description |
|---|---|---|
event | string | Event lifecycle phase: created, succeeded, failed (cancelled is deprecated, see Transaction Lifecycle) |
data.notification_type | string | Always "transaction" for this stream |
data.transaction_id | UUID | Unique identifier for the transaction. Always all zeros on REVERSAL_REQUEST, see Refund requests |
data.transaction_type | string | created only. Type of transaction: EFT, RTC, Card (a card payment), CREDIT (incoming money), REVERSAL (a refund), REVERSAL_REQUEST (a refund that has been requested but not yet paid) |
data.parent_transaction_id | UUID | created only, on refunds: the original transaction being refunded. All zeros when the merchant refunded without referencing it, see Refunds |
data.account_id | UUID | Account associated with the transaction |
data.amount.amount | integer | created only. Amount in minor units (e.g., cents for ZAR) |
data.amount.currency | string | ISO 4217 currency code (e.g., ZAR, KES) |
data.timestamp | RFC3339 | Event creation timestamp |
data.card_id, data.mcc, data.merchant_id, data.merchant_name | string | created only, on card notifications (purchases, refund requests and refunds), at the top level of data. See Card fields |
data.ext_transaction_id | string | created only. The transaction's external reference: for a card payment, the card network's retrieval reference. On a refund, it equals the request's retrieval_ref_number |
data.retrieval_ref_number | string | REVERSAL_REQUEST only. Card network reference for the refund request |
Amount Field Notes
Important
The amount field represents minor units (smallest currency denomination).
Subscription Patterns:
Transaction Lifecycle
Incoming transactions arrive in a created state, they do not only appear once final. A transaction then moves to exactly one terminal event:
Every transaction arrives as created, then settles into exactly one terminal event. The cancelled event is deprecated and no longer emitted.
| Event | Meaning |
|---|---|
created | The transaction has been accepted and is in flight. Every transaction arrives as created first |
succeeded | The transaction completed |
failed | The transaction did not complete: it was declined, or, for a card payment, reversed before it settled. See Reversals |
cancelled | Deprecated. Not emitted by the current system |
- End events can follow immediately. Some transactions are decided at once, for example a card payment you decline at authorization, or an incoming RTC. Their
createdand end event arrive back to back, milliseconds apart. - One exception to the lifecycle: a
REVERSAL_REQUESTiscreatedonly and never gets an end event. See Refund requests.
Card Transactions
Card payments follow the lifecycle above, plus card-specific notifications for reversals and refunds. For the whole flow in order, from authorization to refund, and how to keep your records in sync, see the Card Transaction Lifecycle guide.
| What happened | What you receive |
|---|---|
| Purchase | created with transaction_type: "Card" and the card fields, then succeeded at settlement |
| You declined it at authorization | created, then failed, back to back |
| Reversed before settlement | failed on the original transaction |
| Refund requested by the merchant | created with transaction_type: "REVERSAL_REQUEST", and no end event |
| Refund paid | A new transaction: created with transaction_type: "REVERSAL", then succeeded |
Purchase
A card purchase carries the card and merchant details at the top level of data, alongside the usual fields:
Card fields
Card notifications (purchases, refund requests and refunds) carry the card details at the top level of data, on created only. A field is left out when it has no value.
| Field | Type | Description |
|---|---|---|
data.card_id | UUID | Card used. On refunds, use it to find the cardholder |
data.mcc | string | Merchant category code |
data.merchant_id | string | Merchant identifier |
data.merchant_name | string | Merchant display name |
data.ext_transaction_id | string | Card network reference for the transaction. On a refund, it equals the retrieval_ref_number of the request it settles |
data.retrieval_ref_number | string | REVERSAL_REQUEST only. Card network reference for the refund request |
Reversals
A reversal cancels a card payment before it settles. It happens when the merchant voids the payment, or when the card terminal loses its connection and the card network reverses the payment automatically, usually within a minute.
You receive a failed event for the original transaction, with the same transaction_id as its created. No new transaction is created.
- A reversal before settlement is always for the full amount.
- On a card payment you approved, treat
failedas a reversal: release any hold or pending charge you placed for it.
Refund order
A refund always produces its notifications in this order:
REVERSAL_REQUEST: acreatednotification, as soon as the merchant issues the refund. No money moves yet. See Refund requests.REVERSAL: 1 to 14 days later, once the card network's settlement file confirms the refund, acreatednotification for a new transaction, followed immediately by itssucceeded. Credit the cardholder on thesucceeded. See Refunds.
To link the two, the REVERSAL's ext_transaction_id equals the REVERSAL_REQUEST's retrieval_ref_number.
Refund requests
When a merchant issues a refund, SAVA receives the request before any money moves and sends you a REVERSAL_REQUEST, so you can show the cardholder that a refund is on its way:
-
It is
createdonly. Nosucceededorfailedever follows it. -
Its
transaction_idis always all zeros (00000000-0000-0000-0000-000000000000), so don't use it to deduplicate. Useretrieval_ref_numberinstead. -
Don't credit the cardholder yet. The money moves with the refund itself.
-
Sent once, never retried. A
REVERSAL_REQUESTisn't redelivered if you don't acknowledge it. If you miss it, the refund itself still arrives.
Refunds
On SAVA a refund is called a reversal: a new transaction with transaction_type: "REVERSAL", delivered on the same subject pattern as every other transaction. It never changes the original purchase.
SAVA processes a refund only once the card network's settlement file confirms it, which can take 1 to 14 days after the request. This protects against refunds that are issued and then never paid. The refund then arrives as created followed immediately by succeeded. A refund never fails.
- Partial refunds exist. A refund can be for less than the original purchase, so always book the amount from the refund's own
created. - The parent can be missing.
parent_transaction_idpoints to the original purchase, but it is all zeros when the merchant refunded without referencing it. Usecard_idto find the cardholder instead.
Matching refunds
Handling refunds
- Match the refund to the original purchase with
parent_transaction_id, or to the cardholder withcard_idwhen the parent is all zeros - Match the refund to its earlier
REVERSAL_REQUEST: the refund'sext_transaction_idequals the request'sretrieval_ref_number - Credit the cardholder on the refund's
succeeded, using the amount stored from itscreated - For the full record, including
parent_tx_id, fetch the refund with Get Transaction by ID
Request-Reply Pattern
How It Works
The notification system uses NATS request-reply messaging:
- Sava sends request: Transaction event is published to your subject
- Your service receives: Message arrives at your subscribed handler
- Your service processes: Parse JSON, execute business logic
- Your service responds: Send acknowledgment reply (required within 5s)
Response Requirements
CRITICAL
You MUST respond to every request within 5 seconds:
Note: Use JSON.parse() for decoding incoming JSON messages.
Failure to respond will:
- Trigger automatic redelivery, up to 5 delivery attempts in total (
REVERSAL_REQUESTis sent once and never redelivered) - Cause the same message to be redelivered
- Impact system performance
Missed Notifications
The stream is plain NATS request-reply, not JetStream: your {} reply is the acknowledgement, and a notification that is never acknowledged is not queued for later delivery. If your service misses notifications, for example during downtime or because of a bug that dropped them, contact SAVA to have them replayed. Replayed notifications are identical to the originals, so deduplicate on transaction_id (or retrieval_ref_number for refund requests).
As a safety net, check any transaction still awaiting an end event after a few days by fetching it with Get Transaction by ID.
Queue Subscriptions (recommended)
Recommended
If you run more than one instance of your notification consumer, and most production setups do, subscribe with a queue group so each notification is processed by exactly one instance.
The consumer examples below use a standard subscription: every subscriber receives every notification. That's fine when you run a single instance of your service. If you run more than one, for reliability or to handle more load, use a queue subscription instead.
Same subject, same notification. The only difference is the queue group name your instances subscribe with. NATS picks a member at random, and a group needs no setup on SAVA's side.
A queue subscription adds a queue group name to the subscription. NATS treats every subscriber using the same name as one group, and delivers each notification to exactly one member, chosen at random. Queue groups are standard Core NATS behaviour: nothing to set up on SAVA's side, and the subject, payload and reply rules stay the same.
Why it helps
- No duplicate processing. With a standard subscription, every instance processes every notification, which can, for example, credit the same refund twice.
- Shared load. Adding instances spreads notifications across them instead of multiplying the work.
- Failover. If an instance stops, NATS sends new notifications to the remaining members.
- Safe deploys. Replace instances one at a time: as long as one member is subscribed, notifications keep flowing.
How to use it
- Choose any group name and use the same name on every instance. SAVA never sees it.
- Keep deduplicating. A queue group stops copies between your instances, but SAVA's redelivery (up to 5 attempts) and replays can still deliver a notification more than once, possibly to a different instance. Record processed
transaction_ids (orretrieval_ref_numbers forREVERSAL_REQUEST) in storage every instance shares. - Shut down with
drain(). Draining finishes the notifications an instance has already received before it leaves the group. Closing abruptly drops them, and they only come back through SAVA's redelivery. - Use a separate group per subject, for example one for notifications and another for authorization requests.
Consumer Examples
A basic consumer in each client library: subscribe, process the notification, and acknowledge within 5 seconds. These use a standard subscription, which suits a single instance; if you run more than one, add a queue group as shown in Queue Subscriptions.
Support & Resources
NATS Resources
- NATS.js Documentation: https://nats-io.github.io/nats.js/core/index.html#publish-and-subscribe
- NATS Documentation: https://docs.nats.io
- Request-Reply Pattern: https://docs.nats.io/nats-concepts/core-nats/reqreply
- NATS.ws Client (JavaScript): https://github.com/nats-io/nats.ws
- NATS.py Client (Python): https://github.com/nats-io/nats.py
- NATS Java Client: https://github.com/nats-io/nats.java
- NATS .NET Client (C#): https://github.com/nats-io/nats.net