Transaction Status
There are 2 ways to fetch payment status: -
1. Order Status API: Juspay provides a server-to-server mechanism of verifying the Order Status. Click for Detailed API for order status
2. 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. Click for Detailed Webhook Specifications
Q: 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.
Payment Response
Once the payment is complete the user is redirected to the return_url configured by you. Following is the typical destination where the user is taken to:
HTTP GET https://merchant.shop.com/paymentresponse/handler?order_id=order_id_007&status=CHARGED&status_id=21&signature=euKzwwiUztPPg3MCEYpgKZfcyTr1uQq1hzKkhP8G1vQ%253D&signature_algorithm=HMAC-SHA256'
Please note that the parameters are sent using HTTP GET by default. To enable HTTP POST for your MID, please enable the flag ‘Enable POST method support for return URL’ in Settings.
Best Practices
The following figure is a workflow of how you can handle the order status:
.png)
Step 1 - User redirected to your App / Website: After completion of a payment session the user will be automatically redirected to your app / website
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
Step 3 - Managing Webhooks: Asynchronously your server shall listen to the Webhooks events posted by Juspay Servers. Please refer here for Webhook specifications
Step 4 - Handling Transaction Status scenarios: Handle the transaction status scenarios (received via Webhooks/ Order Status API) as recommended below
|
Status ID
|
Status
|
Description
|
Actionables
|
|---|---|---|---|
10
| NEW
| Newly created order. This is the status if transaction is not triggered for an order
| N/A
|
23
| PENDING_VBV
| Authentication is in progress
| This is a non-terminal transaction status. Show pending screen to your customers and in background keep polling order-status API till you get Charged or Failed; or till the time your order fulfilment window (a specified duration post which payments will not be accepted against the order) is active.
|
21
| CHARGED
| Successful transaction
| Display order confirmation page to the user and fulfill the order.
|
26
| AUTHENTICATION_FAILED
| User 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.
|
27
| AUTHORIZATION_FAILED
| User 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.
|
22
| JUSPAY_DECLINED
| User input is not accepted by the underlying PG
| This scenario is an integration error. Reach out to us with order ID details for clarification.
|
28
| AUTHORIZING
| Transaction status is pending from bank
| This is a non-terminal transaction status. Show pending screen to your customers and in background keep polling order-status API till you get Charged or Failed; or till the time your order fulfilment window (a specified duration post which payments will not be accepted against the order) is active.
|
29
| COD_INITIATED
| COD Initiated Successfully
| Display order confirmation page to the user and fulfill the order.
|
20
| STARTED
| Transaction is pending. Juspay system isn't able to find a gateway to process a transaction
| This scenario is an integration error. Reach out to us with order ID details for clarification.
|
36
| AUTO_REFUNDED
| Transaction is automatically refunded
| Display the refund status to the user and in background keep polling order-status API till you get Success or Failure.
|
37
| PARTIAL_CHARGED
| This status occurs when the final charged or debited amount is less than the effective order amount. It typically happens in scenarios involving either the use of products like a merchant's in-house wallet, where users can claim a certain balance from the Merchant's wallet, or in Auth and Capture flow where the total amount captured in the end is lower than the effective order amount
| Display order confirmation page to the user and fulfill the order.
|
25
| AUTHORIZED
| Pre-authorized transaction
| |
33
| CAPTURE_INITIATED
| Capture pending for the pre-authorized transaction
| |
34
| CAPTURE_FAILED
| Capture failed for the pre-authorized transaction
| |
31
| VOIDED
| Void is successful for the pre-authorized transaction
| |
32
| VOID_INITIATED
| Void pending for the pre-authorized transaction
| |
35
| VOID_FAILED
| Void failed for the pre-authorized transaction
| |
40
| NOT_FOUND
| Provided order id is not created at Juspay
|
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
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
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”
In case you want to process refund for delayed success orders, you can either do a Manual Refund or Auto-Refund. Refer here for more details
Q: Is there a recommended order status polling logic?
In order to optimise the number of order status API calls, post payment completion you should call the API at below time intervals upto your order fulfilment window (a specified duration post which payments will not be accepted against the order). Polling should be stopped once terminal status is received for the order
This is only a recommended logic and can be customised as per your business use case
|
Time post payment redirection
|
Polling Logic
|
|---|---|
t=0 to t=90 secs
| Poll every 15 seconds
|
t>90 secs and t<=2 minutes
| Poll at 2nd Minute
|
t>2 minutes and t<=5 minutes
| Poll at 5th Minute
|
t>5 minutes and t<=10 minutes
| Poll at 10th Minute
|
t>10 minutes and t<=20 minutes
| Poll at 20th Minute
|
t>20 minutes and t<=1 hour
| Poll at 1 hour
|
t>1 hours and t<=24 hours
| Poll at 2nd hour, 6th hour, 12th hour and 24th hours
|