API References

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:

Each notification is published to
workqueue.notification.<partner_id>.transaction.<transaction_id>

You don't know transaction IDs ahead of time, so subscribe with the wildcard to receive every transaction:

Subscribe with
workqueue.notification.<partner_id>.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:

What you subscribe to
workqueue.notification.950db7cb-febe-4c5e-a447-0373a2ab001b.transaction.*
What individual messages arrive on
workqueue.notification.950db7cb-febe-4c5e-a447-0373a2ab001b.transaction.2f805c37-ba32-43c5-b5f8-4d8970f4bdd9
workqueue.notification.52c844f1-17b3-4aa5-9a59-f4f7eaca22c3.transaction.2992b67d-8a5b-40b7-abeb-7e8e11742c99

Message Payload

All messages share this envelope. A created event carries the full transaction details:

created event
{
  "event": "created",
  "data": {
    "notification_type": "transaction",
    "transaction_id": "2f805c37-ba32-43c5-b5f8-4d8970f4bdd9",
    "transaction_type": "EFT",
    "account_id": "9c09dcf2-ee29-4d85-a6c5-843ea8113509",
    "amount": {
      "amount": 10000000,
      "currency": "ZAR"
    },
    "timestamp": "2025-10-09T10:51:01.862974041+02:00"
  }
}

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:

succeeded event
{
  "event": "succeeded",
  "data": {
    "notification_type": "transaction",
    "transaction_id": "2f805c37-ba32-43c5-b5f8-4d8970f4bdd9",
    "account_id": "9c09dcf2-ee29-4d85-a6c5-843ea8113509",
    "timestamp": "2025-10-09T10:51:02.104512337+02:00"
  }
}

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

FieldTypeDescription
eventstringEvent lifecycle phase: created, succeeded, failed (cancelled is deprecated, see Transaction Lifecycle)
data.notification_typestringAlways "transaction" for this stream
data.transaction_idUUIDUnique identifier for the transaction. Always all zeros on REVERSAL_REQUEST, see Refund requests
data.transaction_typestringcreated 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_idUUIDcreated only, on refunds: the original transaction being refunded. All zeros when the merchant refunded without referencing it, see Refunds
data.account_idUUIDAccount associated with the transaction
data.amount.amountintegercreated only. Amount in minor units (e.g., cents for ZAR)
data.amount.currencystringISO 4217 currency code (e.g., ZAR, KES)
data.timestampRFC3339Event creation timestamp
data.card_id, data.mcc, data.merchant_id, data.merchant_namestringcreated only, on card notifications (purchases, refund requests and refunds), at the top level of data. See Card fields
data.ext_transaction_idstringcreated 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_numberstringREVERSAL_REQUEST only. Card network reference for the refund request

Amount Field Notes

Important

The amount field represents minor units (smallest currency denomination).

Subscription Patterns:

// Listen to all transactions for your partner
const myPartnerSubject = `workqueue.notification.${partnerId}.transaction.*`;
 
// Listen to all notifications (any type) for your partner
const allPartnerNotifications = `workqueue.notification.${partnerId}.>`;

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:

createdarrives firstsucceededterminalfailedterminal

Every transaction arrives as created, then settles into exactly one terminal event. The cancelled event is deprecated and no longer emitted.

EventMeaning
createdThe transaction has been accepted and is in flight. Every transaction arrives as created first
succeededThe transaction completed
failedThe transaction did not complete: it was declined, or, for a card payment, reversed before it settled. See Reversals
cancelledDeprecated. 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 created and end event arrive back to back, milliseconds apart.
  • One exception to the lifecycle: a REVERSAL_REQUEST is created only 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 happenedWhat you receive
Purchasecreated with transaction_type: "Card" and the card fields, then succeeded at settlement
You declined it at authorizationcreated, then failed, back to back
Reversed before settlementfailed on the original transaction
Refund requested by the merchantcreated with transaction_type: "REVERSAL_REQUEST", and no end event
Refund paidA 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 purchase notification
{
  "event": "created",
  "data": {
    "notification_type": "transaction",
    "transaction_id": "9f1c2b7a-3d4e-41b9-8a21-6e7d5c4b3a20",
    "transaction_type": "Card",
    "account_id": "1b6d9f30-2a44-4f2e-9f67-0b3a8d9c7e51",
    "amount": {
      "amount": 27850,
      "currency": "ZAR"
    },
    "ext_transaction_id": "492817560143",
    "card_id": "c4a28d91-6f73-4b2f-a95d-3e8c1f709a62",
    "mcc": "5411",
    "merchant_id": "987654321098765",
    "merchant_name": "DEMO MERCHANT STORE",
    "timestamp": "2026-02-09T14:12:33.456Z"
  }
}

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.

FieldTypeDescription
data.card_idUUIDCard used. On refunds, use it to find the cardholder
data.mccstringMerchant category code
data.merchant_idstringMerchant identifier
data.merchant_namestringMerchant display name
data.ext_transaction_idstringCard network reference for the transaction. On a refund, it equals the retrieval_ref_number of the request it settles
data.retrieval_ref_numberstringREVERSAL_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 failed as a reversal: release any hold or pending charge you placed for it.

Refund order

A refund always produces its notifications in this order:

  1. REVERSAL_REQUEST: a created notification, as soon as the merchant issues the refund. No money moves yet. See Refund requests.
  2. REVERSAL: 1 to 14 days later, once the card network's settlement file confirms the refund, a created notification for a new transaction, followed immediately by its succeeded. Credit the cardholder on the succeeded. 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:

Refund request notification
{
  "event": "created",
  "data": {
    "notification_type": "transaction",
    "transaction_id": "00000000-0000-0000-0000-000000000000",
    "transaction_type": "REVERSAL_REQUEST",
    "parent_transaction_id": "00000000-0000-0000-0000-000000000000",
    "account_id": "1b6d9f30-2a44-4f2e-9f67-0b3a8d9c7e51",
    "card_id": "c4a28d91-6f73-4b2f-a95d-3e8c1f709a62",
    "amount": {
      "amount": 10000,
      "currency": "ZAR"
    },
    "mcc": "5411",
    "merchant_id": "987654321098765",
    "merchant_name": "DEMO MERCHANT STORE",
    "retrieval_ref_number": "492817560177",
    "timestamp": "2026-02-09T15:02:10.000Z"
  }
}
  • It is created only. No succeeded or failed ever follows it.

  • Its transaction_id is always all zeros (00000000-0000-0000-0000-000000000000), so don't use it to deduplicate. Use retrieval_ref_number instead.

  • Don't credit the cardholder yet. The money moves with the refund itself.

  • Sent once, never retried. A REVERSAL_REQUEST isn'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.

Refund notification (R100 refund against a previous purchase)
{
  "event": "created",
  "data": {
    "notification_type": "transaction",
    "transaction_id": "3c9d8f21-7b4a-4e6d-9f10-2a8b5c7d4e90",
    "transaction_type": "REVERSAL",
    "parent_transaction_id": "9f1c2b7a-3d4e-41b9-8a21-6e7d5c4b3a20",
    "account_id": "1b6d9f30-2a44-4f2e-9f67-0b3a8d9c7e51",
    "card_id": "c4a28d91-6f73-4b2f-a95d-3e8c1f709a62",
    "amount": {
      "amount": 10000,
      "currency": "ZAR"
    },
    "mcc": "5411",
    "merchant_id": "987654321098765",
    "merchant_name": "DEMO MERCHANT STORE",
    "ext_transaction_id": "492817560177",
    "timestamp": "2026-02-10T08:15:00.000Z"
  }
}
  • 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_id points to the original purchase, but it is all zeros when the merchant refunded without referencing it. Use card_id to find the cardholder instead.

Matching refunds

Handling refunds

  • Match the refund to the original purchase with parent_transaction_id, or to the cardholder with card_id when the parent is all zeros
  • Match the refund to its earlier REVERSAL_REQUEST: the refund's ext_transaction_id equals the request's retrieval_ref_number
  • Credit the cardholder on the refund's succeeded, using the amount stored from its created
  • 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:

  1. Sava sends request: Transaction event is published to your subject
  2. Your service receives: Message arrives at your subscribed handler
  3. Your service processes: Parse JSON, execute business logic
  4. Your service responds: Send acknowledgment reply (required within 5s)

Response Requirements

CRITICAL

You MUST respond to every request within 5 seconds:

// Simple acknowledgment (success)
msg.respond(JSON.stringify({}));

Note: Use JSON.parse() for decoding incoming JSON messages.

Failure to respond will:

  • Trigger automatic redelivery, up to 5 delivery attempts in total (REVERSAL_REQUEST is 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.

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.

Standard subscription
What the examples on this page use
SAVA
1 notification
NATS
Instance A
processes it
Instance B
processes it
Instance C
processes it
Every instance gets a copy: processed 3 times
Queue subscription
All instances join the group "notification-workers"
SAVA
1 notification
NATS
Instance A
not sent
Instance B
processes it
Instance C
not sent
NATS picks one member: processed once

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 (or retrieval_ref_numbers for REVERSAL_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.
Queue subscription
import { connect } from "@nats-io/transport-node";
import { jwtAuthenticator } from "@nats-io/nats-core";
 
const nc = await connect({
  servers: ["wss://hermes.sava.africa"],
  authenticator: jwtAuthenticator(jwt, seed),
});
 
const subject = `workqueue.notification.${partnerId}.transaction.*`;
 
// Same queue group name on every instance: each notification goes to one of them.
const sub = nc.subscribe(subject, { queue: "notification-workers" });
 
(async () => {
  for await (const msg of sub) {
    try {
      const notification = msg.json<Notification>();
 
      // Skip anything already processed. Keep processed IDs in shared storage.
      await processOnce(notification);
 
      // Acknowledge within 5 seconds.
      msg.respond(JSON.stringify({}));
    } catch (err) {
      // No reply: SAVA redelivers, up to 5 delivery attempts in total.
      console.error("Failed to process notification:", err);
    }
  }
})();
 
// Finish in-flight notifications before leaving the group.
for (const signal of ["SIGINT", "SIGTERM"] as const) {
  process.on(signal, async () => {
    await nc.drain();
    process.exit(0);
  });
}

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.

Notification consumer
import { connect, jwtAuthenticator, JSONCodec } from "nats.ws";
 
async function main() {
  // Connection initialisation truncated for brevity
  const m = { json: (data) => JSON.parse(data) };
 
  // Subscribe to partner's transactions
  const subject = `workqueue.notification.${config.partnerId}.transaction.*`;
 
  const sub = nc.subscribe(subject, {
    callback: async (err, msg) => {
      if (err) {
        console.error("Subscription error:", err);
        return;
      }
 
      // Parse notification (automatically decoded from JSON)
      const notification = m.json();
 
      console.log(`Transaction ${notification.data.transaction_id}: ${notification.event}`);
      // Only created events carry the type and amount
      if (notification.event === "created") {
        console.log(`  Type: ${notification.data.transaction_type}`);
        console.log(`  Amount: ${notification.data.amount.currency} ${notification.data.amount.amount / 100}`);
      }
 
      // Process notification
      await processTransaction(notification);
 
      // CRITICAL: Send response (automatically encoded to JSON)
      msg.respond(JSON.stringify({}));
    }
  });
 
  console.log(`Listening for notifications on: ${subject}`);
 
  // Cleanup setup if required
}
 
async function processTransaction(notification) {
  // Your business logic here
}

Support & Resources

NATS Resources