Card Transaction Lifecycle
How a card payment moves from authorization to settlement, reversal or refund, and how to keep your records in sync.
Overview
A card payment touches three parts of the API:
- Transaction Authorization: you approve or decline the payment in real time.
- Notifications: you're told what happens to it next:
created, thensucceededorfailed. - Account Service: the transaction's permanent record, with its card and merchant details.
This guide follows a card payment through all three, including reversals and refunds, which are the cases integrations most often get wrong. For exact payloads and field definitions, see the Card Transactions section of the Notifications page.
{}.1. A purchase
Authorization
When the cardholder pays, SAVA sends you an authorization request on psvc.transaction.{partner_id}.auth. Reply within 2 seconds: 000 approves, any other code declines. See Transaction Authorization.
This step only applies if you opted in to transaction authorization during partner onboarding. If you didn't, SAVA approves the payment when the account has the funds, and your first message is the created notification below.
If the cardholder's account doesn't have the funds, SAVA declines straight away and you won't receive a request at all.
Created
Once you approve, you receive a created notification with transaction_type: "Card", the amount, and the card details at the top level of data (card_id, mcc, merchant_id, merchant_name, ext_transaction_id). This is the only notification that carries the full details, so store it, keyed by transaction_id.
Show the payment to the cardholder as pending.
Settlement
When the merchant's bank settles the payment, usually within a few days, you receive succeeded with the same transaction_id. It carries no amount: look it up in the created you stored.
A card payment always settles at the amount you authorized. There is no partial settlement; any difference arrives later as a separate refund.
If you decline at authorization, you receive created and then failed, back to back.
2. A reversal (before settlement)
A reversal cancels a card payment that hasn't settled yet. It happens when:
- the merchant voids the payment, or
- the card terminal loses its connection before it gets your approval, and the card network reverses the payment automatically, usually within a minute.
You receive failed on the original transaction, with the same transaction_id as its created. No new transaction is created, and the reversal is always for the full amount.
So a failed on a payment you approved means it was reversed: release any hold or pending charge you placed for it.
3. A refund (after settlement)
A refund returns money for a payment that has already settled. You always receive its notifications in this order:
REVERSAL_REQUEST: acreatednotification, as soon as the merchant issues the refund. No money moves yet.REVERSAL: 1 to 14 days later, once the settlement file confirms the refund, a new transaction. You receive itscreatednotification, followed immediately by itssucceeded. This is when you credit the cardholder.
The REVERSAL's ext_transaction_id equals the REVERSAL_REQUEST's retrieval_ref_number, so you can link the two. The stages in detail:
Refund request
As soon as the merchant issues the refund, SAVA sends you a created notification with transaction_type: "REVERSAL_REQUEST". Despite its name, it's a notification, not a request you answer like a transaction authorization request: acknowledge it with {} like any other notification. Use it to show the cardholder that a refund is on its way, but don't credit them yet.
- It is
createdonly; no end event ever follows it. - Its
transaction_idis always all zeros (00000000-0000-0000-0000-000000000000). Deduplicate on itsretrieval_ref_numberinstead. - It's sent once and never redelivered. If you miss it, the refund itself still arrives.
Settlement file
SAVA waits for the card network's settlement file to confirm the refund before moving any money, which can take 1 to 14 days. This protects against refunds that are issued and then never paid.
Refund
The refund arrives as a new transaction with transaction_type: "REVERSAL", and you receive two notifications for it: created, followed immediately by succeeded. A refund never fails.
- It has its own
transaction_id. The original purchase is not changed. - It can be for less than the original purchase, so credit the amount from the refund's own
created. - Credit the cardholder on its
succeeded.
Reversal or refund? Watch the naming
SAVA calls a refund a reversal: transaction_type: "REVERSAL" always means money coming back after settlement. A card payment reversed before settlement never produces a REVERSAL transaction; it shows up only as failed on the original payment.
| Reversal | Refund | |
|---|---|---|
| When | Before the payment settles | After the payment settles |
| What you receive | A failed notification on the original transaction | A REVERSAL_REQUEST notification, then created and succeeded notifications for a new REVERSAL transaction |
transaction_id | Same as the original | New |
| Amount | Always the full amount | Can be partial |
| Timing | Usually within minutes | 1 to 14 days after the request |
4. Matching a refund to the right cardholder
Refund notifications carry three ways to place the money:
| Field | Tells you |
|---|---|
parent_transaction_id | The original purchase being refunded, when the merchant referenced it |
card_id | The card, and so the cardholder, the refund belongs to. Always present on refund notifications |
ext_transaction_id | Which REVERSAL_REQUEST this refund settles: it equals that request's retrieval_ref_number |
Merchants sometimes refund without referencing the original purchase. The refund then arrives with parent_transaction_id set to all zeros. Use card_id to credit the right cardholder. To suggest which purchase it refunds, look for that card's purchases at the same merchant (merchant_id), which refund notifications also carry.
5. Keeping your records in sync
- Store every
created. End events carry only the transaction ID, account and timestamp. Join eachsucceededorfailedback to its storedcreatedbytransaction_id. A refund'ssucceededlooks exactly like a purchase's on its own. - Acknowledge everything. Reply
{}to every notification within 5 seconds, including types you don't process yet. Unacknowledged notifications are redelivered, up to 5 delivery attempts in total;REVERSAL_REQUESTis the exception and is sent only once. - Deduplicate. Retries and replays can deliver the same notification more than once. Deduplicate on
transaction_id, or onretrieval_ref_numberforREVERSAL_REQUEST. - Fill gaps by fetching. If an end event arrives without its
created, or a payment has had no end event after a few days, fetch it with Get Transaction by ID. A refund's own record includes itsparent_tx_id. To review a card's history, list the account's transactions and filter onmetadata.card_id. - Ask for a replay. If your service missed notifications, for example during downtime, contact SAVA to have them sent again.
6. What to show the cardholder
| Notification | Show the cardholder |
|---|---|
created, Card | Payment pending |
succeeded, Card | Payment complete |
failed, Card | Declined, or reversed if you had approved it. No charge either way |
created, REVERSAL_REQUEST | Refund pending |
succeeded, REVERSAL | Refunded, for the amount on the refund's created |