Mada for API only

Last updated: March 27, 2025

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


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}


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}

Card number	Card type
`4464043505991993`	Mada, Visa co-brand
`4407954943022953`	Mada, Visa co-brand
`5433571755811375`	Mada, Mastercard co-brand
`5541805721646120`	Mada, Mastercard co-brand

Mada for API only

Merchant-initiated transactions

Note

Initial request example

Subsequent request example

Mada test cards