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
| State | What must happen | Common failure |
|---|---|---|
| Successful authorisation | The order moves to paid, stock is reserved, the customer sees confirmation | A confirmation shown before the payment notification arrives |
| Declined card | A clear message, and the order stays retryable | A duplicate order created on every attempt |
| Response timeout | The order stays pending, and the state is checked before it is treated as failed | Treating silence as a decline and charging again |
| Full refund | The amount is returned, the order is updated, the customer is told | A refund at the gateway without a store update |
| Partial refund | Amount, stock and invoice change together | Editing the invoice by hand later |
| Duplicate notification | The same event is processed once | Stock decremented twice for one order |
| Month-end settlement | Gateway payout matches store sales and refunds | A 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.
Successful card: a complete order through invoice and confirmation, with amount and tax matched.
Declined card: a clear message, one order only, and a retry that does not duplicate it.
Timeout: simulate a delayed response and confirm the order is not marked failed before verification.
Full refund: from the gateway and from the store admin, with state matched in both.
Partial refund: amount, invoice and stock change together, with a clear user record.
Duplicate event: resend the same event and confirm stock is not decremented twice.
Order without an address: a clear rejection before payment, not after, with a message explaining what is missing.
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
- Baymard: checkout usability — 11.3 fields on average, and 22% who abandoned because checkout was too long.
- Baymard: cart abandonment rate — the 50-study 70.19% average.
- Rasad integrations — ZATCA, Nafath, Mada and ERP, and how each is tested.
- Ecommerce development — scope, process, and delivery.
- Rasad's published price bands — the figures this article works from.

