Mada
Last updated: October 30, 2024
Mada is Saudi Arabia's domestic payment network. Due to Mada's partnerships with major card schemes including Visa and Mastercard, their cards are 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. We recommend that you process Mada cards using 3D Secure and the card verification value (CVV) / card security code (CSC).
However, if you're processing a Mada card through Apple Pay outside of Saudi Arabia, you're required to enforce the use of Visa or Mastercard instead. To do so, make the following changes in your app or web application's front-end Apple Pay code:
- In the
supportedNetworksarray, removemada. This ensures that transactions from co-branded cards are processed on the Visa or Mastercard network. - Set the
countryCodevalue to the country code that you're processing from. You can set this value to any country code, exceptSA. This will prevent Apple from forcing Mada for international transactions.
To process Mada cards within Saudi Arabia, 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.
Note
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.
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"totrueto 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 scheme.
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 Account Manager to enable Mada v2.
Note
The Mada v2 network does not support Google Pay or Apple Pay merchant-initiated transactions.
| Card number | Card type |
|---|---|
4464043505991993 | Mada, Visa co-brand |
4407954943022953 | Mada, Visa co-brand |
5433571755811375 | Mada, Mastercard co-brand |
5541805721646120 | Mada, Mastercard co-brand |
The list of approved Mada BINs is updated frequently. To keep your transaction routing accurate, make sure your systems are regularly updated with the most recent Mada BIN list.
Select the link to download a list of the Mada BINs - Download a list of the Mada BINs (.csv file).
File last updated: October 30, 2024.
Information
If you're using Safari, hold the Option key when you download.