Features Documentation
Start typing to searchā€¦

Direct Payment Tokenization

Introduction

In Direct Integration, you can save the card information as a token, get the token back to your application, and associate it with your customer profile for easier future payment execution.

šŸ“˜

Approval Needed

In case you are using Direct Integration you need to contact your account manager to activate Tokenization features for Direct Payment.

How it works

3D Secure Flow

Step 1: Create the Payment

You need to send the card details, unique Customer.Reference and SaveCardOptions.SaveToken=true 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
    },
    "SaveCardOptions": {
        "SaveToken": true
    },
    "Customer": {
        "Reference": "ref-1"
    },
    "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": "6389799",
        "PaymentId": "07076389799322483474",
        "PaymentURL": "https://demo.MyFatoorah.com/En/KWT/PayInvoice/MpgsAuthentication?paymentId=07076389799322483474&sessionId=SESSION0002859250654K70081809F5&mfSessionId=",
        "PaymentCompleted": false,
        "TransactionDetails": null
    }
}

Step 2: Inquire About the Payment Status and get the card token

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/07076389799322483474
{
    "IsSuccess": true,
    "Message": "",
    "ValidationErrors": null,
    "Data": {
        "Invoice": {
            "Id": "6389799",
            "Status": "PAID",
            "Reference": "2025001626",
            "CreationDate": "2025-12-24T18:21:10.7770000Z",
            "ExpirationDate": "2026-05-23T18:21:10.7770000Z",
            "ExternalIdentifier": null,
            "UserDefinedField": "",
            "MetaData": null
        },
        "Transaction": {
            "Id": "110012",
            "Status": "SUCCESS",
            "PaymentMethod": "VISA/MASTER",
            "PaymentId": "07076389799322483474",
            "ReferenceId": "535818108932",
            "TrackId": "24-12-2025_3224834",
            "AuthorizationId": "108932",
            "TransactionDate": "2025-12-24T18:27:17.5370000Z",
            "ECI": "02",
            "IP": {
                "Address": "197.32.51.213",
                "Country": "Egypt"
            },
            "Error": {
                "Code": "",
                "Message": ""
            },
            "Card": {
                "NameOnCard": "JOHN DOE",
                "Number": "512345xxxxxx0008",
                "Token": "TKN-13ee9854-a358-492b-be24-2c91a6a80dc4",
                "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": []
    }
}
šŸ“˜

Webhook

You will receive the card token also in the webhook data.

Non-3D Secure Flow

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

Endpoint: POST /v3/payments(Create Payment)

{
    "PaymentMethod": "CARD",
    "Order": {
        "Amount": 20
    },
    "SaveCardOptions": {
        "SaveToken": true
    },
    "Customer": {
        "Reference": "ref-1"
    },
    "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": "6389804",
        "PaymentId": "07076389804322483974",
        "PaymentURL": "https://your-website.com/payment-callback?paymentId=07076389804322483974&Id=07076389804322483974",
        "PaymentCompleted": true,
        "TransactionDetails": {
            "Invoice": {
                "Id": "6389804",
                "Status": "PAID",
                "Reference": "2025001627",
                "CreationDate": "2025-12-24T18:28:48.4897351Z",
                "ExpirationDate": "2026-05-23T18:28:48.4897351Z",
                "ExternalIdentifier": null,
                "UserDefinedField": "",
                "MetaData": null
            },
            "Transaction": {
                "Id": "112092",
                "Status": "SUCCESS",
                "PaymentMethod": "VISA/MASTER",
                "PaymentId": "07076389804322483974",
                "ReferenceId": "535818111042",
                "TrackId": "24-12-2025_3224839",
                "AuthorizationId": "111042",
                "TransactionDate": "2025-12-24T18:28:49.9295716Z",
                "ECI": "",
                "IP": {
                    "Address": "",
                    "Country": ""
                },
                "Error": {
                    "Code": "",
                    "Message": ""
                },
                "Card": {
                    "NameOnCard": "JOHN DOE",
                    "Number": "512345xxxxxx0008",
                    "Token": "TKN-425fc686-bccc-4a81-9eac-a5b8384ac6f0",
                    "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": []
        }
    }
}
šŸ“˜

Cancel Token

If the customer wants to change their card information, or their card information has been expired or stolen, you have the possibility to cancel a credit card token by using the CancelToken endpoint.

Request using the card token:

Endpoint: POST /v3/payments(Create Payment)

Using 3DS flow with CVV

{
    "PaymentMethod": "CARD",
    "Order": {
        "Amount": 20
    },
    "Customer": {
        "Reference": "ref-1"
    },
    "SourceOfFund": {
        "Token": "TKN-425fc686-bccc-4a81-9eac-a5b8384ac6f0",
        "Card": {
            "SecurityCode": "100"
        }
    },
    "IntegrationUrls": {
        "Redirection": "https://your-website.com/payment-callback"
    }
}
{
    "IsSuccess": true,
    "Message": "",
    "ValidationErrors": null,
    "Data": {
        "InvoiceId": "6389809",
        "PaymentId": "07076389809322484474",
        "PaymentURL": "https://demo.MyFatoorah.com/En/KWT/PayInvoice/MpgsAuthentication?paymentId=07076389809322484474&sessionId=SESSION0002206942478H99513423M1&mfSessionId=",
        "PaymentCompleted": false,
        "TransactionDetails": null
    }
}

Using Non-3DS and BypassCVV

{
    "PaymentMethod": "CARD",
    "Order": {
        "Amount": 20
    },
    "SourceOfFund": {
        "Token": "TKN-425fc686-bccc-4a81-9eac-a5b8384ac6f0"
    },
    "IntegrationUrls": {
        "Redirection": "https://your-website.com/payment-callback"
    },
    "3DS": {
        "Enabled": false
    }
}
{
    "IsSuccess": true,
    "Message": "",
    "ValidationErrors": null,
    "Data": {
        "InvoiceId": "6418111",
        "PaymentId": "07076418111324568272",
        "PaymentURL": "https://your-website.com/payment-callback?paymentId=07076418111324568272&Id=07076418111324568272",
        "PaymentCompleted": true,
        "TransactionDetails": {
            "Invoice": {
                "Id": "6418111",
                "Status": "PAID",
                "Reference": "2026000121",
                "CreationDate": "2026-01-07T07:54:04.0723477Z",
                "ExpirationDate": "2026-06-06T07:54:04.0723477Z",
                "ExternalIdentifier": null,
                "UserDefinedField": "",
                "MetaData": null
            },
            "Transaction": {
                "Id": "81615",
                "Status": "SUCCESS",
                "PaymentMethod": "VISA/MASTER",
                "PaymentId": "07076418111324568272",
                "ReferenceId": "600707081615",
                "TrackId": "07-01-2026_3245682",
                "AuthorizationId": "081615",
                "TransactionDate": "2026-01-07T07:54:05.6126662Z",
                "ECI": "",
                "IP": {
                    "Address": "",
                    "Country": ""
                },
                "Error": {
                    "Code": "",
                    "Message": ""
                },
                "Card": {
                    "NameOnCard": "JOHN DOE",
                    "Number": "512345xxxxxx0008",
                    "Token": "TKN-425fc686-bccc-4a81-9eac-a5b8384ac6f0",
                    "PanHash": "b888aa5f23a817883d4d12c74044bab1ae6ee65dc8d6e11515394aba452b273b",
                    "ExpiryMonth": "01",
                    "ExpiryYear": "39",
                    "Brand": "Mastercard",
                    "Issuer": "Test Bank",
                    "IssuerCountry": "KWT",
                    "FundingMethod": "credit"
                }
            },
            "Customer": {
                "Name": "Anonymous",
                "Mobile": "+965",
                "Email": ""
            },
            "Amount": {
                "BaseCurrency": "KWD",
                "ValueInBaseCurrency": "20",
                "ServiceCharge": "0.2",
                "ServiceChargeVAT": "0.03",
                "ReceivableAmount": "19.77",
                "DisplayCurrency": "KWD",
                "ValueInDisplayCurrency": "20",
                "PayCurrency": "KWD",
                "ValueInPayCurrency": "20"
            },
            "Suppliers": []
        }
    }
}
šŸ“˜

Approval Needed

In case you need to use Bypass3DS and BypassCVV you need to contact your account manager to activate it for your account.

šŸ“˜

FastPay

Fastpay is different from Bypass3DS where Fastpay will always bypass the OTP page for a tokenized card that is 3DSVerified before. Fastpay overrides Bypass3DS.

Updated 8 days ago