The transaction types

🚧

Important

SAMA is currently certifying the mada scheme only. Every capture and void
scenario in this guide, and every row of the matrices in section 7, The scenario matrices, is a mada scenario. The
Visa and Mastercard entries below describe what the protocol supports, not what is in scope
for certification today — build to them if your rollout needs them, but do not expect them to
be exercised at the audit.

The scheme differences decide which message you send

This is the part that catches people. The correct transaction depends on the card scheme, and getting it wrong means a hold that never releases.

📘

Note

"Capture for less than authorised" means a final capture at the delivered figure,
with the issuer releasing the remainder. It is not the withdrawn partial capture mechanism
— see section 8, What your application must survive, where the capture request's type field is always 1.

Read that table twice. Pre Auth Void (6) is mada only. On Visa and Mastercard a void is expressed as a Reversal (9), and on Visa a partial capture is expressed as a Partial Reversal (27) rather than a capture for the lower amount.

Your integration must branch on the scheme returned in the pre-authorisation response (index 27 of the response - section 3). A single code path that always sends 4 and 6 will work perfectly in mada testing and leave Visa holds stranded in production.

Send the wrong one and the payment app tells you. If a transaction does not belong to the
authorisation in front of it — a mada pre-authorisation followed by a Visa Partial Reversal,
say — the response is:

Invalid transaction

That is a useful thing to know two ways round. It means a scheme-branching bug surfaces as a
clear rejection rather than as a silent no-op, so it is worth deliberately provoking during
development. And it means an "Invalid transaction" in production is almost always your own
sequencing, not a host problem: the hold is still open, still needs settling, and the clock
on it is still running.

Suspect Reversal is the Visa and Mastercard path for the 120-second unknown timeout in
section 7 — the row where the terminal stops waiting with no idea what happened. Its request
format and one property that constrains your design are in section 8, What your application must survive.

Capture is final

From the SAMA framework's own definitions:

"for mada AFD transaction the type of capture is Final and will be either equal to the pre-authorized amount or less, However if the amount was lesser then it will result to release the remaining hold amount by the Issuer Bank"

And, unambiguously:

"for mada AFD the Void transaction shall always equal to the Pre-Authorized amount, Hence AFD Partial Void is not supported"

You capture once, for the amount delivered. There is no second capture, no top-up, and no partial void. If you capture for less than the hold, the issuer releases the difference.

---

← Reading the response  ·  Contents  ·  The amounts →