Mada for API only

Last updated: April 8, 2026

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.

To store Mada card details for a recurring payment series, you must define the subscription agreement with the cardholder. For example, whether the recurring amount is a fixed amount, or varies over time.

Because this is a cardholder-initiated transaction, 3D Secure (3DS) authentication must also be enabled. The card details are automatically stored, and the response returns a payment instrument ID for future use.

Call the Request a payment or payout endpoint, setting the following fields:

3ds.enabled – to true
3ds.challenge_indicator – to challenge_requested_mandate
merchant_initiated – to false
payment_plan.amount_variability – To either Fixed or Variable, depending on the subscription agreement you set with your customer.
payment_type – to Recurring

post

https://{prefix}.api.checkout.com/payments


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    "challenge_indicator": "challenge_requested_mandate"
12  },
13  "payment_plan": {
14    "amount_variability": "Fixed"
15  },
16  "merchant_initiated": false,
17  "payment_type": "Recurring",
18  "currency": "SAR",
19  "reference": "05CIT",
20  "success_url": "https://example.com/payments/success",
21  "failure_url": "https://example.com/payments/failure"
22}


1{
2  "id": "pay_4hlqceyyib5ezpxtpdpwfhwtda",
3  "status": "Pending",
4  "3ds": {
5    "downgraded": false,
6    "enrolled": "Y"
7  },
8  "source": {
9    "type": "id",
10    "id": "src_nwd3m4in3hkuddfpjsaevunhdy"
11  },
12  "_links": {
13    "self": {
14      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_fbfrj7f3bwou5bdgmzsryd223i"
15    },
16    "actions": {
17      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_fbfrj7f3bwou5bdgmzsryd223i/actions"
18    },
19    "redirect": {
20      "href": "https://{prefix}.api.sandbox.checkout.com/redirect/act_y3oqhf46pyzuxjbcn2giaqnb44"
21    }
22  }
23}

The source.id field returns the payment instrument ID for future use. Use the payment instrument ID to request future payments.

After the agreement is established, you can process subsequent MITs. You must reference the initial payment and submit the same subscription agreement type that was defined in the initial payment request. 3DS authentication is not required for MITs.

Call the Request a payment or payout endpoint, setting the following fields:

source.type – to id
source.id – to the payment instrument ID returned in the initial payment request
previous_payment_id – to the payment ID of the initial payment
payment_plan.amount_variability – This value must match the one used in the initial payment request.
merchant_initiated – to true
payment_type – to Recurring


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  "payment_plan": {
11    "amount_variability": "Fixed"
12  },
13  "merchant_initiated": true,
14  "payment_type": "Recurring"
15}

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

Request example

Response example

Subsequent payment request

Request example

Mada test cards