Handling Order Status Responses

Displaying the Payment Status to User
Juspay communicates Order Status via three channels.

  1. Event Callback or Redirections: The user will be redirected to your App or Website after completion of payment as follows
    • Android/ iOS App: Juspay Android/ iOS SDK will automatically terminate the session after the user completes payment and provides a callback event with the payment status
    • Website: The user will be redirected to the Payment Redirect URL configured on Juspay Dashboard. Please configure a valid https url on the Juspay Dashboard > Settings > Payment Redirect URL to enable this flow
  2. Order Status API: Juspay provides a server-to-sever mechanism of verifying the Order Status. Please refer here for the Order Status API specifications
  3. Webhooks: After the completion of every payment/refund, Juspay will provide direct notification to your server regarding the event. These are called Webhooks. You must configure a valid HTTPS endpoint that is reachable from our servers to consume these notifications. Our servers will push data using HTTP POST calls to your endpoint. Please refer here for the Webhooks

Best Practices
We recommend that you follow the below steps for handling order status with you Juspay integration

  1. Step 1 - User redirected to your App / Website: After completion of a payment session the user will be automatically redirected to your app / website
  2. Step 2 - Display Order Confirmation Page: From your server, use the Juspay Order Status API to verify the status of payment. Please ensure that the order ID and amount transaction are verified. If the order has reached the terminal status, please display the order confirmation page to your customer
  3. Step 3 - Managing Webhooks: Asynchronously your server shall listen to the Webhooks events posted by Juspay Servers. Please refer here for Webhook specifications
  4. Step 4 - Handling Transaction Status scenarios: Handle the transaction status scenarios (received via Webhooks/ Order Status API) as recommended below
  5. #StatusIDDescription
    1CHARGED21Transaction is successful

    Display order confirmation page to the user and fulfill the order
    2AUTHENTICATION_FAILED26User did not complete authentication

    Display transaction failure status to the user along with the failure reason provided in the order status API response. Allow user to retry payment
    3AUTHORIZATION_FAILED27User completed authentication, but the bank refused the transaction.

    Display transaction failure status to the user along with the failure reason provided in the order status API response. Allow user to retry payment
    4AUTHORIZING28Transaction status is pending from the bank's end.

    This is a non-terminal transaction status. Implement business logic as per Step 5 (mentioned below)
    5PENDING_VBV23Authentication is in progress.

    This is a non-terminal transaction status. Implement business logic as per Step 5 (mentioned below)
    6STARTED20Transactions couldn’t be created against the order. Juspay system could not map this transaction to an applicable gateway.

    To be treated failed transaction attempts. Such scenarios are expected to happen when the payment gateway or priority logic is incorrectly configured on the Juspay system. Reach out to [email protected]
    7AUTO_REFUNDED36The transaction is automatically refunded to the user. Since the transaction status was a delayed success exceeding the order timeout configured on Juspay Dashboard.

    To be treated failed transaction attempts. The status shall be used to reconcile as automatically refunded to customer
    8NOT_FOUND40The transaction was not created on the Juspay server.

    To be treated as a User Dropout and hence a failed transaction attempt
    9JUSPAY_DECLINED22The input parameters are invalid.

    This scenario is an integration error. Reach out to [email protected] with order ID details for clarification

  6. Step 5 - Handling delayed status updates: Occasionally it may be possible that the payment status does not get updated immediately due to delays across payment processing systems (of Banks and Aggregators). In such cases, it is recommended to continuously use the Order Status API to poll and verify status.

    Your business policy might have a predefined order timeouts (a specified duration post which payments will not be accepted against the order). This may range from few minutes to a few days depending on the type of product/ service offered by your business

    • Step 5(a): Before declaring an order as timed-out, please use order status API to check the final status of the order. In case the order has reached terminal status, please fulfill the order
    • Step 5(b): In case the order status has not reached a terminal status, assure your customers that the “Order fulfillment has failed, and any amount deducted will be automatically refunded”

  7. Step 6 - Automatic refunds for delayed successful transactions: Juspay will automatically initiate the refunds with the respective payment processor. The refund will be processed as per the SLA of the payment processor which generally ranges between 1-7 days. You can enable auto refund from the Jupay Dashboard > Settings section

Frequently Asked Questions:

Why should I use the Order Status API?
As best practices, we recommend to use Order Status API for two reasons:

  • Reliability: While our webhooks are delivered instantly, it also depends on multiple other stakeholders in the payments ecosystem delivering Webhooks in a timely manner to Juspay Servers (Bank, Payment aggregators etc.). Hence, for business critical events such as communicating payment status to your customers, it is recommended to use the Order status API.
  • Fraud prevention: Under rare scenarios, it may be possible that fraudulent users try to tamper transaction processing by exploiting payment offers or tamper transaction amounts during various stages of a transaction. Such incidents could potentially lead to financial loss. Hence, the Order Status API is recommended as a secure channel to re-verify the Order ID and Actual Amount before fulfilling the product/service to your customers.

How does Auto Refund work?
It may be possible that transaction status doesn’t reach terminal status in real time. Some transactions may go into pending state and become successful at a later point of time and such transactions are called ‘conflicted transactions’.

Juspay will constantly check status with the payment service provider at regular intervals to fetch updated status. Any such updated status will be communicated with webhooks.

  • Auto Refund of Conflicted Transactions: If you wants to automatically refund the conflicted transaction enable this option (The default threshold is 10 minutes)
  • Auto Refund of Conflicted Transactions Threshold in Mins: Enter a threshold in minutes beyond which you would wish Juspay to automatically refund the transaction. The default threshold is 10 minutes
  • Auto Refunds in Multiple Charged Transactions: Enable the flag if Juspay should automatically refund the transaction(s) if there are multiple charged transactions against a single order