Transaction Authorization
Real-time card transaction authorization over NATS request-reply, with approval decisions made by your platform.
Overview
Transaction authorization lets your platform control card usage in real time: every card transaction is sent to you for an approve or decline decision before it completes.
The flow uses NATS request-reply. Your platform subscribes to an authorization subject and must respond within 2 seconds. If no response arrives in that window, the transaction is automatically declined.
Opt-in during partner onboarding
Transaction authorization is optional. You choose whether to use it when you onboard as a partner with SAVA. If you opt in, every card payment is sent to you for a decision. If you don't, SAVA authorizes card payments for you: a payment is approved when the cardholder's account has the funds, and you still receive the usual notifications.
Authorization sequence
The real-time flow for a single transaction:
SAVA reserves the funds, then asks the partner to approve or decline. The partner must reply within 2 seconds with an ISO 8583:1993 code, where 000 approves and anything else declines. No reply within the window means an automatic decline.
Authorization decision factors
Within the 2 second window, your platform can apply any combination of checks:
| Factor | Description |
|---|---|
| Internal balance check | Validates the user has sufficient funds in your internal ledger |
| MCC whitelisting | Validates the transaction MCC against approved merchant category codes |
| Merchant ID whitelisting | Validates the transaction merchant ID against approved merchants |
| Card controls | Applies configured limits and features (daily, weekly, monthly, geographic, and so on) |
| Custom logic | Any authorization rules specific to your product |
MCC and merchant ID whitelisting
Partners are required to maintain whitelists for both Merchant Category Codes (MCC) and merchant IDs to control where card transactions can be authorized. During authorization, validate the incoming mcc and merchantID fields against these lists.
- MCC whitelisting: maintain a list of approved merchant category codes, for example
5411(grocery stores),5541(service stations),5812(restaurants). Decline transactions at non-approved MCCs with code119(transaction not permitted to cardholder). - Merchant ID whitelisting: maintain a list of approved merchant IDs for specific use cases, useful for restricting transactions to specific partner merchants. Decline non-approved merchants with code
119.
Authorization request
Your platform receives authorization requests on this subject:
Subject: psvc.transaction.{partner_id}.auth
| Field | Type | Description |
|---|---|---|
transaction_id | string | UUID of the transaction |
retrievalRefNumber | string | Retrieval reference number for the transaction |
account_id | string | UUID of the account the card is tied to |
card_id | string | UUID of the card being used |
timestamp | string | Transaction timestamp (RFC 3339) |
transactionAmount | number | Amount in minor units (cents) |
mcc | string | Merchant category code |
merchantID | string | Merchant identifier |
merchantName | string | Merchant display name |
transactionCurrencyCode | string | ISO 4217 numeric currency code, e.g. 710 for ZAR |
Authorization response
Reply on the NATS message itself (the reply subject is handled by the request-reply pattern). The decision field must be an ISO 8583:1993 3-digit response code: 000 approves, any other code declines.
| Field | Type | Required | Description |
|---|---|---|---|
transaction_id | string | required | Echo of the request's transaction_id |
retrievalRefNumber | string | required | Echo of the request's retrievalRefNumber |
decision | string | required | ISO 8583:1993 3-digit response code. 000 approves, anything else declines |
reason | string | required | Human-readable reason for the decision |
processed_at | string | required | When your platform processed the request (RFC 3339) |
After you reply, the transaction's notifications follow: created, then succeeded when it settles, or failed if you declined it or it was reversed before settling. See the Card Transaction Lifecycle guide.
Implementation example
Subscribing to authorization requests and responding. Pick your client library. These use a standard subscription, which suits a single instance; if you run more than one, use a queue group as shown in Queue Subscriptions.
Always respond
Respond to every request, including failures inside your handler. A missed reply counts as a timeout and the transaction declines with no reason attached, which is harder to debug than an explicit 100.
Queue Subscriptions (recommended)
Recommended
If you run more than one instance of your authorization service, and most production setups do, subscribe with a queue group so each payment is decided by exactly one instance.
The implementation examples above use a standard subscription: every subscriber receives every authorization request. That's fine when you run a single instance. With more than one, every instance decides and replies to every payment. SAVA uses the first reply and ignores the rest, so your instances can disagree (one approves, another declines) and each payment is evaluated several times.
Same subject, same authorization request. 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 request to exactly one member, chosen at random. Queue groups are standard Core NATS behaviour: the subject, payload, response format and 2-second limit stay the same.
Why it helps
- One decision per payment. Only one instance evaluates and answers each request.
- Shared load. Adding instances spreads requests across them instead of multiplying the work.
- Failover. If an instance stops, NATS sends new requests to the remaining members.
- Safe deploys. Replace instances one at a time: as long as one member is subscribed, payments keep being authorized.
What to know for authorization
- Each request gets one chance. SAVA sends a request once and waits 2 seconds. It doesn't retry or try another instance, so a slow or stuck instance means a declined payment. Reply with a decline yourself before the 2 seconds run out rather than letting it time out.
- Keep at least one instance subscribed. If no instance is subscribed, NATS reports no responders and the payment is declined immediately. Use rolling deploys.
- Shut down with
drain(). Draining finishes the requests an instance has already received before it leaves the group. Closing abruptly drops them, and those payments are declined. - Share balances and limits. Any instance can receive any card's request, so keep balances, limits and card state in storage every instance shares. Two taps on the same card can reach two instances at once, so make the balance check and the reservation one atomic step.
- Use a separate group from notifications, and don't run another subscriber on the authorization subject that replies: it receives every request as well, and its reply races yours.
- Choose any group name and use the same name on every instance. SAVA never sees it.
ISO 8583:1993 response codes
The following response codes are recommended during transaction authorization.
Recommended partner response codes
| Code | Description | Partner use case |
|---|---|---|
000 | approved | Transaction approved |
100 | do not honour | Generic decline (catch-all) |
101 | expired card | Card expired in partner system |
102 | suspected fraud | Partner fraud rules triggered |
104 | restricted card | Card frozen or blocked by partner |
110 | invalid amount | Amount validation failed (too low or too high) |
116 | not sufficient funds | User balance insufficient |
119 | transaction not permitted to cardholder | MCC restrictions, card controls blocked |
121 | exceeds withdrawal amount limit | Daily, weekly, or monthly limits exceeded |
122 | security violation | Security rule triggered |
123 | exceeds withdrawal frequency limit | Velocity checks (too many transactions) |
125 | card not effective | Card not yet activated |
Simplified core response set
If you want to start with a minimal set:
| Code | Meaning |
|---|---|
000 | Approved |
100 | Do Not Honour (generic decline) |
116 | Not Sufficient Funds |
119 | Transaction Not Permitted (MCC or controls) |
121 | Exceeds Amount Limit |
104 | Restricted Card |
123 | Exceeds Frequency Limit |
Technical requirements
| Requirement | Description |
|---|---|
| Communication protocol | NATS request-reply over wss://hermes.sava.africa |
| Authentication method | JWT + NKey authentication |
| Partner identification | Partner ID in the subject path |
| Authorization subject | psvc.transaction.{partner_id}.auth |
| Response timeout | 2 seconds (transactions auto-declined if exceeded) |
| Response code format | ISO 8583:1993 3-digit codes |