mada payment gateway integration: a guide for Saudi businesses

mada payment gateway integration lets your website or app accept the debit cards most shoppers in Saudi Arabia carry. You do not connect to mada directly; you integrate a payment gateway that supports mada, then add Apple Pay, wallets such as STC Pay and other methods through the same provider. The work that matters is in checkout design, refunds, reconciliation and testing, not just the payment button.

What is mada and why does it matter for online checkout?

mada is Saudi Arabia's national payment network, owned by the Saudi Central Bank (SAMA), and the debit cards issued by Saudi banks run on it. If your checkout does not handle mada cards properly, you turn away a large share of local shoppers.

mada cards are used in shops, online and through Apple Pay. Some mada cards also carry an international scheme logo, so ask your gateway how it identifies and processes mada cards and whether any setting is needed on your side. This is worth confirming early in the project.

How does mada payment gateway integration work?

Your website or app sends the order to a gateway, the customer pays on a secure page or native sheet, and the gateway returns the result to your system. Funds settle to your bank account on the gateway's schedule.

There are three common integration styles. A hosted payment page redirects the customer to the gateway, which keeps card data away from your servers. An embedded form or widget looks more native but still lets the gateway handle card details. A direct API integration gives full control but places much more security responsibility on you. For most businesses, a hosted page or embedded widget is the sensible starting point.

Whatever the style, the critical piece is the server-side confirmation. Your system should only mark an order as paid after it receives and verifies the gateway's notification, not because the customer landed on a success page.

Which gateway should a Saudi business choose?

Choose a gateway that supports the methods your customers use, works with your platform and settles in SAR on terms that suit your cash flow. Several providers serve the Saudi market, including HyperPay, Moyasar and PayTabs, and instalment services such as Tabby and Tamara connect alongside them.

• Supports mada, Visa, Mastercard and Apple Pay, plus any wallets your customers ask for
• Is authorised to operate in Saudi Arabia; ask the provider to confirm its regulatory status with SAMA
• Offers a sandbox, clear API documentation and plugins or SDKs for your platform
• Supports refunds, partial refunds and, if you need them, saved cards and recurring payments
• Provides settlement reports you can match against orders automatically
• States fees, settlement timing and reserve rules clearly in the contract
• Has support hours that cover your trading hours, including Fridays and Saturdays if you trade outside the Sunday to Thursday working week

Ask each gateway how it handles mada specifically. Card networks can have their own rules on authorisation, capture and refunds, and some gateways handle mada differently from international cards, for example around holding an amount and capturing it later. If your business takes deposits, charges after delivery or bills on a schedule, confirm early that the flow you need works with mada cards, not only with Visa and Mastercard.

Do not choose on transaction fees alone. A slightly cheaper gateway with slower settlement, weaker reports or poor support can cost more in staff time.

How do Apple Pay, STC Pay and buy now, pay later fit in?

They usually come through the same gateway as mada, but each needs its own setup and testing. Apple Pay, for example, needs merchant configuration with Apple and your gateway, and domain verification for web checkout.

Wallets such as STC Pay are popular with mobile-first customers, and instalment providers like Tabby and Tamara are widely used by online retailers. Each adds a slightly different flow: wallet confirmation in another app, or an instalment approval step. Add them based on your customers rather than all at once, and check how each one reports refunds and settlements so finance can reconcile them.

What should the checkout and back office handle?

A working payment button is the easy part. The integration also has to cover failures, refunds, invoices and reports, or your team will spend hours fixing orders by hand.

• Arabic and English checkout with right-to-left layout and clear error messages in both languages
• Prices in SAR, with VAT at 15% shown as your adviser requires
• 3-D Secure authentication flows that return customers to the right page
• Handling for abandoned, failed and duplicate payments
• Full and partial refunds from your admin panel, linked to credit notes
• Webhooks or notifications verified on the server before an order is confirmed
• Daily reconciliation between orders, gateway reports and bank settlements
• Invoice output that fits your ZATCA e-invoicing setup

Subscriptions and repeat billing need extra thought. If you charge customers monthly, check whether the gateway supports saved cards and recurring charges for each method you offer, how expired cards are handled, and how customers can update their payment details without calling you.

For example, an online electronics retailer might offer mada, Apple Pay and an instalment option. When a customer returns one item from a two-item order paid in instalments, the system has to issue a partial refund through the right provider, raise a credit note, and update stock. Planning that case before launch avoids a manual workaround that lasts for years.

What about security and card data?

Keep card data off your servers wherever possible. Using the gateway's hosted page or tokenised fields reduces your exposure and your compliance burden under the card industry's PCI DSS standard.

Beyond cards, your checkout collects names, phone numbers and addresses, which are personal data under the Saudi Personal Data Protection Law (PDPL). Collect only what you need, explain it in your privacy notice, and confirm your obligations with your legal adviser. On the technical side, use HTTPS everywhere, keep gateway keys in a secure vault rather than in code, restrict who can issue refunds, and log every payment action.

How is a payment integration project usually run?

Payment work follows the same disciplined path as any other build: discovery, a written scope, phased releases, thorough testing and a documented handover.

We start with a video-call workshop with your finance and operations teams to map every payment and refund case. That becomes a written scope listing methods, flows and reports. A named lead engineer runs delivery in two-week sprints with a demo every sprint, usually starting with mada and Apple Pay in the sandbox before adding wallets or instalments.

Testing covers successful, failed, cancelled and refunded payments in both languages and on common devices, then a controlled go-live with small real transactions. At handover, code, gateway settings and cloud accounts are registered to your company. If you are building a new store or portal, see our web development company page for Saudi Arabia and our web development service; for in-app payments see app development.

Frequently asked questions

Can I accept mada without a payment gateway?

For online payments, you normally go through a payment gateway or payment service provider that supports mada. Talk to your bank and the gateway about which option fits your business.

How long does mada integration take?

The technical connection is often the shorter part. Merchant onboarding with the gateway, Apple Pay setup, refund flows and reconciliation take longer, so start the gateway application early.

Do I need a separate integration for Apple Pay?

Usually Apple Pay runs through the same gateway, but it needs its own merchant setup, domain verification for web and testing on Apple devices.

Can one integration serve my website and app?

Yes. A shared backend can handle orders and payment confirmations for both, while the website and app each use the gateway's web or mobile SDK.

If you are adding mada, Apple Pay or wallets to a website or app, talk to us and we will map your payment and refund flows before any code is written.