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 nstFi system.

We are covering the:

• Redirection to RedirectionUrl
• Transactions Webhook
• Handling both the webhook and the redirection together

RedirectionUrl:

After the customer makes a payment, nstFi redirects the customer to the provided redirection URL, appending the PaymentId to the URL.

Steps:

• Call the (Get Payment Details) endpoint using the PaymentId.
• In the response of GET Payments, you will get the order payment status.
• Display the payment result to your customer OR redirect them to a suitable page based on the payment status.

🚧 Many calls to GET Payments

GET Payments 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.

Webhook:

After the customer completes the payment attempt, nstFi 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 nstFi.
• Update the Payment Status of the order on your system.
• Return HTTP 200 OK to nstFi POST request of the webhook.

📘 nstFi Webhook Retries

Webhook V2:

You can configure the retries from the dashboard by setting how many times and how often the retries should happen.

Webhook V1:

nstFi attempts to trigger the webhook to your server four times, each time for nearly 100 seconds, with a delay 10 seconds between each attempt. If we get a successful response from your side, we will not try to trigger it again.

If after the fourth 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 fourth attempt.

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

Updating Order Sequence:

We recommend utilizing both the Webhook and Get Payment Details from nstFi to make sure you get the latest payment status update from nstFi 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 GET Payments.
• 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 nstFi. In this case, a webhook event indicating a successful payment status overrides any other status (even if received first).

📘 Success Status

In nstFi 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:

GET Payments is not Reachable:

• Schedule a retry to call GET Payments 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 nstFi 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 nstFi 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.