The first thing Saudi Arabia teaches developers who arrive with a Western payment stack is that Stripe does not work for Mada.

Stripe is not SAMA (Saudi Central Bank)-licensed for Mada acquiring in Saudi Arabia. A Saudi-resident merchant integrating Stripe will accept international credit cards while missing Mada, STC Pay, Apple Pay through Mada, and Buy Now, Pay Later (BNPL) payment methods that Saudi consumers actually use.

In Saudi Arabia's 2026 payment environment, where more than 80% of transactions are cashless, a Western-first checkout leaves significant payment coverage gaps.

This guide explains the complete payment gateway integration Saudi Arabia developers need—from gateway selection and Mada routing to Apple Pay behaviour, BNPL implementation, webhook architecture, and ZATCA integration.

For the wider Saudi compliance framework surrounding payment systems, read our guide on ZATCA-compliant app development Saudi Arabia.

---

The Saudi payment stack — what your checkout must support in 2026

A production-ready Saudi checkout is not simply Visa and Mastercard.

The minimum payment stack should support:

1. Mada
2. Apple Pay
3. STC Pay
4. Visa & Mastercard
5. BNPL (Tabby + Tamara)
6. SADAD (where applicable)

Vision 2030's cashless economy initiative has fundamentally changed Saudi consumer payment behaviour.

For developers, the implication is straightforward: payment method coverage matters as much as checkout performance.

---

Mada

Mada is Saudi Arabia's domestic debit card network operated by Saudi Payments.

It represents the dominant payment method for Saudi consumers and should always appear first during checkout.

---

Apple Pay

Apple Pay enjoys strong consumer adoption across Saudi Arabia.

Unlike international implementations, Saudi Apple Pay commonly routes through Mada debit cards rather than international credit card networks.

---

STC Pay

STC Pay is Saudi Telecom Company's digital wallet.

It is particularly common among mobile-first consumers.

---

Visa and Mastercard

International cards remain important for expatriates, business purchases, and international customers.

They complement—not replace—Mada.

---

BNPL (Buy Now, Pay Later)

BNPL providers Tabby and Tamara influence a significant percentage of Saudi online purchases.

Developers should treat BNPL as part of the shopping experience rather than merely another payment option.

---

SADAD

SADAD serves subscription billing, insurance, government payments, utilities, and invoice-based payment workflows.

Consumer retail checkouts rarely require it.

---

SAMA licensing — why your gateway choice determines your Mada access

SAMA regulates payment service providers operating inside Saudi Arabia.

Merchants do not require their own SAMA licence.

Instead, they inherit compliance by integrating a SAMA-licensed gateway.

As of 2026, major SAMA-licensed payment providers include:

• HyperPay
• Moyasar
• PayTabs
• Tap Payments
• Amazon Payment Services (APS)

This decision determines everything that follows.

Gateway licensing affects Mada availability, settlement, authentication flows, PCI-DSS (Payment Card Industry Data Security Standard) compliance, and payment acceptance behaviour.

Stripe remains an excellent international gateway but is not SAMA-licensed for Mada acquiring in Saudi Arabia.

For Saudi B2C businesses, that limitation prevents it from serving as the primary gateway.

---

Mada — the integration foundation every developer must get right first

Many developers mistakenly treat Mada as another Visa card.

It is not.

Mada operates through Saudi Payments with dedicated Bank Identification Number (BIN) ranges issued by Saudi banks.

The payment gateway identifies those BINs and routes transactions through the domestic Mada network rather than international Visa or Mastercard infrastructure.

---

Understanding Mada 3DS

3DS (Three-Domain Secure) Version 2 is mandatory for modern Saudi card authentication.

Saudi banks generally authenticate Mada transactions through One-Time Password (OTP) verification delivered via SMS.

The payment gateway orchestrates authentication.

Developers should never intercept or attempt to customise the bank's authentication experience.

---

Refund behaviour

Mada refunds typically complete within 24 hours to three business days.

Applications should communicate these expectations clearly instead of promising immediate refunds.

---

Sandbox testing

Every SAMA-licensed payment gateway provides Mada sandbox cards.

These cards simulate Saudi-specific routing, authentication, settlement, and failure behaviour.

Testing only with Visa sandbox cards creates false confidence before production deployment.

Which SAMA-licensed gateway for which Saudi product

Choosing the right gateway is less about features and more about how your business operates.

Approval rates, settlement behaviour, geographic coverage, onboarding speed, and supported Saudi payment methods all influence the final decision.

For a commercial comparison covering merchant fees, settlement terms, and feature differences, read our guide on Tap Payments vs HyperPay vs Moyasar Saudi Arabia.

---

HyperPay — highest Mada approval rates for established Saudi businesses

HyperPay has direct acquiring relationships with multiple Saudi banks.

That translates into consistently high Mada authorization rates for merchants processing significant payment volumes.

HyperPay supports:

• Mada
• Visa
• Mastercard
• Apple Pay
• STC Pay
• Tabby
• Tamara
• SARIE
• ZATCA integrations

Its onboarding process is more enterprise-oriented than most Saudi gateways.

Documentation is comprehensive, but developers should expect a structured verification process before production credentials are issued.

HyperPay is particularly suited for:

• High-volume Saudi retailers
• Enterprise commerce platforms
• Hospitality systems
• Airline and travel platforms
• Large subscription businesses
• Businesses where Mada approval rate directly impacts revenue

HyperPay also operates beyond Saudi Arabia, supporting merchants in:

• UAE
• Egypt
• Jordan

This regional coverage makes it suitable for companies expanding across multiple Middle Eastern markets without replacing their payment infrastructure.

---

Moyasar — fastest path to live Mada for Saudi startups

Moyasar has become one of the preferred gateways among Saudi startups because of its developer experience.

Its REST APIs are straightforward, documentation is clear, and sandbox onboarding is significantly faster than traditional enterprise providers.

Developers generally appreciate:

• Clean REST architecture
• Simple authentication
• Excellent sandbox environment
• Clear webhook documentation
• Fast Mada enablement

Moyasar supports:

• Mada
• Apple Pay
• STC Pay
• Samsung Pay
• Visa
• Mastercard

For Saudi-only businesses, Moyasar often provides the shortest route from development to production.

Its primary limitation is geographic reach.

Unlike HyperPay or PayTabs, Moyasar focuses almost entirely on Saudi Arabia rather than broader GCC expansion.

---

PayTabs — when Saudi is one GCC market among several

Some businesses launch in Saudi Arabia while simultaneously operating across neighbouring GCC countries.

Managing different gateways for every country increases operational complexity.

PayTabs addresses this by supporting merchants across:

• Saudi Arabia
• UAE
• Kuwait
• Bahrain
• Oman
• Qatar
• Jordan
• Egypt
• Palestine

One merchant account can support payment processing throughout the region.

PayTabs also supports SADAD, making it particularly attractive for:

• Subscription businesses
• Insurance platforms
• Government-facing systems
• Utility payment applications
• Invoice-driven B2B software

If Saudi Arabia is only one market inside a broader GCC expansion strategy, PayTabs often becomes the simplest operational choice.

---

Tap Payments — for Shopify and GCC-wide operations

Tap Payments has built a strong reputation among Shopify merchants operating throughout the Gulf.

Its Shopify Markets integration simplifies multi-country checkout configuration without requiring extensive custom payment routing.

Tap Payments supports operations across:

• Saudi Arabia
• UAE
• Kuwait
• Bahrain

Its onboarding process is generally faster than enterprise-focused gateways while still supporting regional expansion.

Businesses that frequently launch new Shopify storefronts often choose Tap Payments because it reduces operational overhead across multiple GCC markets.

---

Apple Pay, STC Pay, and SADAD — the rest of the Saudi payment stack

Developers often focus heavily on card payments while overlooking alternative payment methods.

In Saudi Arabia, these payment methods frequently represent the difference between an average checkout and one optimised for local consumer behaviour.

---

Apple Pay — Mada underneath, not international Apple Pay

This is one of the most misunderstood aspects of Saudi payment development.

Apple Pay in Saudi Arabia is not simply Apple's international payment system operating inside Saudi Arabia.

For most Saudi consumers, Apple Pay routes through Mada debit cards stored inside Apple Wallet.

The customer experiences Face ID or Touch ID authentication.

Behind the scenes, however, the gateway processes a Mada transaction rather than a standard Visa or Mastercard authorization.

This distinction changes several integration requirements.

Developers must ensure:

• Apple Pay merchant certificates are correctly configured.
• The gateway supports Mada routing through Apple Pay.
• BIN validation confirms Mada compatibility before displaying the Apple Pay payment sheet.
• Testing uses Saudi-issued Mada cards inside Apple Wallet rather than international credit cards.

Failure to perform Mada-specific testing creates confusing production issues.

The Apple Pay sheet may appear successfully while the underlying Mada authorization fails because the gateway has not been configured for Saudi routing.

Refund behaviour also differs from many international implementations.

Apple Pay refunds using Mada cards follow Mada settlement timelines rather than immediate wallet updates.

---

STC Pay — Saudi wallet integration

STC Pay operates independently from the Mada network.

Instead of card authorization, users authenticate directly with the STC Pay application before returning to the merchant platform.

Typical implementation involves:

1. Redirect or deep-link into the STC Pay application.
2. Customer authentication inside STC Pay.
3. Payment confirmation.
4. Gateway webhook sent to the merchant backend.
5. Order confirmation after webhook validation.

HyperPay and Moyasar both support STC Pay using API-driven redirect workflows.

Because settlement typically follows T+1 schedules, it integrates well into Saudi commerce operations requiring fast payment confirmation.

STC Pay is especially valuable for:

• Mobile commerce
• Food delivery
• Retail applications
• Digital services
• Youth-focused consumer products

---

SADAD — for recurring and government payments

SADAD serves a very different purpose from Mada or STC Pay.

Rather than processing instant consumer purchases, SADAD enables structured invoice-based payments.

Typical implementation flow:

1. Merchant generates a SADAD bill reference.
2. Customer opens their banking application or SADAD portal.
3. Customer enters the reference number.
4. Payment confirmation reaches the merchant through gateway notification.

SADAD is particularly useful for:

• SaaS subscription billing
• Insurance premium collection
• Utility management platforms
• Government-facing services
• Enterprise invoicing

Consumer retail platforms generally do not require SADAD.

Business software, however, often depends on it.

---

BNPL — Tabby and Tamara as first-class checkout options

BNPL (Buy Now, Pay Later) has become a standard expectation across Saudi e-commerce.

Developers should treat Tabby and Tamara as core payment methods rather than optional checkout additions.

Tamara generally appeals to Saudi-first audiences through its Sharia-compliant structure.

Tabby enjoys wider adoption across GCC fashion, electronics, and lifestyle merchants.

For merchants comparing both providers commercially, read Tabby vs Tamara merchant fees Saudi Arabia.

Developers building an entirely new BNPL platform should instead read BNPL app development Saudi Arabia.

The biggest implementation mistake is assuming BNPL begins at checkout.

It does not.

The buying decision happens much earlier.

Both providers supply JavaScript widgets that belong on the product page beneath the displayed product price.

The widget should update dynamically whenever:

• Product variants change
• Quantity changes
• Currency changes
• Promotional pricing changes

Displaying instalment information before checkout significantly influences purchasing decisions.

Integrating BNPL only inside the checkout flow removes much of its conversion value.

The three integration mistakes Saudi developers make

The majority of Saudi payment integration issues do not originate from the payment gateway.

They originate from assumptions developers bring from international payment systems into a Saudi-specific payment environment.

These three mistakes repeatedly appear during production launches and are responsible for many avoidable checkout failures.

---

Mistake 1 — Testing with Visa, not Mada sandbox cards

Every payment gateway provides sandbox environments with test cards.

Most developers instinctively begin testing with Visa because it is familiar and works across almost every international payment integration.

That approach creates a false sense of confidence.

Mada is not simply another card network.

It has:

• Different BIN (Bank Identification Number) ranges
• Different routing logic
• Different 3DS (Three-Domain Secure) authentication
• Different decline codes
• Different settlement behaviour
• Different refund processing

A checkout can successfully process every Visa sandbox transaction and still fail immediately when real Saudi customers attempt to pay using Mada.

Common production issues include:

• OTP authentication failures
• Unsupported BIN routing
• Incorrect gateway configuration
• Refund processing failures
• Unexpected authorization declines

Every SAMA-licensed gateway provides Mada-specific sandbox cards precisely because the payment flow differs from Visa.

Before considering an integration complete, developers should test:

• Successful authorization
• Failed authorization
• OTP verification
• Insufficient funds
• Daily spending limit exceeded
• Customer cancellation
• Refund processing
• Settlement confirmation
• Webhook delivery

Skipping Mada-specific testing almost always results in production issues that could have been discovered before launch.

---

Mistake 2 — Misunderstanding Apple Pay routing in Saudi Arabia

Many developers have already integrated Apple Pay for clients in Europe, North America, or Australia.

They naturally expect the Saudi implementation to behave the same way.

It does not.

For most Saudi consumers, Apple Pay is simply a Mada debit card presented through Apple's wallet interface.

Face ID authenticates the customer.

The payment itself still travels through Mada.

This changes the integration requirements considerably.

The gateway must support Mada routing through Apple Pay.

The Apple Pay merchant certificate must also be configured correctly for Saudi payment processing.

Without those configurations, developers often encounter confusing behaviour.

Typical production scenario:

1. Apple Pay sheet opens successfully.
2. Customer authenticates using Face ID.
3. Apple Pay returns a payment token.
4. Gateway attempts authorization.
5. Mada routing fails.
6. Payment is declined.

From the customer's perspective, Apple Pay appears broken.

In reality, the gateway has not been configured for Saudi Apple Pay via Mada.

Testing is equally important.

Developers should never rely solely on international Visa or Mastercard cards stored in Apple Wallet.

Instead, testing should use Saudi-issued Mada cards inside Apple Wallet to verify the complete production payment path.

Refund behaviour also surprises many international teams.

Apple Pay refunds using Mada cards follow Mada settlement timelines rather than the immediate wallet updates developers often observe in Western markets.

Understanding this distinction prevents inaccurate customer support messaging after launch.

---

Mistake 3 — Adding BNPL only at checkout, not on the product page

This is probably the most common Saudi e-commerce mistake.

Developers frequently treat Buy Now, Pay Later (BNPL) as another payment option displayed beside Visa or Mada during checkout.

That misses the primary conversion opportunity.

Saudi consumers often make their purchasing decision long before reaching checkout.

Seeing:

Pay SAR 250/month with Tamara

directly beneath the product price changes purchasing behaviour before the customer even clicks Add to Cart.

Both Tabby and Tamara therefore provide two separate integrations:

Product page widget

The JavaScript SDK displays installment information immediately below the product price.

The widget updates automatically whenever:

• Product variants change
• Discounts apply
• Currency changes
• Quantity changes

Checkout API

Once the customer decides to purchase, the checkout integration completes the financing process.

These are separate implementations.

Completing only the checkout API means the merchant misses one of BNPL's biggest conversion advantages.

The product page widget should receive:

• Merchant credentials
• Product price
• Currency
• Product identifier
• Dynamic price updates during variant selection

The widget should also appear prominently below pricing instead of being hidden further down the page.

Developers who postpone widget implementation until after launch usually discover that adding it later requires unnecessary frontend restructuring.

Treat the widget as part of the product page architecture—not the checkout page.

---

ZATCA intersection — payment webhook to invoice engine

Payment processing and ZATCA (Zakat, Tax and Customs Authority) e-invoicing are two completely separate systems.

The payment gateway confirms whether money has been successfully collected.

The invoicing engine generates and submits the legally compliant electronic invoice.

The connection between those systems is the payment webhook.

The recommended production flow is:

1. Customer completes payment.
2. Gateway sends a payment.confirmed webhook.
3. Backend verifies the webhook signature.
4. Payment status is confirmed.
5. ZATCA invoice generation begins.
6. Invoice is digitally signed.
7. Invoice is transmitted to ZATCA.

For B2C simplified invoices, the Reporting API submission must occur within the required reporting window.

For B2B invoices, the invoice must first pass through the Clearance API before delivery to the buyer.

Developers should never generate ZATCA invoices from client-side success pages.

Customers may close the browser, lose connectivity, or manipulate client-side redirects.

Only the server-side webhook represents the authoritative payment confirmation.

Webhook processing should also implement idempotency.

Gateways may resend identical webhook events multiple times.

Applications should therefore store the transaction identifier and process each payment event only once.

For a complete implementation architecture covering ASP communication, invoice signing, cryptographic stamps, Reporting API, and Clearance API workflows, read ZATCA Fatoorah API integration Saudi Arabia.

The complete Saudi checkout architecture

A production-ready Saudi checkout is far more than a payment form connected to a gateway.

It is an orchestration layer that combines local payment preferences, Arabic user experience, secure authentication, server-side verification, and ZATCA-compliant invoicing into a single payment workflow.

For the complete Saudi commerce architecture beyond payments—including catalogue management, logistics, fulfilment, Arabic UX, and order management—see our guide on e-commerce app development Saudi Arabia.

---

Payment method display order

Saudi consumers expect to see familiar payment methods immediately.

Displaying them in the wrong order reduces trust and increases checkout abandonment.

A recommended display hierarchy is:

1. Mada
2. Apple Pay (only on supported Apple devices)
3. STC Pay
4. Visa / Mastercard
5. Tabby
6. Tamara

SADAD and SARIE generally belong inside invoice-based or B2B payment workflows rather than consumer checkout.

---

Apple Pay conditional rendering

Apple Pay should never appear universally.

Browsers and devices that do not support Apple Pay should not display the payment option.

Developers should verify Apple Pay availability before rendering the payment button.

Typical frontend flow:

1. Detect browser support.
2. Verify Apple Pay session availability.
3. Verify gateway configuration.
4. Display Apple Pay button.
5. Hide Apple Pay on unsupported devices.

Rendering unavailable payment methods creates unnecessary customer confusion.

---

3DS Version 2 handling

Three-Domain Secure (3DS) Version 2 is the standard authentication protocol supported by Saudi issuing banks.

Every card payment flow should gracefully handle:

• Authentication challenge
• OTP entry
• Successful authentication
• Authentication timeout
• Authentication cancellation
• Failed authentication

Developers should never attempt to customise or replace the issuing bank's authentication screens.

The gateway controls the authentication journey while the merchant application waits for the final authorization result.

---

Arabic decline and retry logic

Payment declines are inevitable.

Poor decline handling is not.

Saudi consumers expect meaningful Arabic error messages rather than generic English notifications.

Instead of displaying:

Payment Declined

Applications should communicate specific reasons whenever possible, such as:

• Insufficient funds
• Daily spending limit exceeded
• OTP expired
• Authentication cancelled
• Bank declined transaction

Following a failed payment, the checkout should immediately offer an alternative payment method instead of repeatedly attempting authorization on the same payment instrument.

For example:

• Mada fails → suggest STC Pay.
• Apple Pay fails → offer direct Mada.
• Card limit exceeded → suggest Tabby or Tamara.

Well-designed retry logic recovers many failed checkouts that would otherwise become abandoned carts.

---

Arabic RTL checkout experience

Saudi payment interfaces should be designed for Arabic from the beginning rather than translated after development.

Core requirements include:

• Right-to-left page layout
• Arabic-first labels
• Arabic validation messages
• RTL form alignment
• Arabic typography
• Clear Gregorian expiry date labels
• Arabic primary action buttons

Card numbers themselves should remain left-to-right for readability, even inside RTL interfaces.

This hybrid layout matches Saudi banking applications and creates familiarity for users.

---

Webhook verification

Client-side payment confirmation is never authoritative.

The payment gateway's webhook is the only trusted source confirming that money has actually been collected.

Every webhook implementation should include:

• Signature verification
• HMAC (Hash-based Message Authentication Code) validation
• Timestamp validation
• Transaction lookup
• Duplicate event detection
• Idempotent processing

Only after successful verification should the backend:

1. Confirm payment.
2. Update order status.
3. Reserve inventory.
4. Generate the ZATCA invoice.
5. Trigger customer notifications.

Ignoring webhook verification creates opportunities for fraudulent order completion.

---

Recommended production payment flow

A robust Saudi payment architecture generally follows this sequence:

1. Customer selects a payment method.
2. Gateway begins authorization.
3. Customer completes 3DS or wallet authentication.
4. Gateway processes the payment.
5. Gateway sends a signed webhook.
6. Backend verifies authenticity.
7. Order status changes to paid.
8. ZATCA invoice generation begins.
9. Customer receives confirmation.
10. Fulfilment workflow starts.

Each step should be independent so failures can be retried without creating duplicate payments or invoices.

---

Why LogioLegion for Saudi payment integration

Building payment infrastructure for Saudi Arabia requires much more than connecting a payment gateway SDK.

Every production system must coordinate payment processing, ZATCA e-invoicing, Arabic user experience, security, and regulatory compliance into one reliable transaction flow.

At LogioLegion, Saudi payment systems are designed around local payment behaviour rather than international assumptions.

Our payment integrations combine Mada, Apple Pay, STC Pay, BNPL providers, and ZATCA into a unified backend architecture that prioritises reliability, compliance, and maintainability.

Our technical stack includes:

• React and React Native for Arabic-first RTL checkout experiences.
• Node.js for gateway webhooks, payment orchestration, and ZATCA API communication.
• Laravel for reconciliation workflows, payment state management, invoice lifecycle management, and audit logging.
• Next.js for merchant dashboards and payment administration portals.

Our Saudi engineering experience extends beyond payment gateways.

We also build systems integrating:

• ZATCA Phase 2 e-invoicing
• Mada payment infrastructure
• NAFATH digital identity
• PDPL-aware application architecture

Developers wanting a deeper understanding of Saudi invoicing architecture can read our guide on ZATCA Fatoorah API integration Saudi Arabia.

Businesses comparing Saudi gateways can also review our detailed comparison of Tap Payments vs HyperPay vs Moyasar Saudi Arabia.

Together with our broader custom software development Saudi Arabia expertise, these implementations enable businesses to launch payment systems designed specifically for Saudi consumer behaviour instead of adapting generic international checkout architectures.

---

Conclusion

A Saudi Arabia payment integration is not a Western payment implementation with Mada added later.

It is an entirely different technical discipline involving SAMA-licensed gateways, Mada routing, Saudi-specific Apple Pay behaviour, BNPL product-page integrations, ZATCA-triggered invoice generation, and Arabic-first checkout architecture.

Building these components correctly from the beginning avoids costly production issues while delivering the payment experience Saudi customers expect.

Building a Saudi Arabia payment integration for your platform?

Book a free discovery call with LogioLegion and we'll scope the complete Saudi payment architecture—from gateway selection and Mada integration to ZATCA webhook workflows—and deliver a detailed technical proposal tailored to your platform.