Mada

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.

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).

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.

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.

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 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.

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

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

Select the link to download a list of the Mada BINs - Download a list of the Mada BINs (.csv file).