Card Direct Integration

Overview

Card Direct Integration allows you to accept card payments directly on your website or application. You can collect the card details and send them to the payment gateway to process the payment.

How It Works

3D Secure Flow

Step 1: Create the Payment

You need to send the card details along with the remaining payment data to create a payment request. Then we return an OTP (3D Secure) URL in the response. You must redirect the customer to this URL to complete the authentication.
After the customer completes the payment, we redirect the user to your Redirection URL, appending the paymentId.

Endpoint: POST /v3/payments(Create Payment)

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

{
    "IsSuccess": true,
    "Message": "",
    "ValidationErrors": null,
    "Data": {
        "InvoiceId": "6389575",
        "PaymentId": "07076389575322466574",
        "PaymentURL": "https://demo.MyFatoorah.com/En/KWT/PayInvoice/MpgsAuthentication?paymentId=07076389575322466574&sessionId=SESSION0002610220078K87660104K2&mfSessionId=",
        "PaymentCompleted": false,
        "TransactionDetails": null
    }
}

Example Redirection URL after the customer completes the payment: https://your-website.com/payment-callback?paymentId=07076389575322466574&Id=07076389575322466574

Step 2: Inquire About the Payment Status

After the customer redirects back to your website, use the paymentId to inquire about the payment status.

Endpoint: GET /v3/payments/:paymentId

GET /v3/payments/07076389544322463873

{
    "IsSuccess": true,
    "Message": "",
    "ValidationErrors": null,
    "Data": {
        "Invoice": {
            "Id": "6389544",
            "Status": "PAID",
            "Reference": "2025001607",
            "CreationDate": "2025-12-24T15:17:55.0130000Z",
            "ExpirationDate": "2026-05-23T15:17:55.0130000Z",
            "ExternalIdentifier": null,
            "UserDefinedField": "",
            "MetaData": null
        },
        "Transaction": {
            "Id": "104686",
            "Status": "SUCCESS",
            "PaymentMethod": "VISA/MASTER",
            "PaymentId": "07076389544322463873",
            "ReferenceId": "535815103616",
            "TrackId": "24-12-2025_3224638",
            "AuthorizationId": "103616",
            "TransactionDate": "2025-12-24T15:18:06.4100000Z",
            "ECI": "02",
            "IP": {
                "Address": "197.32.51.213",
                "Country": "Egypt"
            },
            "Error": {
                "Code": "",
                "Message": ""
            },
            "Card": {
                "NameOnCard": "JOHN DOE",
                "Number": "512345xxxxxx0008",
                "Token": "",
                "PanHash": "b888aa5f23a817883d4d12c74044bab1ae6ee65dc8d6e11515394aba452b273b",
                "ExpiryMonth": "01",
                "ExpiryYear": "39",
                "Brand": "Mastercard",
                "Issuer": "Test Bank",
                "IssuerCountry": "KWT",
                "FundingMethod": "credit"
            }
        },
        "Customer": {
            "Reference": "",
            "Name": "Anonymous",
            "Mobile": "+965",
            "Email": ""
        },
        "Amount": {
            "BaseCurrency": "KWD",
            "ValueInBaseCurrency": "20",
            "ServiceCharge": "0.002",
            "ServiceChargeVAT": "0",
            "ReceivableAmount": "19.998",
            "DisplayCurrency": "KWD",
            "ValueInDisplayCurrency": "20",
            "PayCurrency": "KWD",
            "ValueInPayCurrency": "20"
        },
        "Suppliers": []
    }
}

Non-3D Secure Flow

The payment is processed immediately without redirecting the customer for authentication. The payment result is returned directly in the same response.

Endpoint: POST /v3/payments(Create Payment)

{
    "PaymentMethod": "CARD",
    "Order": {
        "Amount": 20
    },
    "SourceOfFund": {
        "Card": {
            "Number": "5123450000000008",
            "ExpiryMonth": "01",
            "ExpiryYear": "39",
            "SecurityCode": "100",
            "HolderName": "JOHN DOE",
        }
    },
    "IntegrationUrls": {
        "Redirection": "https://your-website.com/payment-callback"
    },
    "3DS": {
        "Enabled": false
    }
}

{
    "IsSuccess": true,
    "Message": "",
    "ValidationErrors": null,
    "Data": {
        "InvoiceId": "6389599",
        "PaymentId": "07076389599322468274",
        "PaymentURL": "https://your-website.com/payment-callback?paymentId=07076389599322468274&Id=07076389599322468274",
        "PaymentCompleted": true,
        "TransactionDetails": {
            "Invoice": {
                "Id": "6389599",
                "Status": "PAID",
                "Reference": "2025001613",
                "CreationDate": "2025-12-24T15:42:47.7867227Z",
                "ExpirationDate": "2026-05-23T15:42:47.7867227Z",
                "ExternalIdentifier": null,
                "UserDefinedField": "",
                "MetaData": null
            },
            "Transaction": {
                "Id": "110008",
                "Status": "SUCCESS",
                "PaymentMethod": "VISA/MASTER",
                "PaymentId": "07076389599322468274",
                "ReferenceId": "535815108928",
                "TrackId": "24-12-2025_3224682",
                "AuthorizationId": "108928",
                "TransactionDate": "2025-12-24T15:42:49.3363038Z",
                "ECI": "",
                "IP": {
                    "Address": "",
                    "Country": ""
                },
                "Error": {
                    "Code": "",
                    "Message": ""
                },
                "Card": {
                    "NameOnCard": "JOHN DOE",
                    "Number": "512345xxxxxx0008",
                    "Token": "",
                    "PanHash": "b888aa5f23a817883d4d12c74044bab1ae6ee65dc8d6e11515394aba452b273b",
                    "ExpiryMonth": "01",
                    "ExpiryYear": "39",
                    "Brand": "Mastercard",
                    "Issuer": "Test Bank",
                    "IssuerCountry": "KWT",
                    "FundingMethod": "credit"
                }
            },
            "Customer": {
                "Reference": "",
                "Name": "Anonymous",
                "Mobile": "+965",
                "Email": ""
            },
            "Amount": {
                "BaseCurrency": "KWD",
                "ValueInBaseCurrency": "20",
                "ServiceCharge": "0.002",
                "ServiceChargeVAT": "0",
                "ReceivableAmount": "19.998",
                "DisplayCurrency": "KWD",
                "ValueInDisplayCurrency": "20",
                "PayCurrency": "KWD",
                "ValueInPayCurrency": "20"
            },
            "Suppliers": []
        }
    }
}