GetPaymentStatus
Endpoint
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:
<th>
Type
</th>
<th>
Description
</th>
</tr>
<td>
string
</td>
<td>
Refers to the invoice number or payment ID based on the key type
</td>
</tr>
<tr>
<td>
**KeyType**
</td>
<td>
string
</td>
<td>
"**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
</td>
</tr>
| Input Parameter |
|---|
| **Key** |
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.
<th>
Type
</th>
<th>
Description
</th>
</tr>
<td>
number
</td>
<td>
Represents the invoice ID that was used in the inquiry call
</td>
</tr>
<tr>
<td>
**InvoiceStatus**
</td>
<td>
string
</td>
<td>
"**Pending**"\
"**Paid**"\
"**Canceled**"
</td>
</tr>
<tr>
<td>
**InvoiceReference**
</td>
<td>
string
</td>
<td>
Invoice reference that is generated by MyFatoorah
</td>
</tr>
<tr>
<td>
**CustomerReference**
</td>
<td>
string
</td>
<td>
The customer reference data associated with the invoice
</td>
</tr>
<tr>
<td>
**CreatedDate**
</td>
<td>
string
</td>
<td>
The creation date of the invoice
</td>
</tr>
<tr>
<td>
**ExpiryDate**
</td>
<td>
string
</td>
<td>
The expiry date for the invoice
</td>
</tr>
<tr>
<td>
**InvoiceValue**
</td>
<td>
number
</td>
<td>
Invoice total value with the actual base account currency
</td>
</tr>
<tr>
<td>
**Comments**
</td>
<td>
string
</td>
<td>
Comments that are associated with the invoice (mainly used portal use users)
</td>
</tr>
<tr>
<td>
**CustomerName**
</td>
<td>
string
</td>
<td>
The customer name that was save along with the invoice
</td>
</tr>
<tr>
<td>
**CustomerMobile**
</td>
<td>
string
</td>
<td>
Customer mobile number
</td>
</tr>
<tr>
<td>
**CustomerEmail**
</td>
<td>
string
</td>
<td>
Customer email address
</td>
</tr>
<tr>
<td>
**UserDefinedField**
</td>
<td>
string
</td>
<td>
The user defined filed that was stored during the invoice creation
</td>
</tr>
<tr>
<td>
**InvoiceDisplayValue**
</td>
<td>
string
</td>
<td>
Invoice value that is displayed in case of different currency from the base one
</td>
</tr>
<tr>
<td>
**DueDeposit**
</td>
<td>
number
</td>
<td>
The amount that will be deposited to the vendor
</td>
</tr>
<tr>
<td>
**DepositStatus**
</td>
<td>
string
</td>
<td>
The deposit status of the invoice, if it is "Deposited" or "Not Deposited".
</td>
</tr>
<tr>
<td>
**InvoiceItems**
</td>
<td>
Array of [InvoiceItemModel](#invoiceitemmodel) objects
</td>
<td>
</td>
</tr>
<tr>
<td>
**InvoiceTransactions**
</td>
<td>
Array of [InvoiceTransactionModel](#invoicetransactionmodel) objects
</td>
<td>
</td>
</tr>
| Response Field |
|---|
| **InvoiceId** |
InvoiceItems Model
<th>
Type
</th>
<th>
Description
</th>
</tr>
<td>
string
</td>
<td>
Invoice item name that is stored with the invoice
</td>
</tr>
<tr>
<td>
**Quantity**
</td>
<td>
integer
</td>
<td>
Item quantity
</td>
</tr>
<tr>
<td>
**UnitPrice**
</td>
<td>
number
</td>
<td>
Item unit price
</td>
</tr>
<tr>
<td>
**Weight**
</td>
<td>
number
</td>
<td>
100 >= Weight > 0\
Weight in kg
</td>
</tr>
<tr>
<td>
**Width**
</td>
<td>
number
</td>
<td>
200 >= Width > 0\
Width in cm
</td>
</tr>
<tr>
<td>
**Height**
</td>
<td>
number
</td>
<td>
160 >= Height > 0\
Height in cm
</td>
</tr>
<tr>
<td>
**Depth**
</td>
<td>
number
</td>
<td>
200 >= Depth > 0\
Depth in cm
</td>
</tr>
| Response Field |
|---|
| **ItemName** |
InvoiceTransactions Model
<th>
Type
</th>
<th>
Description
</th>
</tr>
<td>
string
</td>
<td>
The date of the transaction related to the invoice
</td>
</tr>
<tr>
<td>
**PaymentGateway**
</td>
<td>
string
</td>
<td>
The gateway the transaction was processed through
</td>
</tr>
<tr>
<td>
**ReferenceId**
</td>
<td>
string
</td>
<td>
The reference that is generated by the payment gateway
</td>
</tr>
<tr>
<td>
**TrackId**
</td>
<td>
string
</td>
<td>
The track number that is used to track the transaction with the gateway
</td>
</tr>
<tr>
<td>
**TransactionId**
</td>
<td>
string
</td>
<td>
The transaction ID
</td>
</tr>
<tr>
<td>
**PaymentId**
</td>
<td>
string
</td>
<td>
The payment ID that is assigned to this transaction
</td>
</tr>
<tr>
<td>
**AuthorizationId**
</td>
<td>
string
</td>
<td>
The authorization ID that is assigned to this transaction
</td>
</tr>
<tr>
<td>
**TransactionStatus**
</td>
<td>
string
</td>
<td>
The status of the transaction as
* \*InProgress\
Succss\
Failed\
Canceled\
Authorize \*\*
</td>
</tr>
<tr>
<td>
**TransationValue**
</td>
<td>
string
</td>
<td>
The value of the transaction
</td>
</tr>
<tr>
<td>
**CustomerServiceCharge**
</td>
<td>
string
</td>
<td>
The service charges considered on the customer during the transaction
</td>
</tr>
<tr>
<td>
**TotalServiceCharge**
</td>
<td>
string
</td>
<td>
Total service charge deducted from MyFatoorah side
</td>
</tr>
<tr>
<td>
**DueValue**
</td>
<td>
string
</td>
<td>
The value of this transaction
</td>
</tr>
<tr>
<td>
**PaidCurrency**
</td>
<td>
string
</td>
<td>
The currency that was used to pay for the transaction
</td>
</tr>
<tr>
<td>
**PaidCurrencyValue**
</td>
<td>
string
</td>
<td>
The currency value that was used to pay for the transaction
</td>
</tr>
<tr>
<td>
**VatAmount**
</td>
<td>
float
</td>
<td>
The value of the VAT amount for the transaction
</td>
</tr>
<tr>
<td>
**Currency**
</td>
<td>
string
</td>
<td>
Transaction currency
</td>
</tr>
<tr>
<td>
**Error**
</td>
<td>
string
</td>
<td>
The error message that might be associated with the transaction.\
This error is from the acquirer bank/platform
</td>
</tr>
<tr>
<td>
**CardNumber**
</td>
<td>
string
</td>
<td>
The masked card number that was used for the transaction.
</td>
</tr>
<tr>
<td>
**ErrorCode**
</td>
<td>
string
</td>
<td>
The MyFatoorah error code. Kindly refer to the [Error Codes](#error-codes) table.
</td>
</tr>
<tr>
<td>
**ECI**
</td>
<td>
string
</td>
<td>
The ECI record of the transaction.
</td>
</tr>
<tr>
<td>
**Card**
</td>
<td>
object
</td>
<td>
Contains details about the card used for payment.
</td>
</tr>
| Response Field |
|---|
| **TransactionDate** |
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
}
]
}
}
Updated 2 days ago