How to Integrate Mada and STC Pay for Lebanese Brands 2026

By the end of this guide, you will have integrated Mada and STC Pay on a Lebanese brand storefront selling into Saudi Arabia in 2026. You will know which gateway fits, what KYC the merchant onboarding wants, how to wire the SDK, how to run the 3DS test plan, and how to settle into your bank account without losing a week to small mistakes most teams make on the first launch.

Key takeaways

• Saudi Arabia's e-commerce market exceeds 12 billion USD with Mada at 22 percent and STC Pay at 12 percent of consumer preference.
• A Lebanese brand without a KSA entity can still launch through a partner-of-record gateway in roughly 2 to 4 weeks.
• Mada and STC Pay must appear at equal visual weight on mobile, not buried under Visa and Mastercard.
• 3DS challenge flows and STC Pay OTP are the two test cases most teams skip and ship broken.

What are Mada and STC Pay, and why does a Lebanese brand need both in 2026?

Mada is Saudi Arabia's national debit card network used by more than 70 percent of Saudi shoppers, and STC Pay is the country's leading digital wallet with over 20 million users on a population of roughly 34.5 million. Any Saudi-targeting storefront without both is leaving 50 percent or more of mobile conversions on the table, per Symloop's 2026 Saudi e-commerce integration guide. For Lebanese brands chasing the GCC market through Voxire's e-commerce GCC service, Mada plus STC Pay is the floor, not a stretch goal.

How does a Lebanese brand without a KSA entity get a Mada and STC Pay merchant account?

This is the question that decides your launch timeline. Three paths work in 2026. The first is registering a Saudi entity, which gives you direct merchant status with HyperPay or Moyasar but adds 6 to 12 weeks of legal work and a local sponsor or 100 percent foreign ownership filing depending on category. The second is going through a partner-of-record gateway such as Tap Payments, which onboards Lebanese merchants under its own KSA license and settles into a USD or LBP account abroad. The third is using Stripe or a global gateway that adds Mada and STC Pay through a backend partner, which is slower to launch and limits Saudi-specific features.

For most Lebanese DTC brands shipping into KSA, the partner-of-record path through Tap Payments is the fastest live, with a 2 to 4 week onboarding window. The trade-off is slightly higher transaction fees, often 2.8 percent plus a fixed SAR fee per transaction versus 2.5 percent for direct merchants. The Voxire web development team has wired this exact path on five Lebanese brands selling into Riyadh and Jeddah, and the fee delta is rounding error compared to the time saved.

What documents and KYC does the gateway actually ask for?

The KYC scope is wider than most Lebanese founders expect. For Tap and Moyasar in 2026, expect to submit your Lebanese commercial registration, a translated trade license, the founder's passport, a utility bill or proof of address less than 3 months old, your storefront URL with working terms and conditions and refund policy in Arabic and English, expected monthly volume in SAR, expected average order value, an Anti-Money-Laundering questionnaire, and bank account details for settlement.

The two items that block the most teams are the Arabic terms and conditions and the live URL. Gateways will not approve a merchant account with a placeholder Shopify checkout link or a refund policy only in English. Build the bilingual policies first, host them on the production URL, then start the application. This saves the back-and-forth cycle that adds 1 to 2 weeks to onboarding.

Lebanese brands lose more time to bilingual policy drafting than to actual gateway integration. Write the Arabic refund policy in week one, not week three.

How do you wire Mada and STC Pay into Shopify, WooCommerce, or a custom Next.js store?

For Shopify, install the official Tap Payments app or the HyperPay app from the Shopify app store, paste your live keys into the configuration, enable Mada and STC Pay in the payment methods section, and set the storefront currency to SAR for Saudi visitors via Shopify Markets. For WooCommerce, install the gateway's plugin from WordPress.org, configure the merchant ID and API keys in the plugin settings, and enable both Mada and STC Pay as separate payment methods so each shows its own logo at checkout.

For a custom Next.js store, use hosted checkout rather than direct API integration on the first launch. Hosted checkout pushes PCI scope to the gateway, which is the single biggest engineering simplification you can take. The flow is straightforward. Create a payment session via the gateway API on your server route, redirect the buyer to the hosted page, receive the success webhook on your server, mark the order as paid, and redirect the buyer to your thank-you page. Voxire's SaaS products team typically wires this in 4 to 6 hours on a Next.js storefront with the official SDK.

What is the 3DS and STC Pay test plan most teams skip?

Run 8 test cases before going live. Test 1 is a successful Mada card payment with frictionless 3DS, where the bank approves without a challenge screen. Test 2 is a Mada card with challenge 3DS, where the bank sends an OTP to the buyer's phone before approving. Test 3 is a Mada card declined for insufficient funds. Test 4 is a Mada card declined for fraud rule. Test 5 is an STC Pay payment with successful OTP authorization. Test 6 is an STC Pay payment where the buyer cancels on the wallet screen. Test 7 is a Visa or Mastercard cross-border payment. Test 8 is a webhook delivery failure that gets retried.

Run every test case on a real iPhone and a real Android device, not just a desktop browser. STC Pay specifically renders different on mobile Safari than on desktop, and the OTP screen has known interaction quirks on older Android versions. Lebanese brands that ship without testing on real devices regularly take down their checkout for 6 to 24 hours on launch day. Our payment gateway Lebanon guide covers the gateway-specific quirks for the Lebanese side of the same stack.

How long does settlement take, and what currency lands in your account?

Mada settlement to a Saudi merchant bank is typically 1 to 2 business days. For a Lebanese brand on a partner-of-record gateway, settlement to your Lebanese or offshore USD account is typically 5 to 7 business days, with a 2 to 5 percent FX spread baked into the conversion from SAR to USD. STC Pay settlements bundle with Mada on most gateways, so you receive one consolidated transfer per cycle.

Reconcile the first 50 orders manually against the gateway settlement file. The number of orders, the gross amount, the gateway fees, and the net settled amount must match. Discrepancies in week one are almost always partial refunds posted in the wrong cycle or chargebacks that have not closed yet. Catching these early saves a finance team weeks of cleanup at month-end.

What is the right launch checklist for day one?

Confirm Mada and STC Pay both appear at the top of the payment selector with logos at equal weight on mobile. Confirm the storefront currency is set to SAR for Saudi visitors. Confirm the success URL and the failure URL are both live and styled. Confirm the webhook endpoint is verified and signing keys are stored in environment variables. Confirm 3DS test cases all pass on iPhone and Android. Confirm Arabic and English receipts are sent on order confirmation. Confirm the support phone number on the receipt is a +966 number or a Saudi WhatsApp Business account.

Day one volume should be capped intentionally. Run paid traffic at 25 percent of planned spend for the first 48 hours. Watch the gateway dashboard for declined transactions, chargeback flags, and webhook failures. Voxire's digital marketing team coordinates the staged spend ramp with the engineering launch on every KSA cutover we have done.

Sources

1. Saudi Arabia E-Commerce 2026: Mada and STC Pay Integration
2. Tap Payments: Saudi Arabia merchant onboarding
3. Mada: official scheme overview

Ready to grow your business online?

Stuck on a step in the Mada or STC Pay integration, or hitting KYC pushback from the gateway? We will do it for you in 48 hours. Talk to our team and we will scope your KSA payment stack against your specific platform and timeline.