Mada Online Payments: Authorization, Capture, Refunds and Settlement
Online mada payment states, capture, void, refund and bank settlement, with a scoped Moyasar example.
SAMA describes mada's e-commerce card service, but capture, void, refund and bank credit depend on a merchant's provider and acquirer. Moyasar's API illustrates distinct authorized and paid states, capture windows and aggregation settlements.
An online mada authorization confirms a card-payment step, not merchant bank settlement. In Moyasar's documented implementation, a default purchase authorizes and captures, while a manual authorization must later be captured or voided; Moyasar tells users of its mada flow to capture within 14 days. A paid or captured payment uses a different refund path, and merchant settlement follows either an aggregation schedule or a direct-bank acquiring arrangement. Those operational windows and schedules are provider-specific unless a current mada rule is independently established.
A Saudi online card payment has at least three checkpoints: the card transaction, the capture or reversal decision, and the merchant's bank credit. The national mada system is part of the card route, but the detailed API states and payout schedule depend on the merchant's payment provider and acquirer.
SAMA describes mada E-Commerce as online card use with 3D Secure. Its online mada circular addresses domestic e-store routing and bank testing/approval conditions. Neither public page provides a universal API status map or merchant payout clock. The operational example below comes from Moyasar's own documentation. A merchant on another integration must verify that provider's states and terms.
A payment can be authorized without being captured
Moyasar's default purchase flow authorizes and captures in one action and returns a payment status of paid. With manual: true, the initial response is authorized: a hold is in place, and the merchant must decide whether to capture or void. Do not book both statuses as the same cash event.
Moyasar says its authorized mada payments must be captured within 14 days and that other card schemes may allow longer. That is the window Moyasar instructs users of its manual flow to follow. This article does not extend that figure to every mada processor, acquirer or contract. A delayed-fulfilment merchant should confirm the actual window before designing an “authorize now, ship later” flow.
Moyasar's capture action allows a full capture with no amount field, or a partial capture for no more than the authorized amount. Capture failure should trigger a status check before another attempt; the provider's guide gives a specific retry sequence. The merchant's order ID, payment ID, authorized amount and captured amount must be kept distinct.
Void and refund are different operations
In Moyasar's flow, a void can release an authorized hold. Its guide also says a paid or captured payment can be voided only within approximately two hours of the original transaction; later, it directs merchants to a refund. This short paid/captured void window is a Moyasar implementation detail, not a national mada timing rule. The card issuer determines when a released hold becomes visible to the cardholder; do not promise “instant money back” from a successful void request.
A refund follows a charged payment. Moyasar documents full and partial refunds, capped by the amount charged or captured. It also says a live aggregation merchant needs enough account balance for the refund. If a payment was only partly captured, the original authorization is not the amount available to refund. Record each refund's own ID, amount and status; use the refund operations runbook for the wider customer and ledger workflow.
| Moyasar state or action | What the merchant can infer | What still needs checking |
|---|---|---|
authorized | A hold exists in its manual flow. | Capture or void decision; the provider's applicable deadline. |
paid or captured | The provider reports a charged payment. | Refund/void eligibility and the later payout record. |
voided | The provider reports a reversal/hold release. | Issuer-side cardholder display and settlement effects. |
refunded | The provider reports a refund action. | Refund record, funding balance and bank/settlement adjustment. |
The table follows Moyasar's status and action definitions; it is not a mada-wide status dictionary. A browser redirect or a shopper screenshot is insufficient evidence for fulfilling an order. Confirm the payment's final state through the provider's server-side records.
Settlement depends on the acquiring arrangement
For aggregation merchants, Moyasar documents a default settlement schedule of Monday and Thursday, while saying the agreement may differ. Its report includes payment IDs and other payment details. That is a Moyasar merchant payout schedule, not a mada settlement rule or a guarantee that a particular payment reaches the bank on either day.
For facilitation or direct-bank merchants, Moyasar sends the merchant to its acquiring bank for the POS settlement report, using its merchant ID. The party supplying the checkout API may therefore not own the final bank-credit file.
Reconcile order → payment → capture/void/refund → settlement line → bank credit. Investigate missing IDs, partial amounts and fee deductions before attributing a short bank credit to a mada rule. The Saudi payment-stack overview explains where the national systems and provider roles fit; the payment lifecycle reference explains the generic card states across markets.
Questions for the provider contract
Ask the prospective provider to identify its acquiring bank or licensed payment-service provider, online mada availability for your entity, manual-capture support, current authorization window, void/refund state rules, refund-funding method and the report that reconciles to your bank account. Request a sample transaction and settlement export. The operational answer lives in those named services and records, not in “mada supported” on a sales page.
Sources & methodology (5)
SAMA describes mada E-Commerce as online card payments using 3D Secure.
Checked:
SAMA's domestic online mada circular addresses the routing and bank testing/approval conditions.
Checked:
Moyasar documents default purchase, manual authorization, capture, void and refund states and windows.
Checked:
Moyasar's aggregation merchants have a stated twice-weekly default settlement schedule that can vary by agreement.
Checked:
Moyasar directs facilitation/direct-bank merchants to obtain their POS settlement report from the acquiring bank.
Checked:
Source types explained in our Methodology.
By Shaun Toh · Director, Digital Payments · Razer