Card Verification

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

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}

📘
Integration Availability
Card Verification works only with Embedded Integration.

How It Works

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"
    }
}

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