Introduction

Card Verification is a MyFatoorah functionality used to authenticate a customer’s card without deducting any amount and without creating any transaction record in MyFatoorah.

It allows you to:

Validate the card
Confirm the card supports 3D Secure
Confirm the customer completed authentication (OTP)
Tokenize the card for later usage

📘
Integration Availability
Card Verification works only with Embedded Integration & Direct Integration

How It Works

Embedded Integration

You will receive the verification result either:

Directly in MyFatoorah callback (if using shouldHandlePaymentUrl: true)
Or by calling the inquiry API GET /v3/sessions/{sessionId}

Step 1: Create a Verification Session

Endpoint: POST /v3/sessions (Create Session)

{
    "PaymentMode": "COMPLETE_PAYMENT",
    "Order": {
        "Amount": 0
    },
    "Customer": {
        "Reference": "NewToken-1"
    },
    "OperationType": "Verify",
    "IntegrationUrls": {
        "Redirection": "https://your-website.com/payment-callback"
    },
    "SaveCardOptions": {
        "SaveToken": true
    }
}

{
    "IsSuccess": true,
    "Message": "Created Successfully!",
    "ValidationErrors": null,
    "Data": {
        "SessionId": "KWT-3e13d9ef-4049-4451-946a-9d130de7afc1",
        "SessionExpiry": "2025-11-18T22:10:11.0402350Z",
        "EncryptionKey": "5Yisq7Z7lR/1Bg1FuA+wGg5P/sjhIQyPoMVCEzBO+bo=",
        "OperationType": "Verify",
        "Order": {
            "Amount": 0.0,
            "Currency": "KWD",
            "ExternalIdentifier": null
        },
        "Customer": {
            "Reference": "123456",
            "Cards": null
        }
    }
}

Step 2: Implement Embedded Integration

Use the Embedded integration guide: Embedded Payment

Step 3: Receiving Verification Result

Option 1: shouldHandlePaymentUrl = true

You will receive the verification result directly in MyFatoorah callback.

{
    "isSuccess": true,
    "sessionId": "KWT-b980fb36-e6da-4110-9b5c-812ee14e7cf3",
    "paymentCompleted": true,
    "paymentData": "07kipVdwrbJuYN/yDTbDgGCU087bEgq7xEnW+j5voFiKPxK5+IiCoMBLg0IIFsYnvyXNUgZMR27X6IM3453gsMkn2zJtgDAwyPRyap4soK+yDGt5OzerOyCOCO7jrSw1VZkDqUSiivNBs5J9jjjxMiocb77/LxIS/oWCgd7HNME8myqQ+aXdZh1bV49fnHzb3/sZUN8jGJrEEOSZxM8Iw9g3TjGi7rl3G6M0W5pDhGA0xdYeVknmoeR0sG/wTiq+HdlBe4zoZMzEv8NutWzB+4XTLHC3oAvuxuMsGu/wYf9+7L3fPwKGSGldmIbCq0bLCBwilxMWL5sb3aUgeQLT8/geVUWsX0Ub4GqhScpxXCwsoimK0NilmjM78XFyOMpq0ffR0Mn/sZ92DUFjDsDqXKgKhXVi0OXdz4lDaD3m4T1vO9gqWL/pLnaqCG8GZxWQrlA8kjwhBIjagtHLCedN2dwPIn2HuW6vZbcxI8ZEF0i8GDDaI4npWyMWMywd7Lwjt5Lpw1D9FY5l7neM3RscGV7Wv0MZ+6koox6AseLv5mV/fgC7dG0A1kBdSJzDgh+mj8Ze4snX4tyYDY9EshDfxD07VFoojhbpLUdaFUtIimoTeSpOG+WBdTNMr4k7YlxnnkNk4lOi4OlvKQB8Mp8Z5FJ5sAyVpQz86I6GimnWYHO112DaQWSbxc2FYUYqVxlv9f5I382PZoFMQSEABsVEKoSVL53VR9pz9Oq7+soL99Gay9j8nl+0BU3fxU/bhGj6rbntoPlq5nkCWz1As9ow/pb89XaGC1s4dOpjOZ59X9s=",
    "paymentType": "CARD",
    "redirectionUrl": "https://demo.MyFatoorah.com/payments/v3/En/KWT/VerifyResult?sessionId=KWT-b980fb36-e6da-4110-9b5c-812ee14e7cf3"
}

{
    "IsCardVerified": true,
    "Error": null,
    "Card": {
        "Number": "512345xxxxxx0008",
        "ExpiryMonth": "01",
        "ExpiryYear": "39",
        "Brand": "Mastercard",
        "PanType": "Card",
        "Issuer": "Test Bank",
        "PanHash": "b888aa5f23a817883d4d12c74044bab1ae6ee65dc8d6e11515394aba452b273b",
        "TokenId": null,
        "Token": "TKN-7b5a78ea-ca6f-46cc-be5c-a9801d189d48",
        "TransactionType": null,
        "AgreementId": null,
        "NetworkTransactionId": "",
        "Bypass3ds": false,
        "NameOnCard": "test",
        "IssuerCountry": "KWT",
        "FundingMethod": "credit",
        "ProductName": "Mastercard Titanium",
        "First8digit": "51234500",
        "Is3DSVerified": true,
        "IsLocalCard": true
    },
    "Customer": {
        "Reference": "NewToken-1"
    }
}

You must decrypt paymentData using the session’s EncryptionKey.

A successful verification means: IsCardVerified = true and Is3DSVerified = true.

Option 2: shouldHandlePaymentUrl = false

MyFatoorah will send a callback that includes the OTP redirection link, and you must redirect the customer to the redirectionUrl value.

{
  "isSuccess": true,
  "paymentType": "CARD",
  "sessionId": "KWT-444c3461-a50d-4b22-bf85-4dc90fb03fe8",
  "paymentCompleted": false,
  "card": {
    "brand": "Mastercard",
    "panHash": "b888aa5f23a817883d4d12c74044bab1ae6ee65dc8d6e11515394aba452b273b",
    "token": "Token05065471913927257",
    "number": "512345xxxxxx0008",
    "nameOnCard": "test",
    "expiryYear": "39",
    "expiryMonth": "01",
    "issuer": "Test Bank",
    "issuerCountry": "KWT",
    "fundingMethod": "credit",
    "productName": "Mastercard Titanium"
  },
  "redirectionUrl": "https://demo.MyFatoorah.com/En/KWT/PayInvoice/MFCardVerification?sessionId=444c3461-a50d-4b22-bf85-4dc90fb03fe8"
}

The customer will complete OTP authentication, and then MyFatoorah will redirect the customer back to your website with the sessionId: https://your-website.com/payment-callback?sessionId=444c3461-a50d-4b22-bf85-4dc90fb03fe8

You need to call the Get Session Details endpoint to inquire about the verification result:

GET /v3/sessions/{sessionId}

{
    "IsSuccess": true,
    "Message": "Created Successfully!",
    "ValidationErrors": null,
    "Data": {
        "SessionExpiry": "2025-12-24T18:52:24.4687915+00:00",
        "IsUsed": true,
        "OperationType": "VERIFY",
        "Order": {
            "Amount": 0.0,
            "Currency": "KWD",
            "ExternalIdentifier": null
        },
        "Customer": {
            "Reference": "NewToken-1"
        },
        "Card": {
            "Number": "512345xxxxxx0008",
            "ExpiryMonth": "01",
            "ExpiryYear": "39",
            "Brand": "Mastercard",
            "PanType": "Card",
            "Issuer": "Test Bank",
            "PanHash": "b888aa5f23a817883d4d12c74044bab1ae6ee65dc8d6e11515394aba452b273b",
            "Token": "TKN-7b5a78ea-ca6f-46cc-be5c-a9801d189d48",
            "NameOnCard": "test",
            "IssuerCountry": "KWT",
            "FundingMethod": "credit",
            "ProductName": "Mastercard Titanium",
            "Is3DSVerified": true
        },
        "TransactionResult": null
    }
}

The card is verified when: Is3DSVerified: true

📘
Note
If you are using "PaymentMode": "COLLECT_DETAILS" we will redirect your customer to your Redirection URL with the SessionId appended. You then need to call GET /v3/sessions/:sessionId to check the verification result.

Direct Integration

3DS Card Verification

Endpoint: POST /v3/payments

{
    "PaymentMethod": "CARD",
    "Order": {
        "Amount": 0
    },
    "OperationType": "VERIFY",
    "SourceOfFund": {
        "Card": {
            "Number": "5123450000000008",
            "ExpiryMonth": "01",
            "ExpiryYear": "39",
            "SecurityCode": "100",
            "HolderName": "JOHN DOE"
        }
    },
    "IntegrationUrls": {
        "Redirection": "https://example.com/payment-callback"
    }
}

{
    "IsSuccess": true,
    "Message": "",
    "ValidationErrors": null,
    "Data": {
        "InvoiceId": null,
        "PaymentId": null,
        "PaymentURL": "https://demo.MyFatoorah.com/En/KWT/PayInvoice/MpgsCardVerification?sessionId=98df3e75-39b8-49f0-a231-560e85b2d10a",
        "PaymentCompleted": false,
        "TransactionDetails": null,
        "Card": {
            "Number": "512345xxxxxx0008",
            "ExpiryMonth": "01",
            "ExpiryYear": "39",
            "Brand": "Mastercard",
            "PanType": "Card",
            "Issuer": "Test Bank",
            "PanHash": "b888aa5f23a817883d4d12c74044bab1ae6ee65dc8d6e11515394aba452b273b",
            "Token": "",
            "NameOnCard": "JOHN DOE",
            "IssuerCountry": "KWT",
            "FundingMethod": "credit",
            "ProductName": "Mastercard Titanium",
            "IsValidCard": null,
            "Is3DSVerified": false
        }
    }
}

MyFatoorah will return the 3DS challenge URL in the API response. You must redirect the customer to the URL provided in the PaymentURL field to complete OTP authentication.

After the customer completes authentication, MyFatoorah will redirect them back to your website with the sessionId parameter.
https://example.com/payment-callback?sessionId=KWT-98df3e75-39b8-49f0-a231-560e85b2d10a

You should then call the Get Session Details endpoint using the received sessionId to retrieve the card verification result.

GET /v3/sessions/{sessionId}

{
    "IsSuccess": true,
    "Message": "Created Successfully!",
    "ValidationErrors": null,
    "Data": {
        "SessionExpiry": null,
        "IsUsed": true,
        "OperationType": "VERIFY",
        "Order": {
            "Amount": 0,
            "Currency": "KWD",
            "ExternalIdentifier": null
        },
        "Customer": null,
        "Card": {
            "Number": "512345xxxxxx0008",
            "ExpiryMonth": "01",
            "ExpiryYear": "39",
            "Brand": "Mastercard",
            "PanType": "Card",
            "Issuer": "Test Bank",
            "PanHash": "b888aa5f23a817883d4d12c74044bab1ae6ee65dc8d6e11515394aba452b273b",
            "Token": "",
            "NameOnCard": "JOHN DOE",
            "IssuerCountry": "KWT",
            "FundingMethod": "credit",
            "ProductName": "Mastercard Titanium",
            "IsValidCard": true,
            "Is3DSVerified": true
        },
        "TransactionResult": null
    }
}

The card is verified when Is3DSVerified: true

Non-3DS Card Verification

Endpoint: POST /v3/payments

{
    "PaymentMethod": "CARD",
    "Order": {
        "Amount": 0
    },
    "OperationType": "VERIFY",
    "SourceOfFund": {
        "Card": {
            "Number": "5123450000000008",
            "ExpiryMonth": "01",
            "ExpiryYear": "39",
            "SecurityCode": "100",
            "HolderName": "JOHN DOE"
        }
    },
    "ThreeDS": {
        "Enabled": "false"
    }
}

{
    "IsSuccess": true,
    "Message": "",
    "ValidationErrors": null,
    "Data": {
        "InvoiceId": null,
        "PaymentId": null,
        "PaymentURL": null,
        "PaymentCompleted": true,
        "TransactionDetails": null,
        "Card": {
            "Number": "512345xxxxxx0008",
            "ExpiryMonth": "01",
            "ExpiryYear": "39",
            "Brand": "Mastercard",
            "PanType": "Card",
            "Issuer": "Test Bank",
            "PanHash": "b888aa5f23a817883d4d12c74044bab1ae6ee65dc8d6e11515394aba452b273b",
            "Token": "",
            "NameOnCard": "JOHN DOE",
            "IssuerCountry": "KWT",
            "FundingMethod": "credit",
            "ProductName": "Mastercard Titanium",
            "IsValidCard": true,
            "Is3DSVerified": false
        }
    }
}

Card validity is determined by the IsValidCard value in the response.

true: The card is valid
false: The card is invalid

📘
Tokenization
To tokenize the card in Direct Integration, you will need to send the following in the request:
"SaveCardOptions": {
        "SaveToken": true
    },
"Customer": {
        "Reference": "111"
}