Outgoing webhook/callback

After the completion of every payment/refund call, Juspay will provide direct callback notification regarding an event to the URL in your server configured as a 'Webhook'. You must configure a valid HTTP endpoint that is reachable from our servers to consume these notifications. Our servers will push data using HTTP POST call to your endpoint.

A callback will be sent to your webhook URL for various events, such as: Payment Success/Failure, Refund Success/Failure, Order/Transaction Creation, and Refund Moved to Manual Review.

Webhooks will be triggered for the events listed here, depending on the
API version configured in the dashboard.       (click to view)
Note:
Webhook API version can be configured in the dashboard -> Settings -> Webhooks Tab -> Webhook API version
Event NameDescriptionWebhook API version
ORDER_SUCCEEDEDGenerated when payment is successful for an orderFor all the versions
ORDER_REFUNDEDGenerated when a refund is successfulFor all the versions
ORDER_FAILEDGenerated when an order payment failsFor all the versions >= "2016-07-19"
ORDER_REFUND_FAILEDGenerated when an order refund failsFor all the versions
TXN_CREATEDGenerated when payment is initiated for an orderFor all the versions >= "2016-10-27"
REFUND_MANUAL_REVIEW_NEEDEDGenerated 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
AUTO_REFUND_SUCCEEDEDGenerated when the transaction is auto refunded and refund is successFor all the versions >= "2019-11-11"
AUTO_REFUND_FAILEDGenerated when the transaction is auto refunded and refund is failureFor all the versions >= "2019-11-11"
MANDATE_CREATEDGenerated when the mandate is createdFor all the versions
MANDATE_ACTIVATEDGenerated when the mandate is successful registeredFor all the versions
MANDATE_FAILEDGenerated when the mandate registration failsFor all the versions
MANDATE_REVOKEDGenerated when the mandate is revoked by the merchantFor all the versions
MANDATE_PAUSEDGenerated when the mandate is paused by the customerFor all the versions
MANDATE_EXPIREDGenerated when the mandate expiresFor all the versions
Note:
Other possible events not shown in original documentation are indicated in red.

Webhooks are used for two basic reasons: First, it eliminates the need to send status request APIs in many cases, which can simplify your transaction flow. And secondly, there may be instances where customers' devices would be on low-quality connections, and thereby the final payment redirection using customers' browsers might not succeed. In such cases, a webhook call can help you complete the order for the customer.

Handling webhook failures and other webhook scenarios    (click to view)

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.

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.

Caveats:

Although our webhooks are reliable, it is always suggested that you use our Get Order Status 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 based on your business use case.

Callback Parameters for order/payment/refund events.       (click to view)
ParameterTypeDescription
idStringUnique ID of callback
i.e.   "evt_V2_bc933a28ee5948be9f2939caac09a"
date_createdStringCurrent date - i.e. "2020-07-24T10:42:25Z"
event_nameStringMust be one of the following:
ORDER_SUCCEEDED / ORDER_REFUNDED / ORDER_FAILED / ORDER_REFUND_FAILED / TXN_CREATED / REFUND_MANUAL_REVIEW_NEEDED / AUTO_REFUND_SUCCEEDED / AUTO_REFUND_FAILED / MANDATE_CREATED / MANDATE_ACTIVATED / MANDATE_FAILED / MANDATE_REVOKED / MANDATE_PAUSED / MANDATE_EXPIRED
content.order:wwwwwi
     {param1, param2....}
iObjecti
String
Content Order parameters
(Listed in table below - click to open)
  Callback Object: (content.order)    (click to open)
Note 1:
This object is basically the same as the Order Object, which is the response for the Get Order Status API . Objects contained in the Callback Object are listed on top:
Note 2:
Status Mapping - Transaction status codes and meaning (non-red codes are also used as valid status responses for the for the Order, Payments, and Mandates APIs).     (click to view)
Order StatusIDMeaning
CREATED1This order status code in used only for the Create Order API, and is returned when order is successfully created.
NEW10Newly created order.
PENDING_VBV23Authentication is in progress. The customer has to approve the mandate through the PSP App of their choice.
CHARGED21Successful transaction. The subscription cost of the period has been charged.
AUTHENTICATION_FAILED26User did not complete authentication.
AUTHORIZATION_FAILED27User completed authentication, but the bank refused the transaction.
JUSPAY_DECLINED22User input is not accepted by the underlying PG.
AUTHORIZING28Transaction status is pending from bank.
STARTED20Transaction is pending. Juspay system isn't able to find a gateway to process a transaction
AUTO_REFUNDED36Transaction is automatically refunded
CAPTURE_INITIATED33Capture pending for the pre-authorized transaction
CAPTURE_FAILED34Capture failed for the pre-authorized transaction
VOID_INITIATED32Void pending for the pre-authorized transaction
VOIDED31Void is successful for the pre-authorized transaction
VOID_FAILED35Void failed for the pre-authorized transaction

ParameterTypeDescription
payment_links:wwwwwwwwn
    {web, mobile, iframe}
Object
String
Contains 3 strings that link to a Desktop optimized, Mobile optimized as well as iFrame checkout screen for the given order
    Payment Links Object Parameters:
FieldTypeDescription
webStringLink to checkout page that is optimized for Desktop for the given order.
mobileStringLink to Mobile optimized checkout page for the given order.
iframeStringLink to iFrame checkout screen. This is typically embedded inside of your own page.

Payment Links
These links can directly be emailed or messaged to your customers. They will be redirected using a link to enter payment information. If you wish to use your own branding, then you can embed the iframe link into your page. Note that, these links are not valid perpetually. As soon as your order expires (this can be changed via our dashboard), the link will cease to work.



payment_gateway_response:
     {param1, param2, ....}
Object
String
Object containing payment gateway response details
    Payment Gateway Response Object Parameters:
FieldTypeDescriptionExample
txn_idStringTransaction ID"11327833"
rrnStringAuthorization Retrieval Reference Number"502913366745"
resp_messageStringResult of API action"Payment Successful"
resp_codeStringNumeric code of response message"0"
epg_txn_idStringElectronic Payment Gateway transaction ID"1532690566017"
createdStringDate time (ISO representation) when order was created"2020-04-28T06:31:37Z"
auth_id_codeStringAuthorization ID Code"475926"



txn_detail:wwwwwwwwwni
      {param1, param2, ....}
Object
String
Object containing transaction detailswwww
    Transaction Detail Object Parameters:
FieldTypeDescriptionExample
txn_uuidStringTransaction UUID (available in Order Status API response)"eulneT9JkaAPa1uv"
txn_idStringTransaction ID"11327833"
txn_amountStringAmount of transaction1
tax_amountStringAmount of tax appliednull
surcharge_amountStringExtra fee charged by merchant on paymentnull
statusStringStatus of the order (see Status Mapping table)"CHARGED"
redirectbooleanIf true, the user is redirected to the return_url configured for the order.false
order_idStringUnique Identifier for the order."145678234"
net_amountStringNet amount of order1
gateway_idStringUnique numeric identifier for your preferred gateway. (Refer to "Gateway Mapping" table.)19
gatewayStringName or your preferred gateway"PAYTM_V2"
express_checkoutbooleanTrue if using Express Checkoutfalse
error_messageStringBank error message""
error_codeStringNumeric code of bank error message""
currencyStringISO string of the currency. Use INR for Indian Rupee. Among other accepted values are EUR, USD, GBP."INR"
createdStringDate time (ISO representation) when order was created"2020-04-28T06:31:37Z"



card:wwwwwwwwwwwwnt
      {param1, param2, ....}
Object
String
Object containing credit/debit card details
    Card Object Parameters:
FieldTypeDescription
using_saved_cardbooleanTrue if using a saved card
saved_to_lockerbooleanTrue if card has been saved to locker
last_four_digitsStringLast four digits of card number
name_on_cardStringCard holder name. Should contain alphabetical characters only.
expiry_yearStringExpiry year of the card (Format: "yyyy")
expiry_monthStringExpiry month of the card (Format: "mm")
card_typeString"CREDIT" or "DEBIT"
card_issuerStringCode for bank that issued the card
(Example: "HDFC Bank")
card_isinStringInternational Securities Identification Number for card    (Example: "545721")
card_brandStringBrand of card ("MASTERCARD", "VISA", etc.)



Refunds: [{...},{...},..]
wwwwwwwwwwwwwwwwww
Array
wwwwt
An array of Refund Objects with details of each refund (returned only for the Refund Order and Get Order Status API).
    Refund Object Parameters:
FieldTypeDescription
idStringID generated for the refund
refStringReference number provided by the bank for the refund
amountDoubleAmount refunded (or to be refunded)
createdStringDate time (ISO representation) when refund was created
statusStringStatus of the refund. Can be one of PENDING, SUCCESS, FAILURE, MANUAL_REVIEW (see table below for meaning).

StatusMeaning
SUCCESSThis means that the refund has been successfully executed.
PENDINGThis would mean that the refund has been queued with JusPay or with the downstream system.
FAILUREWe were unable to process the refund successfully. You have to try again with new unique_request_id.
MANUAL_REVIEWThis would mean that the refund request was sent an ambigious response from the payment gateway and the merchant has to manually reconcile it with the payment gateway to get the proper response. Also, any refunds which are in pending for more than 10 days are set for manual review.



merchant_idStringUnique identifier for the merchant.
order_idStringUnique Identifier for the order. It is suggested to keep the order id length at a maximum of 21 characters irrespective of payment methods and gateways.
idStringUnique ID generated by Juspay for the given order.
customer_idStringString that uniquely identifies the customer. Generated by Juspay when you created customer object.
customer_emailStringEmail address of the customer. Must be present if backend gateway requires it.
customer_phoneStringMobile number or fixed line number of the customer. Must be present if backend gateway requires it.
product_idStringAn identifier for the product on the Lender side for which the payment is being done. This field is just echoed back in the response so that Lender can differentiate on their side. Fits well for impulse purchase usecases.
statusStringStatus of the order. If you receive “NEW”, then the order has been successfully created (see Status Mapping table above).
status_idIntegerStatus ID is a numeric id corresponding to the status value (see Status Mapping table above).
amountdoubleThis is the amount that a customer will be charged in this transaction. Will accept double values with up to two decimal places. For example, 100.15 is valid input but 100.1532 is not valid.
currencyStringISO string of the currency. Use INR for Indian Rupee. Among other accepted values are EUR, USD, GBP.
refundedBooleanTrue if the order has been completely refunded. Will be false for partial refunds or if the order doesn’t have any refunds.
amount_refundeddoubleAmount which has been refunded so far for this order.
date_createdStringDate-time of mandate or order creation
return_urlStringA fully qualified URL such as http://shop.merchant.com/ to which the customer will be redirected after payment completion. This URL shouldn’t contain any query parameters. This URL takes higher precedence over the common return URL configured in your account. settings.
udf1Stringudf1 to udf10 - User defined field which will be echoed back in the response from Juspay with a Max character limit of 255.
udf2String
udf3String
udf4String
udf5String
udf6String
udf7String
udf8String
udf9String
udf10String
txn_idStringTransaction ID
txn_uuidStringTransaction UUID
gateway_idIntegerUnique numeric identifier for your preferred gateway. (Refer to "Gateway Mapping" table.)
gateway_reference_idStringAlphabetic reference to the payment gateway used
bank_error_codeStringBank Error Code
bank_error_messageStringBank Error Message
payment_method_typeStringMust be either CARD, NB, WALLET, or UPI. Entered when creating the order or mandate
payment_methodStringEntered when creating the order or mandate. Found in the given tables for the corresponding API and transaction type.
payer_vpaStringPayer VPA used during setting up mandate
auth_typeStringType of authentication used


Payload:

 Payload : {
  "id": "evt_hk0a9ccu6qwkcryg",
  "date_created": "2018-12-05T13:53:24Z",
  "event_name": "ORDER_SUCCEEDED",
  "content": {
    "order": {
      "gateway_id": 18,
      "product_id": "",
      "auth_type": "THREE_DS",
      "customer_phone": "7598504535",
      "bank_error_message": "",
      "date_created": "2018-12-05T13:48:48Z",
      "order_id": "3e0411f7-a4b1-466b-85b2-ea55d1ba6496",
      "currency": "INR",
      "amount": 600,
      "id": "ord_c4345ba45dd3457c85fe8299f5321f53",
      "udf2": "",
      "udf1": "",
      "refunded": false,
      "udf6": "",
      "udf5": "",
      "amount_refunded": 0,
      "udf4": "",
      "txn_id": "-3e0411f7-a4b1-466b-85b2-ea55d1ba6496-1",
      "udf3": "",
      "card": {
        "saved_to_locker": false,
         "card_issuer": "",
         "card_brand": "MASTERCARD",
         "card_reference": "008485a49f2edfb9e62cefaa0cb95b13",
         "card_type": "CREDIT",
         "card_fingerprint": "1gkmbuaauq6ts9hv6v2oos4qgc",
         "expiry_year": "2023",
         "using_saved_card": true,
         "card_isin": "553227",
         "name_on_card": "",
         "last_four_digits": "",
         "expiry_month": "04"
       },
       "merchant_id": "MID",
       "payment_method_type": "CARD",
       "payment_links": {
         "iframe": "https://sandbox.juspay.in/merchant/ipay/ord_c4345ba45dd3457c85fe8299f5321f53",
         "web": "https://sandbox.juspay.in/merchant/pay/ord_c4345ba45dd3457c85fe8299f5321f53",
         "mobile": "https://sandbox.juspay.in/merchant/pay/ord_c4345ba45dd3457c85fe8299f5321f53?mobile=true"
       },
       "status": "CHARGED",
       "txn_uuid": "rkuk1mu7y77ltiam",
       "status_id": 21,
       "customer_email": "",
       "udf7": "",
       "udf8": "",
       "udf9": "",
       "bank_error_code": "",
       "return_url": "http://88.99.31.206:8222/transactions/online_payment_status",
       "payment_gateway_response": {
         "rrn": "201812<HIDDEN>0010016862<HIDDEN>6345",
         "created": "2018-12-05T13:53:24Z",
         "resp_code": "01",
         "txn_id": "MID-3e0411f7-a4b1-466b-85b2-ea55d1ba6496-1",
         "epg_txn_id": "201812<HIDDEN>0010016862<HIDDEN>6345",
         "resp_message": "Txn Success",
         "auth_id_code": ""
       },
       "payment_method": "MASTERCARD",
       "customer_id": "6989",
       "udf10": ""
    }
  }
 }