Skip to content

Mada

Last updated: November 01, 2022

Start accepting payments with Mada, Saudi Arabia's domestic payment network.

Mada has partnerships with major card schemes like Visa and Mastercard, so the cards can be accepted both locally and globally.


Accepting Mada cards outside Saudi Arabia

When you process a Mada card outside Saudi Arabia, it behaves like any other debit card, so you can process a card payment without any need for specific configurations or extra parameters.

However, we recommend that you process Mada cards using 3D Secure and the card verification value (CVV) / card security code (CSC).


Accepting Mada cards within Saudi Arabia

To process Mada cards within Saudi Arabia's debit card network, you will first need to obtain a merchant ID from a Saudi Arabian card acquirer.

Authorization, capture, and void requests

All Mada transactions must be fully captured. Mada cards do not support partial captures or authorization requests.

If you request either of these, the acquirer will still capture the transaction but our gateway will automatically send a void request after 7 days.

As Mada cards do not support void requests, a refund request will be raised by the acquirer instead.

As the majority of the cards used in the Kingdom of Saudi Arabia are debit cards, we recommend processing all card payments in the region as 3D-secured, with the CVV included, and only using automatic captures and refunds.


Processing Mada card payments

If you would like to process Mada cards differently to credit cards, you'll first need to be able to identify transactions from a Mada card so that you can update your integration accordingly.

When a customer submits their Mada card information through the Frames.js card form, or when you tokenize Mada card details, the response returns the local card type as "scheme_local": "mada".

When a Mada card is identified, we recommend taking the following steps:

  • Set "3ds.enabled" to true to process the payment with 3D Secure authentication.
  • Request the CVV number and pass it in the request, if you’re using your own form to request full card details, or if you’re using a stored card's source ID.
  • Set "metadata.udf1" to "mada". This will help you to identify Mada cards in your payment reports and webhooks.
  • Do not pass "capture" or "capture_on" in the request. This ensures Mada cards are processed with automatic, instant captures.

Merchant-initiated transactions

Merchant-initiated transactions are supported by version 2 of the Mada local card network.

This means that you can store a card's details during an initial, fully-authenticated 3DS transaction and then reuse those details in a subsequent transaction.

Contact your Customer Success Manager to enable Mada v2.

The Mada v2 network does not support Google Pay or Apple Pay merchant-initiated transactions.

Initial request example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"source": {
"type": "token",
"token": "tok_blxfyymfxe3epo242ao25g5tim",
"stored": false,
"store_for_future_use": true
},
"amount": 100,
"3ds": {
"enabled": true
},
"merchant_initiated": false,
"payment_type": "Regular",
"currency": "SAR",
"reference": "ApplePayCIT",
"success_url": "https://google.com/?success",
"failure_url": "https://google.com/?success"
}

Subsequent request example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"source": {
"type": "id",
"id": "src_dab7dgghu877d6os2su5avu",
"store_for_future_use": false,
"stored": true
},
"previous_payment_id": "pay_cr4hxwizzp6k7biycuk2ibltnm",
"amount": 50,
"merchant_initiated": true,
"payment_type": "regular",
"currency": "SAR",
"reference": "MITApplePay05"
}

Mada test cards

Card numberCard type

4464043505991993

Mada, Visa co-brand

4407954943022953

Mada, Visa co-brand

5433571755811375

Mada, Mastercard co-brand

5541805721646120

Mada, Mastercard co-brand