GetPaymentStatus

Overview

The "GetPaymentStatus" endpoint is a POST request. It is used to check the status of your invoice to assure that the payment has been done successfully or not. Detailed functionality of how to use this endpoint is explained in the Payment Inquiry section.

The endpoint on Swagger is: Payment_GetPaymentStatus.

Now, we are going to declare the endpoint and its models along with each accepted parameter and possible value.

📘
Request Header
Add "Authorization": "Bearer {Token}" to request header. Token of demo configuration can be found here.

🚧
Many calls to GetPaymentStatus
GetPaymentStatus endpoint has a rate limit. If you are going to send a lot of requests to the endpoint in a short duration, please contact the account manager to increase the rate limit for your account.

Request Model

The request is a POST request with the following parameters:

Input Parameter	Type	Description
Key	string	Refers to the invoice number or payment ID based on the key type
KeyType	string	"InvoiceId" Refers to the invoice number that is generated by MyFatoorah "PaymentId" the value is returned upon having any update on the invoice payment "CustomerReference" The reference used to link your orders in the store

Input Parameter

Type

Description

Key

string

Refers to the invoice number or payment ID based on the key type

KeyType

string

"InvoiceId" Refers to the invoice number that is generated by MyFatoorah

"PaymentId" the value is returned upon having any update on the invoice payment

"CustomerReference" The reference used to link your orders in the store

👍
PaymentId
We strongly recommend to use the value PaymentId (which is returned in the CallBackURL ) to inquire the payment status, this will get you full information about the invoice that you can use within your application. As long as there is not payment or transactions done for a certain invoice, you can inquire using InvoiceId

Response Model

After viewing the Response Model that you will get as a result of your request, here, you will find full details about the Data Model of this API endpoint. Let's check it and its contents.

Response Field	Type	Description
InvoiceId	number	Represents the invoice ID that was used in the inquiry call
InvoiceStatus	string	"Pending" "Paid" "Canceled"
InvoiceReference	string	Invoice reference that is generated by MyFatoorah
CustomerReference	string	The customer reference data associated with the invoice
CreatedDate	string	The creation date of the invoice
ExpiryDate	string	The expiry date for the invoice
InvoiceValue	number	Invoice total value with the actual base account currency
Comments	string	Comments that are associated with the invoice (mainly used portal use users)
CustomerName	string	The customer name that was save along with the invoice
CustomerMobile	string	Customer mobile number
CustomerEmail	string	Customer email address
UserDefinedField	string	The user defined filed that was stored during the invoice creation
InvoiceDisplayValue	string	Invoice value that is displayed in case of different currency from the base one
DueDeposit	number	The amount that will be deposited to the vendor
DepositStatus	string	The deposit status of the invoice, if it is "Deposited" or "Not Deposited".
InvoiceItems	Array of InvoiceItemModel objects
InvoiceTransactions	Array of InvoiceTransactionModel objects

InvoiceItems Model

Response Field	Type	Description
ItemName	string	Invoice item name that is stored with the invoice
Quantity	integer	Item quantity
UnitPrice	number	Item unit price
Weight	number	100 >= Weight > 0 Weight in kg
Width	number	200 >= Width > 0 Width in cm
Height	number	160 >= Height > 0 Height in cm
Depth	number	200 >= Depth > 0 Depth in cm

InvoiceTransactions Model

Response Field	Type	Description
TransactionDate	string	The date of the transaction related to the invoice
PaymentGateway	string	The gateway the transaction was processed through
ReferenceId	string	The reference that is generated by the payment gateway
TrackId	string	The track number that is used to track the transaction with the gateway
TransactionId	string	The transaction ID
PaymentId	string	The payment ID that is assigned to this transaction
AuthorizationId	string	The authorization ID that is assigned to this transaction
TransactionStatus	string	The status of the transaction as InProgress Succss Failed Canceled Authorize *
TransationValue	string	The value of the transaction
CustomerServiceCharge	string	The service charges considered on the customer during the transaction
TotalServiceCharge	string	Total service charge deducted from MyFatoorah side
DueValue	string	The value of this transaction
PaidCurrency	string	The currency that was used to pay for the transaction
PaidCurrencyValue	string	The currency value that was used to pay for the transaction
VatAmount	float	The value of the VAT amount for the transaction
Currency	string	Transaction currency
Error	string	The error message that might be associated with the transaction. This error is from the acquirer bank/platform
CardNumber	string	The masked card number that was used for the transaction.
ErrorCode	string	The MyFatoorah error code. Kindly refer to the Error Codes table.
ECI	string	The ECI record of the transaction.
Card	object	Contains details about the card used for payment.

📘
Transactions
Transactions information are totally related to the gateway response that came from the acquirer bank / platform. Not necessarily to have information to all the fields, and this was designed only to provide you information about all transactions that happened for a certain invoice

Card Model

Response Field	Type	Description
NameOnCard	string	The name of the cardholder entered by the payer.
Number	string	The masked card number.
PanHash	string	A unique identifier for the PAN.
ExpiryMonth	string	Expiry month entered by the customer.
ExpiryYear	string	Expiry year entered by the customer.
Brand	string	Visa/Mastercard/Mada
Issuer	string	Name of the issuer bank
IssuerCountry	string	The issuer country of the card
FundingMethod	string	The funding method of the card (e.g.: debit, credit, prepaid)

Error Codes

Code	Explanation
MF001	3DS authentication failed, possible reasons (user inserted a wrong password, cardholder/card issuer are not enrolled with 3DS, or the issuer bank has technical issue).
MF002	The issuer bank has declined the transaction, possible reasons (invalid card details, insufficient funds, denied by risk, the card is expired/held, or card is not enabled for online purchase).
MF003	The transaction has been blocked from the gateway, possible reasons (unsupported card BIN, fraud detection, or security blocking rules).
MF004	Insufficient funds
MF005	Session timeout
MF006	Transaction canceled
MF007	The card is expired.
MF008	The card issuer doesn't respond.
MF009	Denied by Risk
MF010	Wrong Security Code
MF020	Unspecified Failure

Sample Message

Now, you can get all the information about the invoice transactions and suppliers - if exist - and the deposit amount of each supplier.

{
    "Key": "5822968",
    "KeyType": "invoiceid" 
}

{
    "IsSuccess": true,
    "Message": "",
    "ValidationErrors": null,
    "Data": {
        "InvoiceId": 5822968,
        "InvoiceStatus": "Paid",
        "InvoiceReference": "2025051959",
        "CustomerReference": "1JjSM4evVcBkqpFHFxw7bg1cZhMmZiQJ",
        "CreatedDate": "2025-06-11T11:39:00.1",
        "ExpiryDate": "November 8, 2025",
        "ExpiryTime": "11:39:00.100",
        "InvoiceValue": 0.510,
        "Comments": null,
        "CustomerName": "Kamren",
        "CustomerMobile": "+966501848457",
        "CustomerEmail": "[email protected]",
        "UserDefinedField": "CK-checkout",
        "InvoiceDisplayValue": "0.510 KD",
        "DueDeposit": 0.498,
        "DepositStatus": "Not Deposited",
        "InvoiceItems": [],
        "InvoiceTransactions": [
            {
                "TransactionDate": "2025-06-11T11:39:20.7766667",
                "PaymentGateway": "VISA/MASTER",
                "ReferenceId": "516208128633",
                "TrackId": "11-06-2025_2785321",
                "TransactionId": "128633",
                "PaymentId": "07075822968278532174",
                "AuthorizationId": "659310",
                "TransactionStatus": "Succss",
                "TransationValue": "0.510",
                "CustomerServiceCharge": "0.000",
                "TotalServiceCharge": "0.010",
                "DueValue": "0.510",
                "PaidCurrency": "KD",
                "PaidCurrencyValue": "0.510",
                "VatAmount": "0.002",
                "IpAddress": "102.43.239.185",
                "Country": "Egypt",
                "Currency": "KD",
                "Error": null,
                "CardNumber": "545454xxxxxx5454",
                "ErrorCode": "",
                "ECI": "02",
                "Card": {
                    "NameOnCard": "test",
                    "Number": "545454xxxxxx5454",
                    "PanHash": "3cc8217a6aad545082e07e563edeec444ce961a2468fa1a5eddf238969095735",
                    "ExpiryMonth": "12",
                    "ExpiryYear": "34",
                    "Brand": "Mastercard",
                    "Issuer": "Test Bank",
                    "IssuerCountry": "KWT",
                    "FundingMethod": "credit"
                }
            }
        ],
        "Suppliers": []
    }
}

{
    "IsSuccess": true,
    "Message": "",
    "ValidationErrors": null,
    "Data": {
        "InvoiceId": 5822978,
        "InvoiceStatus": "Pending",
        "InvoiceReference": "2025051960",
        "CustomerReference": "3fcw1GC85zgyyfzt7Db5KMNpxcsCX",
        "CreatedDate": "2025-06-11T11:46:57.377",
        "ExpiryDate": "November 8, 2025",
        "ExpiryTime": "11:46:57.377",
        "InvoiceValue": 51.000,
        "Comments": null,
        "CustomerName": "Augusta",
        "CustomerMobile": "+966501848457",
        "CustomerEmail": "[email protected]",
        "UserDefinedField": "CK-checkout",
        "InvoiceDisplayValue": "51.000 KD",
        "DueDeposit": 0.000,
        "DepositStatus": "Not Deposited",
        "InvoiceItems": [],
        "InvoiceTransactions": [
            {
                "TransactionDate": "2025-06-11T11:47:29.9433333",
                "PaymentGateway": "VISA/MASTER",
                "ReferenceId": "07075822978278532874",
                "TrackId": "11-06-2025_2785328",
                "TransactionId": "07075822978278532874",
                "PaymentId": "07075822978278532874",
                "AuthorizationId": "07075822978278532874",
                "TransactionStatus": "Failed",
                "TransationValue": "51.000",
                "CustomerServiceCharge": "0.000",
                "TotalServiceCharge": "0.995",
                "DueValue": "51.000",
                "PaidCurrency": "KD",
                "PaidCurrencyValue": "51.000",
                "VatAmount": "0.149",
                "IpAddress": "102.43.239.185",
                "Country": "Egypt",
                "Currency": "KD",
                "Error": "DECLINED : Do not honour",
                "CardNumber": "450875xxxxxx1019",
                "ErrorCode": "MF002",
                "ECI": "05",
                "Card": {
                    "NameOnCard": "test",
                    "Number": "450875xxxxxx1019",
                    "PanHash": "b4eda25d8a64929c02240406fc5cdc5417e4d021e1d055e43edb61e8d4903cfa",
                    "ExpiryMonth": "12",
                    "ExpiryYear": "34",
                    "Brand": "Visa",
                    "Issuer": "The Co-Operative Bank Plc",
                    "IssuerCountry": "GBR",
                    "FundingMethod": "debit"
                }
            }
        ],
        "Suppliers": [
            {
                "SupplierCode": 1,
                "SupplierName": "    Leuschke LLC",
                "InvoiceShare": 51.000,
                "ProposedShare": null,
                "DepositShare": 49.856
            }
        ]
    }
}