Adding mada, Apple Pay and STC Pay to a Saudi store or app is done through a payment gateway, not directly with each network. You choose a gateway that supports all three for your merchant account, then set up three things: mada as a card network, Apple Pay with its own merchant ID and certificate, and STC Pay as a separate payment method. Most launch-day failures come from Apple Pay setup and from mada cards being treated like ordinary Visa or Mastercard.
This guide explains what each method needs, the order to set them up in, and how to test before going live. If you are still choosing a provider, start with our comparison of payment gateways in Saudi Arabia.
What do you need before you start?
- A merchant account with a gateway that supports mada, Apple Pay and STC Pay for your business type. Support on the gateway's website is not the same as approval on your account, so confirm which methods are enabled for you.
- A Saudi commercial registration and the documents the gateway asks for during onboarding.
- An Apple Developer account if you will offer Apple Pay inside an iOS app, or on your own website.
- HTTPS on every domain that will show a payment form.
How does mada work online?
mada is Saudi Arabia's national debit network, and most local shoppers carry a mada card. Two details matter for developers:
- Card detection. Many mada cards are co-branded with Visa or Mastercard. The gateway recognises mada cards by their number range and routes them through the mada network. Use the gateway's own card form or SDK so this routing happens correctly; a custom form that only knows "Visa" and "Mastercard" can send a mada card down the wrong path.
- Authentication. Online card payments usually go through a 3-D Secure check, where the bank asks the customer to confirm with a one-time code. Your checkout must handle the redirect or pop-up and return the customer to the right page whether the payment succeeds or fails.
How do you set up Apple Pay?
Apple Pay is the step that takes the longest, because Apple, your gateway and your domain all have to agree.
For an iOS app:
- Create a Merchant ID in your Apple Developer account.
- Create a Payment Processing Certificate for that Merchant ID. Most gateways give you a certificate signing request (CSR) to upload, so the gateway can decrypt the payment data.
- Enable the Apple Pay capability in the app and use the gateway's iOS SDK.
- Include mada in the list of supported networks. Apple states that domestic debit transactions in Saudi Arabia must use the mada network, so merchants that accept debit cards should add it.
For a website:
- Register and verify every domain that shows the Apple Pay button. Apple checks a verification file placed at a fixed `/.well-known/` path on the domain, served over HTTPS.
- Show the button only on devices and browsers that support Apple Pay.
- Test on the real domain; Apple skips domain verification in its sandbox, so a page that works in testing can still fail in production if the file is missing.
One practical catch: if you use two gateways on the same domain, each one may need its own verification file at the same path, which can conflict. Plan for one Apple Pay gateway per domain.
How do you add STC Pay?
STC Pay (now part of STC Bank) is added as its own payment method through gateways that support it. In the usual flow the customer enters the mobile number linked to their wallet and approves the payment with a one-time code or in the STC app. Ask your gateway whether STC Pay is enabled on your account and whether it is available on web, in-app, or both.
In what order should you set things up?
| Step | Method | Why this order |
|---|---|---|
| 1 | Cards and mada | The base of checkout; most customers pay this way |
| 2 | Apple Pay | Needs the card setup plus Apple's certificate and domain checks |
| 3 | STC Pay and other wallets | Separate approvals; add once cards are stable |
| 4 | Buy now, pay later | Tabby or Tamara, for higher-value carts |
How do you test before launch?
- Run every method in the gateway's sandbox with its test cards and test wallets.
- Test failure cases, not just success: a declined card, a cancelled 3-D Secure check, a closed browser mid-payment.
- Confirm your system receives the gateway's webhook and marks the order as paid even if the customer never returns to your site.
- Test refunds, full and partial, from your admin panel.
- After going live, make one small real payment with each method and refund it.
Common mistakes
- Treating mada as Visa or Mastercard in a custom card form.
- Forgetting to verify a new domain or subdomain for Apple Pay.
- Marking orders as paid from the redirect page instead of the server-side webhook.
- Leaving test keys in the production build.
What we do
We integrate payment gateways into stores, apps and booking systems, including mada, Apple Pay, STC Pay and installments, and we test every flow before launch. See our payment gateway integration service, or contact us to discuss your project.