You're viewing documentation for our latest API. This will not impact your integration, but you will need the documentation relevant to you. If you have an account with Checkout.com you have received an email confirming which version to use.
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. 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 frontend Apple Pay code:
In the supportedNetworks array, remove mada. This ensures that transactions from co-branded cards are processed on the Visa or Mastercard network.
Set the countryCode value to the country code that you're processing from. You can set this value to any country code, except SA. 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.
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" 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.