Webhooks
After the completion of every payment/refund call, 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 HTTPS POST call to your endpoint.
Based on the API version configured in the dashboard, webhooks will be triggered for the events below.
Payment Success
Payment Failure
Refund Success
Refund failure
Order Creation
Transaction Creation
Refund Moved to Manual Review.
Why webhooks?
Payment redirection using customers' browsers are not reliable all the time. There would be instances where customers' devices would be on low-quality connections and thereby the final redirection might not succeed. In such cases, a webhook call can help you complete the order for the customer.
But care must be taken while consuming the webhook data. Since you might receive both webhook and customer redirection around the same time, you should not process the order twice. This is true for most cases.
In very rare scenarios, our webhook call pertaining to order might hit your server more than once. This can happen due to network fluctuations. So, care must be taken to ensure that such scenarios are handled too.
Events
|
Event Name
|
Description
|
Webhook API version
|
|---|---|---|
ORDER_SUCCEEDED
| Generated when payment is successful for an order
| For all the versions
|
ORDER_REFUNDED
| Generated when a refund is successful
| For all the versions
|
ORDER_FAILED
| Generated when an order payment fails
| For all the versions >= "2016-07-19"
|
ORDER_REFUND_FAILED
| Generated when an order refund fails
| For all the versions
|
TXN_CREATED
| Generated when payment is initiated for an order
| For all the versions >= "2016-10-27"
|
REFUND_MANUAL_REVIEW_NEEDED
| Generated when the refund status is ambiguous and the refund has to be manually reconciled by the merchant with the payment processor.
| For all the versions
|
REFUND_INITIATED
| Generated when refund is initiated for an order
| For all the versions
|
AUTO_REFUND_SUCCEEDED
| Generated when the transaction is auto refunded and refund is success
| For all the versions >= "2019-11-11"
|
AUTO_REFUND_FAILED
| Generated when the transaction is auto refunded and refund is failure
| For all the versions >= "2019-11-11"
|
MANDATE_CREATED
| Generated when the mandate is created
| For all the versions
|
MANDATE_ACTIVATED
| Generated when the mandate is successful registered
| For all the versions
|
MANDATE_FAILED
| Generated when the mandate registration fails
| For all the versions
|
MANDATE_REVOKED
| Generated when the mandate is revoked by the merchant
| For all the versions
|
NOTIFICATION_FAILED
| Generated when the mandate notification is failed
| For all the versions
|
NOTIFICATION_SUCCEEDED
| Generated when the mandate notification is success
| For all the versions
|
ORDER_AUTHORIZED
| Generated for pre-auth enabled transactions when the payment is AUTHORIZED
| For all the versions
|
TXN_CHARGED
| Transaction level webhook, generated when a transaction become successful
| For all the versions >="2020-10-31"
|
TXN_FAILED
| Transaction level webhook, generated when a transaction fails
| For all the versions >="2020-10-31"
|
Webhook API version can be configured in the dashboard > Settings > Webhooks Tab > Webhook API version
Response structure for Webhook
Webhook Authentication
We support Basic HTTP Authentication for your Webhook URL. Using Username and password fields to authenticate the webhook call is mandatory. Please ensure that special characters like @ are not used in username.
Handling Failures
If your server is not reachable and we receive a non-200 response when we are attempting webhook notification, we would mark the webhook notified section in our dashboard as False. Hence, consume webhooks on with 200 response code.
You would receive webhook events from the following IPs
Production:
13.126.232.13
35.154.93.248
65.2.117.44
3.110.250.172
Sandbox:
52.221.151.249
13.228.4.195
13.234.141.165
3.111.27.22
3.109.41.51
Caveats:
Although our webhooks are reliable, it is always suggested that you use our GetOrderStatus API to poll our systems, in case you do not receive the webhooks in time.
This will handle the cases where the webhooks could not be notified to your system. The threshold beyond which you start polling our system can be decided basis your business use case.