What is payment gateway integration in Saudi Arabia, and when do you need a developer?
Payment gateway integration in Saudi Arabia is the code that sends a customer from your checkout to a licensed gateway, collects the payment, and tells your system the result in a way it can trust. The gateway talks to the card networks and banks; the integration makes your site or app talk to the gateway.
You need a developer for it when your checkout is not on a hosted platform that already bundles payments. That covers custom-coded websites, booking engines, member portals, marketplaces, B2B ordering tools and every native or cross-platform mobile app. It also covers WooCommerce shops whose plugin half-works: orders stuck as “pending”, Apple Pay missing on iPhone, or refunds that have to be done twice, once in the gateway and once in the shop.
You probably do not need one if you sell on a hosted store platform whose built-in payments already offer mada, Apple Pay and the reports you want. In that case the job is verification and settings, and paying for a custom build would be wasted money.
- Custom site or web app with its own checkout: developer needed
- Flutter or React Native app taking payments: developer needed
- WooCommerce with a working official plugin: usually configuration only
- Hosted Saudi store with built-in payments: usually no developer needed
Which payment methods do Saudi customers expect at checkout?
Start with mada, then cards and Apple Pay, then wallets. mada is the Kingdom's national debit network, and the Saudi Central Bank describes it as a national payment system it owns, launched in 1990. Most Saudi shoppers carry a mada card, so a checkout that treats it as an afterthought loses sales.
After mada come Visa and Mastercard credit cards, then Apple Pay. On its mada page, SAMA notes that mada works with Apple Pay on iPhone and Apple Watch, in stores or online, and with mada Pay on Android devices. On mobile-heavy stores, a one-tap wallet button often matters more than a card form.
STC Pay is a wallet many customers use for transfers and online purchases; whether your gateway supports it, and how, is a question for the gateway's documentation. Buy-now-pay-later providers are another layer some retailers add; they are separate contracts with their own integration. Cash on delivery still exists, but most stores push customers towards prepaid options with a small nudge in the checkout copy.
For a first launch
mada, Visa, Mastercard and Apple Pay cover most shoppers. Add wallets and instalments once you see demand in your own data.
For B2B sellers
Card payments may matter less than bank transfer and payment links attached to quotes; plan both from the start.
How does mada work in an online checkout?
Online, a mada card behaves much like any card: the customer enters the details on the gateway's secure page or fields, completes a 3-D Secure check with their bank, and the gateway returns an approved or declined result. SAMA's own description states that mada enables cards in online transactions at e-commerce outlets through the 3D Secure protocol, so skipping authentication is not an option to plan around.
What changes in practice is detection and labelling. Your checkout should show the mada logo prominently, and the gateway usually needs to know which card brand is being charged so it routes correctly. Some gateways ask you to pass the brand explicitly or to use a separate entity or configuration for mada; others detect it from the card number. Getting this wrong produces confusing declines that customers blame on your shop.
Refunds on mada also deserve a test in the sandbox before launch, because timing and partial-refund support can differ from credit cards. We write a short test script with your gateway's test cards for each brand and run it again before every release that touches the checkout.
How do you add Apple Pay to a Saudi website or app?
Apple Pay needs three things besides the gateway: an Apple merchant ID, verified domains for the web, and a payment processing certificate. Apple's Apple Pay on the web setup guide lists registering a merchant ID, adding and verifying each domain that shows the button, serving pages over HTTPS, and creating the certificate your gateway uses to decrypt payment data.
Several gateways offer a shortcut in which they hold the certificate on your behalf and you only verify your domain in their dashboard. Either way, the merchant ID and the Apple developer account should belong to your business, so the setup survives a change of developer or gateway.
On the web, Apple says Apple Pay works on websites in Safari, so you still need a card form for Chrome and Android shoppers. In iOS apps, the native Apple Pay sheet is used. Apple's App Review Guidelines (4.9) also require apps using Apple Pay to give all material purchase information before the sale and to use its branding correctly, which affects your checkout copy as much as your code.
How to choose a payment gateway for your Saudi business
Choose on method coverage, settlement, developer quality and support, in that order, not on the logo you see most often. We deliberately do not recommend a named gateway here: fees, onboarding speed and supported methods change, and the right choice depends on your business type and bank.
Ask each candidate the same questions and put the answers in one table. The gateway you sign with should be authorised to operate in the Kingdom; ask for its licensing status with the Saudi Central Bank and confirm it yourself before you sign. Then look at the developer documentation with us: a gateway with clear webhooks, a proper sandbox and maintained Flutter and React Native SDKs saves real build time.
- Methods: mada, Visa, Mastercard, Apple Pay, STC Pay, and any you plan to add
- Settlement: into which bank, in riyals, and how many days after the sale
- Fees: per transaction by method, refunds, chargebacks, monthly minimums
- Onboarding: documents needed, time to go live, business categories accepted
- Tech: hosted page, embedded fields, mobile SDKs, webhook signatures, sandbox
- Support: Arabic and English support hours, a named contact for incidents
- Exit: can you export saved-card tokens or customer references if you leave?
Bring the answers to a call and we will score them against your checkout. If two gateways tie, pick the one whose sandbox and documentation are better, because that is what you live with during every future change.
Hosted payment page, embedded fields or direct API: which should you use?
For most Saudi businesses, a hosted payment page or the gateway's embedded secure fields is the right choice, because card numbers never touch your servers. A direct server-to-server API, where your own system receives card data, drags you into much heavier security obligations.
The PCI Security Standards Council states that PCI DSS applies to all entities that store, process or transmit cardholder data, or could affect its security. With a hosted page the customer types card details on the gateway's domain; with embedded fields they type into frames served by the gateway. In both, your compliance effort is far smaller than if card numbers pass through your own code. Your gateway will tell you which self-assessment questionnaire applies.
The trade-off is design control. A redirect to a hosted page is quickest to build but briefly takes the customer off your site. Embedded fields keep the look of your checkout while leaving the card data with the gateway. For apps, the gateway's native SDK gives the smoothest experience.
Choose a hosted page when
You want the fastest launch, the smallest security scope, and you can accept a brief redirect.
Choose embedded fields when
Brand and conversion matter enough to keep the customer on your page, and your gateway offers them.
Avoid a raw card API unless
You have a specific need, a security team and an assessor lined up. Almost no small business does.
3-D Secure, fraud checks and chargebacks in a Saudi payment gateway integration
3-D Secure is the extra step where the customer's bank confirms the payment, usually with a one-time code or an app approval. For mada it is part of how online payments work, and for international cards it shifts some fraud liability away from you when authentication succeeds.
The integration has to cope with the customer leaving mid-challenge, a bank page that times out, or a phone that switches apps and comes back. We never mark an order paid because the customer returned to a success URL; the order is confirmed only by a server-side check or a verified webhook from the gateway. That single rule prevents most “paid but not paid” disputes.
Fraud tools vary by gateway. Useful ones include velocity limits, blocking mismatched country and IP combinations for high-value goods, and manual review for large first orders. Chargebacks still happen, so the admin should keep the evidence a dispute needs: order details, delivery proof and the customer's communication, all tied to the payment reference.
Webhooks, refunds and reconciliation: the part most integrations get wrong
A webhook is the gateway calling your server to report what happened, and it is the only dependable source of truth for payment status. Browsers close, networks drop and customers double-click; the webhook arrives regardless, sometimes more than once and sometimes out of order.
So the listener must verify the gateway's signature, ignore duplicates by event ID, and apply each event only if it moves the payment forward (pending to paid, paid to refunded, never back). Every event is stored raw for audit, then processed. If processing fails, it retries with a delay and alerts someone after a few attempts.
Refunds should start from your admin, not from the gateway dashboard, so that the order, stock and customer record stay in step. Partial refunds need line-level logic: which item, how much, and whether shipping comes back. Reconciliation closes the loop. Each day, the system matches the gateway's settlement report against orders and flags anything paid but not fulfilled, fulfilled but not paid, or settled at an unexpected amount.
- Signature verified on every webhook
- Idempotent processing keyed on the gateway's event ID
- Status only moves forward; late events never undo a refund
- Refunds triggered from your admin with an audit trail
- Daily settlement report matched to orders
SAR settlement, fees and payout timing: what to check before payment gateway integration
Your customers pay in riyals and the gateway settles to your Saudi bank account; ask exactly when and how. Settlement delay, reserves held back for new merchants, and whether fees are deducted before payout all affect cash flow more than a small difference in headline rates.
Fees are set in your contract with the gateway, and they often differ by method: mada, international credit cards and wallets rarely cost the same. Quotes across gateways vary widely, so compare them on your own sales mix. A store where most customers pay by mada should weight that rate heavily; a tourism business with many foreign cards should look closely at international card pricing.
We do not negotiate fees or open merchant accounts; those stay between your business and the gateway. What we do is build the reporting that lets your accountant see gross sales, fees, refunds and net settlement per day, which makes month-end much less painful. If you also need tax invoices for each order, see our ZATCA e-invoicing integration guide, since a payment receipt and a tax invoice are not the same document.
Payment gateway integration in Flutter and React Native apps
In a mobile app, payment gateway integration means using the gateway's Flutter or React Native SDK, or a secure web view of its hosted page, and confirming the result on your server. The app never decides on its own that an order is paid.
Before choosing a gateway for an app, check that its SDK is maintained for current Flutter and React Native versions, supports Apple Pay natively on iOS, and handles 3-D Secure inside the app without dumping the customer into an external browser. An abandoned SDK becomes a blocker at the next OS update.
Apple's rules decide which payment route an iOS app can use. Its App Review Guidelines (3.1.3(e)) say apps selling physical goods or services consumed outside the app must use methods other than in-app purchase, such as Apple Pay or card entry. Digital features unlocked inside the app are a different case and go through Apple's in-app purchase. A delivery app, clinic booking or clothing store therefore uses a gateway; a paid feature inside a learning app may not. We check this against your model before designing screens, because it changes the whole checkout.
Each platform handles payments differently, so the work ranges from configuration to a full custom build. Knowing which bucket you are in saves money before you ask anyone for a quote.
Hosted Saudi platforms bundle payments, and the developer's role is usually theme and app work around them; our Zid store developer and Salla pages cover that. Shopify stores in the Kingdom rely on third-party gateway apps, which our Shopify developer for Saudi stores page explains. WooCommerce uses gateway plugins that are often fine as shipped, but mada labelling, Apple Pay domain files and webhook URLs are where they tend to break.
Custom stores, marketplaces and booking systems are where payment gateway integration in Saudi Arabia is genuine development: checkout screens, a payments service, webhooks, refunds, and reports. Marketplaces add split payouts to sellers, which not every gateway supports; if that is your model, raise it on the first call, and see our multi-vendor marketplace page.
Payment links, cash on delivery and orders taken on WhatsApp
Plenty of Saudi sales still start in a chat or a phone call, and a payment link turns them into prepaid orders without a full checkout. Your staff or an automated flow creates a link for the exact amount, sends it on WhatsApp or SMS, and the order updates itself when the customer pays.
The link must expire, carry the order reference, and be generated from your system rather than typed into the gateway dashboard by hand, or reconciliation falls apart within a week. For repeat use, we add a small screen in your admin where staff choose the order and press one button.
Cash on delivery can live alongside prepaid methods. Common patterns are a COD limit above which prepayment is required, a confirmation message before dispatch, and a prompt at the door offering a link instead of cash. Each reduces failed deliveries without banning COD outright. If WhatsApp is central to your sales, pair this with our WhatsApp automation service.
Saved cards, subscriptions and deposits: payment gateway integration beyond one-off sales
Saved cards and recurring charges work through tokens: the gateway stores the card and gives you a reference that can be charged later with the customer's consent. Your database never sees the card number.
Subscriptions need more than a scheduled charge. You need a retry plan for failed renewals, emails or WhatsApp messages before and after each attempt, a way for customers to update their card, and clear cancellation. If an iOS app offers the subscription through Apple Pay, Apple's guideline 4.9 lists what must be disclosed, including the renewal term, the charges and how to cancel.
Deposits suit clinics, car rentals, venues and custom orders. The pattern is a partial charge at booking and the balance later, either by a second link or by charging a saved token. Refund rules for cancelled deposits belong in your terms, written by you or your lawyer; the system just applies them consistently.
Testing a payment gateway integration before real customers pay
Every serious gateway offers a sandbox with test cards, and a payment integration is not finished until each path has been run there. We write the test list before the code, so the definition of done is agreed in advance.
The list covers successful payments for each brand, declines, 3-D Secure failures and abandonments, duplicate webhooks, a webhook that arrives before the customer returns, full and partial refunds, and a customer who pays twice by double-tapping. On apps, we also test poor connections and switching away mid-payment.
Then comes a small live test with real cards and real money, refunded afterwards, to confirm that settlement reaches your bank account and the reconciliation report matches. Only after that do we remove any “coming soon” message and send traffic to the checkout.
- Sandbox keys separate from live keys, stored as secrets, never in code
- Each payment method tested for success, decline and refund
- Webhook replay and duplicate handling tested
- Live test transaction refunded and matched in the settlement report
How much does payment gateway integration cost in Saudi Arabia?
With us, payment work inside a new store starts from US$750, adding a gateway to an existing custom system starts from US$900, and a mobile app with in-app payments starts from US$600. Other developers' quotes vary widely; the spread usually reflects how much of the webhook, refund and reporting work is included rather than the checkout screen itself.
The price rises with each extra payment method, each extra platform sharing the checkout, saved cards and subscriptions, split payouts for marketplaces, and custom reconciliation reports. It falls when the gateway's plugin or SDK already does most of the job and you only need it configured and tested.
Remember the recurring costs outside our quote: the gateway's per-transaction fees, any monthly fee, and your Apple developer membership (US$99 a year) if you publish an iOS app. For a full picture of website budgets, see website design cost in Saudi Arabia.
Working with an India-based team on your Saudi payment integration
India is 2.5 hours ahead of Saudi Arabia, so your whole office day falls inside ours, and four of your five Sunday–Thursday working days overlap with our week. Calls run on Google Meet or Teams in English, and WhatsApp is open every day.
Payments to us are simple: an itemised quote in US dollars, milestones approved in writing, and payment by Wise, bank wire or PayPal. Invoices are issued from India. Your accountant decides how that payment is treated on your side.
Access is set up so you stay in control. The merchant account, the Apple developer account, the repository and the hosting are all in your business's name. You invite us as users with the least access needed, share sandbox keys first and live keys only for go-live, and remove us whenever you like.
Days 1–5
Call about your checkout, sales mix and gateway shortlist; sandbox access; a written test list for every payment path.
Days 6–10
Payments service and webhook listener in a test environment, first sandbox payments by mada and card, and a demo you can try on your phone.
Worked example: a hypothetical Jeddah abaya boutique adding app payments
Picture a Jeddah abaya boutique, invented for illustration, that sells through a custom website and wants an iPhone and Android app. Today the site accepts cards through a redirect, orders sometimes stay “pending” after payment, and Apple Pay is missing.
The plan starts with a payments service shared by the site and the app. Webhooks from the gateway become the only thing that marks orders paid, which fixes the stuck orders. Apple Pay is added on the website for Safari shoppers after domain verification, and natively in the Flutter app. mada is shown first in both. Custom-tailored pieces take a deposit at order time and a payment link for the balance when the garment is ready.
The admin gains a refunds screen and a daily report that matches settlements to orders, which the boutique's accountant checks weekly. Testing covers every path in the sandbox, then one live purchase per method, each refunded. The shape of this project is typical; the timing for any real shop depends on its existing code and gateway.