Idempotency

Overview

Idempotency allows you to safely retry API requests without creating duplicate operations. You can label an API request with an Idempotency-Key, and the system will cache the original request for 250 minutes. If the same request is sent again using the same Idempotency-Key within this period, the system will return the exact same response instead of processing the request again.

This feature helps to:

Prevent sending multiple duplicate requests.
Avoid completing the same payment or refund more than once

How It Works

To use idempotency, include the following header in your API request:

Idempotency-Key: <unique-value>

The Idempotency-Key should be a unique value for each operation.
If a request with the same key is received again within the cache duration, the previously cached response will be returned.

curl --location 'https://apitest.myfatoorah.com/v3/payments' \
--header 'Idempotency-Key: req20' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--header 'Cookie: X-Oracle-BMC-LBS-Route=56f55515c92256899687eb6a49595b2f10a5707c' \
--data '{
    "PaymentMethod": "CARD",
    "Order": {
        "Amount": 800,
        "Currency": "SAR"
    },
    "SourceOfFund": {
        "Token": "TKN-ac22319e-617f-4d3b-9759-20293e833e89"
    }
}'

{
    "IsSuccess": true,
    "Message": "",
    "ValidationErrors": null,
    "Data": {
        "InvoiceId": "6548530",
        "PaymentId": "07076548530334809573",
        "PaymentURL": "https://demo.MyFatoorah.com/En/KWT/PayInvoice/Result?paymentId=07076548530334809573",
        "PaymentCompleted": true,
        "TransactionDetails": {
            "Invoice": {
                "Id": "6548530",
                "Status": "PAID",
                "Reference": "2026003084",
                "CreationDate": "2026-02-26T12:23:04.6122368Z",
                "ExpirationDate": "2026-07-26T12:23:04.6122368Z",
                "ExternalIdentifier": null,
                "UserDefinedField": "",
                "MetaData": null
            },
            "Transaction": {
                "Id": "137119",
                "Status": "SUCCESS",
                "PaymentMethod": "VISA/MASTER (SAR)",
                "PaymentId": "07076548530334809573",
                "ReferenceId": "605712137119",
                "TrackId": "26-02-2026_3348095",
                "AuthorizationId": "137119",
                "TransactionDate": "2026-02-26T12:23:05.5133690Z",
                "ECI": "",
                "IP": {
                    "Address": "",
                    "Country": ""
                },
                "Error": {
                    "Code": "",
                    "Message": ""
                },
                "Card": {
                    "NameOnCard": "test",
                    "Number": "512345xxxxxx0008",
                    "Token": "TKN-ac22319e-617f-4d3b-9759-20293e833e89",
                    "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": "64.772",
                "ServiceCharge": "0.324",
                "ServiceChargeVAT": "0.049",
                "ReceivableAmount": "64.407",
                "DisplayCurrency": "KWD",
                "ValueInDisplayCurrency": "800",
                "PayCurrency": "SAR",
                "ValueInPayCurrency": "800"
            },
            "Suppliers": []
        },
        "Card": null
    }
}

curl --location 'https://apitest.myfatoorah.com/v3/payments' \
--header 'Idempotency-Key: req20' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--header 'Cookie: X-Oracle-BMC-LBS-Route=56f55515c92256899687eb6a49595b2f10a5707c' \
--data '{
    "PaymentMethod": "CARD",
    "Order": {
        "Amount": 1000,
        "Currency": "SAR"
    },
    "SourceOfFund": {
        "Token": "TKN-ac22319e-617f-4d3b-9759-20293e833e89"
    }
}'

{
    "IsSuccess": true,
    "Message": "",
    "ValidationErrors": null,
    "Data": {
        "InvoiceId": "6548530",
        "PaymentId": "07076548530334809573",
        "PaymentURL": "https://demo.MyFatoorah.com/En/KWT/PayInvoice/Result?paymentId=07076548530334809573",
        "PaymentCompleted": true,
        "TransactionDetails": {
            "Invoice": {
                "Id": "6548530",
                "Status": "PAID",
                "Reference": "2026003084",
                "CreationDate": "2026-02-26T12:23:04.6122368Z",
                "ExpirationDate": "2026-07-26T12:23:04.6122368Z",
                "ExternalIdentifier": null,
                "UserDefinedField": "",
                "MetaData": null
            },
            "Transaction": {
                "Id": "137119",
                "Status": "SUCCESS",
                "PaymentMethod": "VISA/MASTER (SAR)",
                "PaymentId": "07076548530334809573",
                "ReferenceId": "605712137119",
                "TrackId": "26-02-2026_3348095",
                "AuthorizationId": "137119",
                "TransactionDate": "2026-02-26T12:23:05.5133690Z",
                "ECI": "",
                "IP": {
                    "Address": "",
                    "Country": ""
                },
                "Error": {
                    "Code": "",
                    "Message": ""
                },
                "Card": {
                    "NameOnCard": "test",
                    "Number": "512345xxxxxx0008",
                    "Token": "TKN-ac22319e-617f-4d3b-9759-20293e833e89",
                    "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": "64.772",
                "ServiceCharge": "0.324",
                "ServiceChargeVAT": "0.049",
                "ReceivableAmount": "64.407",
                "DisplayCurrency": "KWD",
                "ValueInDisplayCurrency": "800",
                "PayCurrency": "SAR",
                "ValueInPayCurrency": "800"
            },
            "Suppliers": []
        },
        "Card": null
    }
}

Endpoints That Support Idempotency

🚧
Availability
This feature is currently available only in the following countries:

Kuwait

Saudi Arabia