Skip to main content
Rasad

Blog

Blog Overview

Payment gateway integration in Saudi Arabia: what the scope actually includes

PublisherAbwab Admin
Published OnNov 15, 2026
Reading Duration7 min read
Last UpdateNov 15, 2026
Payment gateway integration in Saudi Arabia: what the scope actually includes

The gateway is not a button on a checkout page. This article separates the states, responsibilities, tests and reconciliation that decide whether the integration works after launch.

When you say “we need a payment gateway”, you are not describing one task. You are describing a chain of states: an order is created, an amount is authorised, a card is declined, a refund is requested, and a settlement is reconciled at the end of the month. The gateway is not a button on a checkout page. It is a contract between your store, the payment provider and the bank, and each party has a different responsibility when something goes wrong.

This article separates what belongs inside the integration scope, what is usually left outside, and how to test it before you open the store. It does not discuss fees or commission rates, because those depend on your contract, volume and activity. It discusses what makes the integration work: states, responsibilities, tests and reconciliation.

What the gateway does and does not do

The gateway carries payment data to the party that makes the decision, returns the result to your store, and provides an interface for managing operations afterwards. It does not provide you with funding, does not replace the bank in settlement, and does not make fraud disappear. In Saudi Arabia, Mada is the local card network, Apple Pay and STC Pay are additional methods, and international cards arrive through card providers. Each method has a slightly different authorisation path, even when the checkout page looks the same.

So do not only ask “do you support Mada?”. Ask: does the contract support Mada for local and international cards? Does it support partial refunds? Does it send a notification when the payment state changes? Do you have a test environment that behaves like production? These questions reveal the difference between an integration that launches and one that can be operated.

The states you have to design

StateWhat must happenCommon failure
Successful authorisationThe order moves to paid, stock is reserved, the customer sees confirmationA confirmation shown before the payment notification arrives
Declined cardA clear message, and the order stays retryableA duplicate order created on every attempt
Response timeoutThe order stays pending, and the state is checked before it is treated as failedTreating silence as a decline and charging again
Full refundThe amount is returned, the order is updated, the customer is toldA refund at the gateway without a store update
Partial refundAmount, stock and invoice change togetherEditing the invoice by hand later
Duplicate notificationThe same event is processed onceStock decremented twice for one order
Month-end settlementGateway payout matches store sales and refundsA difference nobody can explain

The local layer: Mada and invoicing

Mada is not just an option in a list. It is a local card network with requirements for authorisation, refunds and settlement. If your store sells to consumers, Mada support is not an enhancement; it is a condition of doing business. If you sell to companies, you may need bank transfer or credit terms, each with a different lifecycle: order, approval, payment, reconciliation. Do not mix them into one screen.

A tax invoice is not an attachment to a payment. It is an accounting record that must reflect the amount paid, the tax and any refund. When an order changes after payment, the invoice must change or a corrective invoice must be issued under the applicable rules. The easiest way to create an accounting problem is to build payment first and try to attach invoicing afterwards. Start from the invoice, then build payment around it.

Measurement starts here too. Baymard's 50-study average puts cart abandonment at 70.19%, 22% of users have abandoned because checkout was too long or complex, and the average form has 11.3 fields. If your checkout asks for fields you do not need, you are losing orders before the gateway is reached. Saudi checkout conversion fixes lists the issues we see first.

From reading to shipping

Want this built, not just explained?

Bring us the problem behind the article. We will tell you what it takes, what it costs, and whether we are the right team.

The test matrix before launch

Do not test in production. Ask for a test environment that behaves like production, then test the following cases. If they are not covered, the integration is incomplete even if the screen shows a success message.

  1. Successful card: a complete order through invoice and confirmation, with amount and tax matched.

  2. Declined card: a clear message, one order only, and a retry that does not duplicate it.

  3. Timeout: simulate a delayed response and confirm the order is not marked failed before verification.

  4. Full refund: from the gateway and from the store admin, with state matched in both.

  5. Partial refund: amount, invoice and stock change together, with a clear user record.

  6. Duplicate event: resend the same event and confirm stock is not decremented twice.

  7. Order without an address: a clear rejection before payment, not after, with a message explaining what is missing.

  8. Settlement: match the gateway report against store sales and refunds for the same day.

PCI scope and responsibility

When card data passes through your server, you widen the scope of PCI compliance. The simpler answer is not to touch card data at all: use a hosted field or redirect to the provider's payment page so the data stays outside your system. That does not remove responsibility, but it reduces what you have to prove later. Ask your provider which integration model it recommends and what still lands on your server.

Responsibility does not stop at the gateway. Who owns the API key? Who can see payment logs? Who approves a refund? Who reconciles settlement? Who answers the customer who says the amount was charged twice? Write these roles into the operating note before launch. An integration where nobody knows who does what ends as a support problem, not a technical one.

Frequently asked questions

Can we connect more than one gateway? Yes, but each gateway adds another state and another settlement. Start with one that covers the core need, and add a second when it has a clear commercial reason.

Do we need 3-D Secure? It depends on your provider, card type and applicable rules. Ask about both paths, challenge and frictionless, and how each appears to the user.

How long does integration take? It depends on the number of methods and states, but it is usually part of the store scope, not a separate project. Test it early, not in the last week.

Who pays refund fees? That is a contractual term with the provider, not a technical decision. Read it before signing.

Do you support Apple Pay and STC Pay? Yes, through the provider that supports them under your contract. We verify each method with a real test, not an assumption.

What happens if the gateway goes down? You need a plan: a clear message, an alternative path if one exists, and monitoring that alerts a person, not a silent error page.

Sources

Cover image: Syced, CC0, via Wikimedia Commons.

Get in Touch

We'd love to hear from you. Fill out the form and we'll get back to you soon.