API References

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:

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 · Purchase
The cardholder pays and the payment settles.
Cardholder pays
Request · you replyAuthorization request
Only if you opted in. Reply 000 within 2 seconds to approve; any other code declines.
instantly
You approve
Notificationcreatedtransaction_type: Card
The payment, with the amount and card details. Save it by its transaction_id: later notifications refer back to it.
usually within days
Merchant’s bank settles
Notificationsucceeded
Same transaction_id as created, with no amount. Mark the payment as complete.
2 · Reversal, before settlement
The payment is cancelled before it settles. You get one notification; no new transaction is created.
Payment approved, not yet settled
Notificationcreatedtransaction_type: Card
The purchase notification from lane 1, already received.
usually within minutes
Merchant voids it, or the terminal times out
Notificationfailed
Same transaction_id as the purchase. The whole payment is cancelled, so release any funds you were holding for it.
3 · Refund, after settlement
Money comes back as a new transaction. The original purchase is unchanged.
Merchant issues a refund
Notificationcreatedtransaction_type: REVERSAL_REQUEST
A refund is on its way. Show it as pending, but don’t credit yet. Sent once; nothing follows for it.
1 to 14 days
Settlement file confirms it
Notificationcreatedtransaction_type: REVERSAL
The refund, as a new transaction with its own transaction_id. Save it.
back to back
Immediately after
Notificationsucceeded
Same transaction_id as the REVERSAL. Credit the cardholder.
request you reply to (not a notification)created notificationsucceeded notificationfailed notificationAcknowledge every notification with {}.

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:

  1. REVERSAL_REQUEST: a created notification, as soon as the merchant issues the refund. No money moves yet.
  2. REVERSAL: 1 to 14 days later, once the settlement file confirms the refund, a new transaction. You receive its created notification, followed immediately by its succeeded. 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 created only; no end event ever follows it.
  • Its transaction_id is always all zeros (00000000-0000-0000-0000-000000000000). Deduplicate on its retrieval_ref_number instead.
  • 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.

ReversalRefund
WhenBefore the payment settlesAfter the payment settles
What you receiveA failed notification on the original transactionA REVERSAL_REQUEST notification, then created and succeeded notifications for a new REVERSAL transaction
transaction_idSame as the originalNew
AmountAlways the full amountCan be partial
TimingUsually within minutes1 to 14 days after the request

4. Matching a refund to the right cardholder

Refund notifications carry three ways to place the money:

FieldTells you
parent_transaction_idThe original purchase being refunded, when the merchant referenced it
card_idThe card, and so the cardholder, the refund belongs to. Always present on refund notifications
ext_transaction_idWhich 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

  1. Store every created. End events carry only the transaction ID, account and timestamp. Join each succeeded or failed back to its stored created by transaction_id. A refund's succeeded looks exactly like a purchase's on its own.
  2. 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_REQUEST is the exception and is sent only once.
  3. Deduplicate. Retries and replays can deliver the same notification more than once. Deduplicate on transaction_id, or on retrieval_ref_number for REVERSAL_REQUEST.
  4. 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 its parent_tx_id. To review a card's history, list the account's transactions and filter on metadata.card_id.
  5. 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

NotificationShow the cardholder
created, CardPayment pending
succeeded, CardPayment complete
failed, CardDeclined, or reversed if you had approved it. No charge either way
created, REVERSAL_REQUESTRefund pending
succeeded, REVERSALRefunded, for the amount on the refund's created

On this page