Mada for API only

Last updated: December 17, 2025

You can build your own user interface and integrate with Checkout.com's API to process Mada payments.

If you want to process Mada cards differently to credit cards, you must be able to identify transactions from Mada cards to 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 in your payment request:

Set "3ds.enabled" to true to process the payment with 3D Secure (3DS) authentication.
If using your own form to request full card details, or if using a stored card's payment instrument, request the card verification value (CVV) and provide it in the request.
Set "metadata.udf1" to "mada". This helps you identify Mada cards in your payment reports and webhooks.
Do not provide "capture" or "capture_on" in the request. This ensures Mada cards are processed with automatic, instant captures.

You can also test Mada payments using the Mada test cards.

Merchant-initiated transactions (MITs) are supported by version 2 of the Mada local card scheme. You can store a card's details during an initial, fully-authenticated 3DS transaction and then reuse the details in subsequent transactions.

Note

The Mada v2 network does not support Google Pay or Apple Pay MITs.

Information

To enable Mada version 2, contact your account manager or request support.


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": "Recurring",
14  "currency": "SAR",
15  "reference": "05CIT",
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": "Recurring",
12  "currency": "SAR",
13  "reference": "MIT05"
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

How it works

Merchant-initiated transactions

Note

Information

Initial payment request example

Subsequent payment request example

Mada test cards