When a mada payment declines at your checkout, do not start with the customer. Start with the decline code. Your gateway records a response code for every failed attempt, and that evidence sorts almost every failure into three owners: the customer's card or bank, the gateway or issuer side, or your own store setup. Read the code first, fix the layer that owns it, and design the failure screen so the order survives even when the card does not.
Matching successful payments to your books is a different job, covered in our guide to mada settlement reconciliation for Saudi stores, and building the integration correctly is covered in our guide to mada integration pitfalls. Here, the store is already trading and the payment just failed.
The short answer: read the decline code first — it sorts the fault into customer, gateway or your store
Every decline leaves evidence: a gateway status, a response code, a timestamp, the method and the device. Open the failed payment in your gateway dashboard before changing any setting. If the code points at the card, the fix belongs to the customer, and your job is a clear message and a fallback. If it points at configuration, the fix is yours. If the issuer was unavailable, the fix is a patient retry.
Step 1 — Find the evidence: where your gateway records the real reason
In Salla, Zid, Shopify, WooCommerce or a custom store, the order timeline usually shows only "payment failed". The real reason sits one layer down, in the gateway record: PayTabs, Moyasar, HyperPay, Paylink and similar dashboards store the status and, where the issuer returns one, the response code. Match the attempt by time, amount and card digits, and note the code and the gateway's wording before you act.
Treat code meanings as gateway property. Paylink's published documentation, for example, defines code 51 as insufficient funds, 54 as an expired card and 91 as the issuer being unavailable — as Paylink documents them. Another gateway may present the same response differently, so never copy a meaning across gateways.
Step 2 — Customer-side causes: card not activated for online use, limits, expiry and issuer blocks
The largest customer-side group is the card never switched on for internet purchases. Paylink's documentation is direct here: its code 49 describes a card not enabled for online transactions, and code 57 covers a function not permitted to the cardholder — the pattern when a card works in a shop but was never activated for online payment in the banking app. Most Saudi banking apps expose an activation control, but the exact path is each bank's own, so tell the customer what to look for, not a memorised menu route.
The rest is ordinary card life. As Paylink documents them: code 51, insufficient funds; code 61, the limit would be exceeded; code 54, an expired card; code 62, a restricted card, including one that does not support the online payment attempted. None is fixed in your dashboard. What you control is how clearly the customer learns which one happened, and what to do next.
Step 3 — The 3-D Secure gap: authentication abandoned, failed or never offered
A second group never reaches an issuer decision. Under 3-D Secure, the issuer authenticates the cardholder — typically through a one-time code or their banking app — before authorisation. Moyasar's official 3-D Secure documentation describes this flow, and notes a successful authentication also shifts fraud liability to the issuer. When the customer closes the bank page, lets the code expire or loses signal, the payment dies as an authentication failure, which looks identical to a decline on a weak order screen.
Separate these in your records. An abandoned authentication is a checkout-experience problem: a redirect that loses the customer's place, a return page that fails to restore the basket, or instructions that never warned a bank step was coming. Test the full round trip on a real phone, on mobile data, in Arabic and English. If the redirect itself is broken, that is a build defect — name it and link it to the integration work.
Step 4 — Store-side causes: mada not enabled properly, test mode, routing and platform checkout limits
Now the uncomfortable group: yours. Check mada is enabled as its own payment method in both store and gateway account, not assumed to ride along with Visa and Mastercard. Check the store runs live credentials, not test keys left over from setup — a store in test mode declines real cards in a way that mimics customer failure. On co-badged cards, check the route: a mada co-badged card pushed down the wrong route can fail where the same card routed as mada would pass, so compare the record's method and route against what the customer presented.
Platform limits are real, but report them honestly. Saudi merchants on Shopify's Community forum report that the native checkout does not pass mada verification tokens for Apple Pay with a third-party gateway, pushing stores to hosted pages. That is merchant-reported experience, not a Shopify policy statement, and one cause among several — confirm it against your own gateway record before treating migration as the answer. The wider build picture is in our guide to web development in Saudi Arabia and our Saudi Arabia overview.
Step 5 — Gateway-side causes: issuer unavailable, suspected fraud and terminal configuration
The third owner is neither you nor the customer. As Paylink documents them, code 91 means the issuer was unavailable when authorisation was attempted, and code 59 records an issuer decline for suspected fraud. Code 58 — a function not permitted to the terminal — points the other way: Paylink ties it to the transaction type or a merchant processing account not correctly configured, making it a gateway-account issue to raise with your provider, code quoted.
Handle these by pattern. One code 91 is weather; a run of them at the same hour is a provider conversation. A suspected-fraud decline is the issuer's call — never advise retrying a card its bank is blocking. Log the code, wording and time, and escalate with evidence.
Fix the message, not just the payment: failure screens that recover the order
Whatever the cause, the customer sees one screen, and "Payment failed" wastes it. A recovering message says, in plain Arabic and English, what most likely happened in terms the customer can act on; keeps the basket, address and delivery option intact; and offers the next step on the same screen. Never show the raw code. Translate it: a card not enabled for online use becomes "Your card is not activated for online shopping — switch it on in your bank app, then try again here."
The fallback ladder: retry, Apple Pay, another card, BNPL and COD — in the right order
Offer fallbacks in order of least effort. First, one guided retry after the specific fix. Second, Apple Pay where your gateway and checkout genuinely support it for that card. Third, another card. Fourth, buy-now-pay-later such as Tabby or Tamara where you already offer it. Last, cash on delivery where you operate it. Each rung keeps the same order alive; an empty cart is not a fallback, it is an exit.
Measure it weekly: payment failure rate by method, by code, by device
Weekly, export failed attempts and group them by method, response code and device. A rising share for one code tells you where to work next; a flat, mixed picture usually means ordinary customer-side failure. Keep the raw gateway wording alongside your groups, and never average mada in with other methods: mada failures have mada-specific causes.
When troubleshooting ends: the signs the checkout itself needs rebuilding
Troubleshooting ends when the same store-side cause survives honest fixes: mada still not presented as its own method, a 3-D Secure return that keeps dropping buyers, or a platform limit your gateway confirms it cannot work around. Then the problem is the build, not the incident queue. A wider technical audit belongs in the same conversation, and structural lessons from our Dubai e-commerce build work apply here too.
Common mistakes stores make while "fixing" declines
First, blaming the customer's balance for every failure. Second, changing settings before reading a single code, destroying the evidence and often the working configuration. Third, copying a code's meaning from another gateway's table and acting on the wrong cause. Fourth, advising repeated retries against an issuer block. Last, fixing the payment and forgetting the message.
FAQ
Where do I find the real reason a mada payment was declined?
In the gateway record for that attempt, not the store order screen. Open the failed transaction in your gateway dashboard, match it by time, amount and card digits, and read the status and response code with that gateway's own documentation as the dictionary.
Why does a mada card work in shops but decline online?
Usually because the card has never been activated for online purchases in the customer's banking app. Paylink's documentation describes this issuer response directly: its code 49 covers a card not enabled for online transactions. The customer switches online use on with their bank, then retries.
Is a 3-D Secure failure the same as a decline?
No. A decline is an issuer decision about the card or account. A 3-D Secure failure happens earlier, during authentication: the customer abandons the bank step, the code expires, or the return to your store breaks. Record them separately, because they have different fixes.
Should I tell the customer the exact decline code?
No. Raw codes help you and your gateway, not the customer. Translate the cause into a plain next step — activate the card for online use, complete the bank verification, wait and retry, or choose another payment method — and keep the basket intact while they do it.
When should I stop troubleshooting and rebuild the checkout?
When the same store-side cause survives honest fixes: mada still not offered as its own method, a 3-D Secure return that keeps losing customers, or a platform limit your gateway confirms in writing. At that point you are maintaining a broken checkout, not troubleshooting incidents.
Get a checkout that stops leaking paid orders (CTA)
If your weekly split shows store-side causes you cannot clear, the fix is a properly built payment layer, not another setting. Our e-commerce web development service builds Saudi checkouts with mada as its own method and failure recovery designed in. Bring a month of decline codes and we will tell you, in an itemised proposal within 24 business hours, which layer loses the orders.
