Salla Shopify ZATCA Mada Setup

2026-11-12 ยท 10 min read

Migrating a Salla store to Shopify solves platform limits, but it also removes the compliance plumbing that came standard in the Kingdom. Salla issues invoices that pass the regulator's rules out of the box, and mada works with default settings. On Shopify, a correct Salla Shopify ZATCA mada setup has to be rebuilt deliberately, because Shopify ships no Saudi-specific invoice or payment defaults. In ConvFetti's audit set of 50+ GCC stores since 2024, the median conversion rate sits at 1.1%, and in-Kingdom stores that skipped this rebuild left measurable completion points on the table. The complete Shopify CRO guide frames where this fits in a wider program.

This piece is part of our problem series for merchants leaving Salla and Zid, and the central resource is the Salla and Zid to Shopify migration guide for Saudi. Here is the contrarian framing most agencies miss: ZATCA is not a legal checkbox bolted on after launch. It is a conversion variable. An invoice flow that fails compliance also fails the buyer who wants a receipt for a corporate expense, and corporate buyers are a large share of high-AOV orders in Riyadh and Dammam.

Why does ZATCA e-invoicing break after a Salla to Shopify migration?

It breaks because Shopify has no native Fatoora integration, so the invoice generation, QR stamping, and reporting pipeline that the old platform ran by default simply stops existing on the new one. Merchants discover this weeks after launch, when an accountant asks for compliant documents. The regulator's Phase Two integration waves, published on the official portal, extend through 2026 and pull taxpayers down toward SAR 250,000 in annual revenue, which captures most growing D2C brands.

Our October 2026 audit of 23 in-Kingdom Shopify stores (methodology: invoice sampling on live test orders, checkout session recordings, and accountant interviews) found 11 with no ZATCA-compliant invoice path at all. Nine of those had migrated from Salla or Zid in the previous twelve months. None of the eleven had noticed, because B2C buyers rarely demand a stamped invoice at checkout. The exposure surfaces later, in tax filing, in corporate customer disputes, and in refund flows where no compliant document exists to reverse.

The technical gap has three parts. First, Phase Two requires XML invoice generation with the TLV QR code and cryptographic stamp, which Shopify's order confirmations do not produce. Second, clearance or reporting calls to the tax authority's APIs must happen per invoice, on your side of the platform boundary. Third, credit notes for refunds need the same treatment, which is the part merchants forget until a return season arrives. Third-party apps from the Shopify App Store handle all three, but they need configuration against your sandbox credentials, not a one-click install.

How do you enable mada payments on Shopify after leaving Salla?

You enable mada by connecting a gateway that routes Saudi-issued debit BINs over domestic rails, because mada routing is not automatic on every processor. On the old platform, the debit scheme worked without thought. On Shopify, the payment method only appears if your gateway supports it and your Shopify Markets configuration treats the Kingdom as a domestic market rather than a cross-border one. Saudi Central Bank payment statistics show this scheme still dominates in-Kingdom card transaction counts, which means a store whose gateway drops domestic debit BINs is declining the most common card in the country at the door.

The failure mode is subtle. Checkout completes for international Visa and Mastercard test cards, so the store ships, and nobody notices that a Riyad Bank or Al Rajhi debit card gets rejected or routed as an expensive cross-border transaction. In the same October 2026 audit, three of the migrated stores had this exact state: checkout looked healthy in aggregate, but in-Kingdom domestic debit attempts converted near zero. One Riyadh electronics seller was quietly losing an estimated 8,000 to 12,000 SAR monthly before we ran a mada test card through the flow.

Fixing it takes an afternoon. Enable mada in your gateway dashboard (Checkout.com, Moyasar, Tap, and HyperPay all support it in the Kingdom), confirm the BIN routing rules cover domestic debit, and place a real test order with a debit card issued in the Kingdom. For how this payment rail sits inside the wider four-layer payment stack, see payment gateway optimization for UAE and GCC, and for the BNPL layer that rides alongside it, see the Tabby Tamara integration for Saudi.

What does a correct Salla Shopify ZATCA mada setup look like end to end?

A correct setup has five configured layers, in this order: gateway with domestic debit routing, SAR currency and Arabic or English locale mapping through Shopify Markets, a ZATCA Phase Two invoicing app wired to sandbox credentials, BNPL positioned deliberately, and a validation pass with real test transactions before traffic switches. Every layer depends on the one before it, which is why piecemeal setups fail silently.

In our 50+ store audit set, stores that configured all five layers before launch showed checkout completion in the 85-90% band on in-Kingdom traffic, versus 60-65% for stores that discovered the gaps post-launch. Post-launch fixes also cost more than time: the average corrected setup in our data added 2.3% median conversion lift once the payment and invoice paths stopped leaking, but only after weeks of degraded trust signals like USD pricing shown to Riyadh IPs. Currency and locale belong to layer two, and the mechanics live in our multicurrency and Arabic localization guide.

Sequence matters more than speed. A Jeddah home goods brand we advised in January 2026 wired Moyasar and domestic debit routing first, assigned SAR and Arabic through Markets second, installed the invoicing app against ZATCA's sandbox third, and only then pointed DNS. Total developer effort was under two days. The competitor that launches in a weekend and patches compliance in month two pays for it in abandoned corporate orders and an accountant's emergency.

One layer deserves its own sentence: COD. It still runs roughly 20 to 25% of in-Kingdom online transactions per Saudi Central Bank data, and BNPL is pulling volume from COD, not from cards, so a migration that keeps legacy COD assumptions unchanged usually misprices handling fees against the new cost base.

Which gateways route mada and feed ZATCA-ready invoice data?

Checkout.com, Moyasar, Tap, and HyperPay are the practical options in the Kingdom, each supporting mada debit routing and settlement in SAR. Shopify Payments now operates in Saudi Arabia as well, but verify mada interchange coverage and settlement currency on your specific account before assuming parity, because coverage terms have changed more than once since launch. Fees for the third-party processors cluster around 2.5-2.9% plus a fixed fee for cards, with BNPL providers charging 4-6% separately.

The selection criterion most merchants skip is data quality for the invoicing layer. Your invoicing app needs order-level fields (buyer VAT number for corporate orders, line-item tax breakdown, refund events) to arrive cleanly from the gateway and Shopify's order object. Moyasar and Checkout.com expose the cleanest webhooks for this in our implementation experience; where a gateway omits fields, the invoicing app fills gaps with defaults, and defaults are where compliance audits get uncomfortable.

Littledata's 2025 benchmark set of thousands of Shopify stores shows checkout completion running materially higher when payment methods match buyer expectations in-market, which is the commercial argument for domestic routing beyond fees. The compliance argument is separate and unforgiving: ZATCA does not care which processor you chose, only whether the invoice document chain is intact. Pick the gateway that satisfies both, not the one with the lowest headline rate.

How much revenue does an incomplete setup cost after migration?

An incomplete setup costs in three currencies: lost orders, lost trust, and lost margin on the orders that do complete. The lost orders come from rejected domestic debit BINs and currency mismatch. The lost trust comes from buyers who reach for a receipt and find none. Baymard Institute's 2025 checkout usability research, built on 1,500+ hours of testing, attributes roughly 9% of abandonments to missing payment methods, and that share runs higher where a national debit scheme dominates volume, as this one does in the Kingdom.

Here is a failure story we keep in the deck. A Riyadh home goods store, migrated from Salla in October 2025, went live with a card-only gateway and no invoicing app. For six weeks the store ran paid traffic from Snapchat and Google into a checkout that rejected domestic debit cards. Aggregate conversion looked acceptable at 0.9% because cross-border test traffic masked the domestic gap. When we audited in December, domestic debit sessions were converting at under 0.2%. Restoring the correct routing and SAR pricing took three days of work; checkout completion on in-Kingdom sessions moved from 61% to 84% within a month, and the median lift across our corrected-store cohort has been the 2.3% figure cited earlier.

The margin cost is quieter. Cross-border routing on a domestic BIN can add interchange spread per transaction, and refunds processed without compliant credit notes create reconciliation labor that compounds at filing time. None of this appears in the migration budget, because it looks like operations, not like the migration that caused it.

How do you validate the whole build before switching traffic?

You validate with five real test transactions, not five test mode clicks: one domestic debit card, one international card, one BNPL order, one COD order, and one refund generating a credit note. Each test should end with a document you could hand to an accountant and a payment you can trace in the gateway settlement report. Test mode hides exactly the failures this setup is designed to catch, because sandbox cards skip the BIN routing and settlement logic where the problems live.

Run the invoicing app against ZATCA's sandbox first, then a small batch of live invoices in the reporting window, checking the portal for acceptance codes. Confirm SAR and Arabic render for a Riyadh IP and that USD never appears to an in-Kingdom session. Check BNPL widgets render on product and cart, not only at the payment step, since our audit data shows stores surfacing installments upstream capture meaningfully more BNPL share than payment-step-only setups. Timebox the whole pass to one week; in our implementation record, validation almost never finds nothing, and every failure found pre-launch costs a test transaction instead of a customer.

Finally, instrument the checkout funnel by payment method for the first thirty days after cutover. If domestic debit attempts convert far below international cards, the routing fix is still incomplete. If COD acceptance rates sag below the 85-90% band we see on surcharged COD, revisit the handling fee. The funnel breakdown is the only scoreboard that tells you the migration actually finished.

FAQ

Does Shopify support ZATCA e-invoicing natively?

No. Shopify generates order receipts, not ZATCA Phase Two compliant invoices with XML, TLV QR codes, and cryptographic stamps. You need a third-party invoicing app from the Shopify App Store connected to the regulator's APIs, configured against your taxpayer credentials and validated in the sandbox before relying on it live.

Can I keep my old invoicing app after migrating to Shopify?

Usually not directly. Most integrations from the previous platform are built against its APIs and do not port to Shopify's order object. Budget for a Shopify-native ZATCA app and expect to re-enter taxpayer credentials, certificate details, and refund handling rules during setup.

Is mada supported by Shopify Payments in Saudi Arabia?

Shopify Payments operates in the Kingdom, but coverage of the domestic debit scheme and settlement terms should be verified on your account before cutover, since terms have shifted since launch. Third-party gateways like Checkout.com, Moyasar, Tap, and HyperPay offer explicit debit routing and remain the predictable choice for in-Kingdom BIN coverage.

How long does the full build take?

With a developer, roughly two to three days: a few hours for gateway and debit routing, an hour or two for Shopify Markets currency and locale mapping, and a half day for the invoicing app plus sandbox validation. The validation pass with five real test transactions is the part merchants cut, and it is the part that prevents the expensive post-launch discovery.

What happens if I launch without ZATCA-compliant invoices?

B2C sales often continue unaffected, which is why the gap hides. The exposure arrives at tax filing, in corporate customer disputes, and in refund flows that need compliant credit notes. Given the Phase Two wave schedule extends through 2026 and captures smaller taxpayers, treat compliance as a launch requirement rather than a backlog item.

Do I need both Tabby and Tamara after migrating from Salla?

Install both. Tamara is the in-Kingdom default for many Saudi buyers and Tabby covers the cross-GCC base, and the overlap is partial. Both installs are free, and our audit data shows stores carrying both reach 35-41% BNPL transaction share versus 25-28% with one provider, provided the widgets render on product and cart surfaces.