Guides

Payment Inquiry

Get the status of your transaction

Suggest Edits

Introduction

By calling the GetPaymentStatus endpoint, you get the status of your invoice to check whether the payment is done or not.

MyFatoorah returns a unique InvoiceId parameter in the response body of the SendPayment and ExecutePayment endpoints. Use this InvoiceId parameter to fetch all details about this invoice and its transactions.

Moreover, after a successful/failed payment, MyFatoorah returns a PaymentId as a parameter in the CallBack/Error URL. This PaymentId parameter is used to inquire about the payment information and its status.

In addition, if you provided a customer reference to the request body of the SendPayment and ExecutePayment endpoints, you can check your payment data using the same value sent in the CustomerReference parameter.

👍

Good Practice

As a good practice, to ensure the payment response is returned from the MyFatoorah end, we encourage you to call the GetPaymentStatus endpoint once you receive the result on your page.

How it works

MyFatoorah invoice may have more than one transaction. The InvoiceStatus parameter represents the overall status of the invoice.

  • The invoice will be "Paid" if there is a successful transaction (with "Succss" status).
  • The invoice will be "Pending" if all transactions have "InProgress" or "Failed" status.

You can call the GetPaymentStatus endpoint using the InvoiceId, PaymentId, or CustomerReference. The latter differs from each transaction. If you request the GetPaymentStatus endpoint using InvoiceId as KeyType (i.e Key: 599578), the response will be the same for all requests of GetPaymentStatus endpoint using PaymentId as KeyType (i.e Key: 100202108342170497, 060659957848741164, 100202108357808709, and 060659957848741765). Also, the response is the same for the request of GetPaymentStatus endpoint using CustomerReference as KeyType

Example Response:

{
  "Key": "912952",
  "KeyType": "invoiceid"
}
OR
{
  "Key": "100202120965964751",
  "KeyType": "PaymentId"
}
OR
{
  "Key": "order_1",
  "KeyType": "CustomerReference"
}

{
  "IsSuccess": true,
  "Message": "",
  "ValidationErrors": null,
  "Data": {
    "InvoiceId": 915102,
    "InvoiceStatus": "Paid",
    "InvoiceReference": "2021005465",
    "CustomerReference": "order_1",
    "CreatedDate": "2021-07-28T13:25:06.153",
    "ExpiryDate": "July 31, 2021",
    "InvoiceValue": 12345,
    "Comments": "",
    "CustomerName": "test inquiry invoices",
    "CustomerMobile": "",
    "CustomerEmail": null,
    "UserDefinedField": null,
    "InvoiceDisplayValue": "12,345.000 KD",
    "InvoiceItems": [],
    "InvoiceTransactions": [
      {
        "TransactionDate": "2021-07-28T13:25:20.1",
        "PaymentGateway": "KNET",
        "ReferenceId": "060691510275442662",
        "TrackId": "28-07-2021_754426",
        "TransactionId": "060691510275442662",
        "PaymentId": "100202120933974848",
        "AuthorizationId": "060691510275442662",
        "TransactionStatus": "Failed",
        "TransationValue": "12,345.000",
        "CustomerServiceCharge": "0.000",
        "DueValue": "12,345.000",
        "PaidCurrency": "KD",
        "PaidCurrencyValue": "12,345.000",
        "Currency": "KD",
        "Error": "Transaction canceled!",
        "CardNumber": null,
        "ErrorCode": "MF006"
      },
      {
        "TransactionDate": "2021-07-28T13:25:51.807",
        "PaymentGateway": "MADA",
        "ReferenceId": "060691510275442762",
        "TrackId": "28-07-2021_754427",
        "TransactionId": "060691510275442762",
        "PaymentId": "060691510275442762",
        "AuthorizationId": "060691510275442762",
        "TransactionStatus": "InProgress",
        "TransationValue": "12,345.000",
        "CustomerServiceCharge": "185.175",
        "DueValue": "12,530.180",
        "PaidCurrency": "SR",
        "PaidCurrencyValue": "154,622.430",
        "Currency": "KD",
        "Error": null,
        "CardNumber": null,
        "ErrorCode": ""
      },
      {
        "TransactionDate": "2021-07-28T13:26:09.13",
        "PaymentGateway": "Visa/Master Direct",
        "ReferenceId": "120910000002",
        "TrackId": "28-07-2021_754428",
        "TransactionId": "202120934050845",
        "PaymentId": "602202120965954201",
        "AuthorizationId": "000000",
        "TransactionStatus": "Failed",
        "TransationValue": "12,345.000",
        "CustomerServiceCharge": "0.000",
        "DueValue": "12,345.000",
        "PaidCurrency": "KD",
        "PaidCurrencyValue": "12,345.000",
        "Currency": "KD",
        "Error": "Transaction not Captured!",
        "CardNumber": "545301xxxxxx5539",
        "ErrorCode": "MF002"
      },
      {
        "TransactionDate": "2021-07-28T13:27:33.367",
        "PaymentGateway": "KNET",
        "ReferenceId": "120910000653",
        "TrackId": "28-07-2021_754431",
        "TransactionId": "202120965959207",
        "PaymentId": "100202120965964751",
        "AuthorizationId": "B77780",
        "TransactionStatus": "Succss",
        "TransationValue": "12,345.000",
        "CustomerServiceCharge": "0.000",
        "DueValue": "12,345.000",
        "PaidCurrency": "KD",
        "PaidCurrencyValue": "12,345.000",
        "Currency": "KD",
        "Error": null,
        "CardNumber": null,
        "ErrorCode": ""
      }
    ],
    "Suppliers": []
  }
}

Payment Status

If you use the GetPaymentStatus endpoint with PaymentId as a KeyType (i.e Key: 100202108342170497), you need to check InvoiceStatus first.

  • If the invoice is still in Pending status, you should search in the InvoiceTransactions array for the transaction with the same key of PaymentId (i.e Key: 100202108342170497) to get the Error of this transaction when its status is Failed, but if the transaction is in InProgress status, then the customer has not tried to pay the invoice till this moment.

  • If the invoice is Paid, you should search in the InvoiceTransactions array for the transaction with ("Succss" status), and you can fetch its data like ReferenceId.

Invoice Status

If you use the GetPaymentStatus endpoint with the InvoiceId as a KeyType (i.e Key: 599578), you need to check InvoiceStatus first.

  • If the invoice is still in Pending status, you should get the last created transaction that occurred in the InvoiceTransactions array by the recent date (usually the one at the end of the array). Then, you can fetch its data like ReferenceId.

  • If the invoice is Paid, you should search in the InvoiceTransactions array for the transaction with ("Succss" status), and you can fetch its data like ReferenceId.

📘

CustomerReference

If you use the GetPaymentStatus endpoint with the CustomerReference as a KeyType (i.e Key: order_1), you should deal with the data exactly as if you retrieve it using the InvoiceId key's type.

🚧

CustomerReference is not unique

The CustomerReference parameter is not unique. When using the same CustomerReference multiple times, the GetPaymentStatus endpoint returns the last invoice created for this customer reference.

Updated 9 months ago