Updating Payment Status Guidelines

Overview

In this section, we will cover the paths available to update the order status on your system after the customer makes the payment on the MyFatoorah system.

We are covering the:

• Redirection to CallBack/Error URL
• Transactions Webhook
• Handling both the webhook and the redirection together

CallBackUrl/ErrorUrl:

After the customer makes a payment, MyFatoorah redirects the customer to the provided CallBackUrl/ErrorUrl appending the PaymentId to the URL.

Steps:

• Call the GetPaymentStatus endpoint using the PaymentId.
• In the response of GetPaymentStatus, you will get the order payment status.
• Display the payment result to your customer OR redirect him to a suitable page based on the payment status.

🚧

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.

🚧

Redirection Reliability

Relying on redirection may not always be reliable, as it depends on the customer's behavior and network conditions. For instance, redirection may fail if the customer closes the page before it completes or if a slow network prevents the redirection process from finishing successfully.

👍

CallBackUrl/ErrorUrl

We recommend not relying on whether the redirection happened to the CallBackUrl and ErrorUrl to update the payment status. Instead, we recommend relying on the response from GetPaymentStatus.

Webhook:

After the customer completes the payment attempt, MyFatoorah triggers a webhook event to your server with the status of the transaction.

Steps:

• Validate the webhook signature to confirm that the webhook event is from MyFatoorah.
• If you want extra fields about the transaction, call the GetPaymentStatus endpoint. Otherwise, move on to the next step.
• Update the Payment Status of the order on your system.
• Return HTTP 200 OK to MyFatoorah POST request of the webhook.

📘

MyFatoorah Webhook Retries

MyFatoorah attempts to trigger the webhook to your server three consecutive times, each time for nearly 100 seconds. If we get a successful response from your side, we will not try to trigger it again.

If after the third attempt, we still get a failure status from your server, we will log the webhook event on our side and mark it as failed. We will not attempt to send the webhook again after the third attempt.

If we get a timeout from your server without getting any response, we will not attempt to send the webhook again after the third attempt.

Updating Order Sequence:

We recommend utilizing both the Webhook and GetPaymentStatus from MyFatoorah to make sure you get the latest payment status update from MyFatoorah side. In this section we will cover the two possible flows to occur if you're using both of them.

Cases:

Getting the Redirection after the Webhook:

• Check if the Payment Status is updated by the webhook.
• If updated, redirect to the result page.
• If not updated, continue the redirection steps.

Getting the Webhook after the Redirection:

• Check if the Payment Status is updated by GetPaymentStatus.
• If updated, return HTTP 200 OK.
• If not, continue the webhook steps.

🚧

Multiple Webhook Calls

In some rare cases, your webhook endpoint may get multiple calls. This behavior is happening because of some payment methods (e.g: KNET) are sending multiple webhooks to MyFatoorah. In this case, a webhook event indicating a successful payment status overrides any other status (even if received first).

📘

Success Status

In MyFatoorah system, the Success Payment Status is final and cannot be override. If you get the payment status as success, you can safely mark the order as paid on your system.

Resilience:

This section of the page provides recommended solutions to ensure resilience in case GetPaymentStatus becomes unreachable.

Cases:

GetPaymentStatus is not Reachable:

• Schedule a retry to call GetPaymentStatus three times. Set 5 seconds as the wait time between each retry.
• It is advised to set the timeout to at least 30 seconds to ensure that you get a response even in high load circumstances.
• If the MyFatoorah endpoint is unreachable after 3 retry attempts, set the status to Pending_Status_Update and decide on the next steps:
  • Schedule a reattempt after a defined period.
  • Handle the process manually.

📘

Webhook vs CallBack/Error URL

Both the Webhook and Redirection are triggered from MyFatoorah at the same time. However, it is most likely that you will get the webhook event first because it is a server-to-server integration making it independent of the slowing factors the redirection might face like poor network connections, or slow devices.