Outgoing webhook/callback

Note:

Webhook API version can be configured in the dashboard -> Settings -> Webhooks Tab -> Webhook API version

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
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
MANDATE_PAUSED	Generated when the mandate is paused by the customer	For all the versions
MANDATE_EXPIRED	Generated when the mandate expires	For all the versions

Note:

Other possible events not shown in original documentation are indicated in red.

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.

Parameter	Type	Description
id	String	Unique ID of callback i.e.   "evt_V2_bc933a28ee5948be9f2939caac09a"
date_created	String	Current date - i.e. "2020-07-24T10:42:25Z"
event_name	String	Must 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 Status	ID	Meaning
CREATED	1	This order status code in used only for the Create Order API, and is returned when order is successfully created.
NEW	10	Newly created order.
PENDING_VBV	23	Authentication is in progress. The customer has to approve the mandate through the PSP App of their choice.
CHARGED	21	Successful transaction. The subscription cost of the period has been charged.
AUTHENTICATION_FAILED	26	User did not complete authentication.
AUTHORIZATION_FAILED	27	User completed authentication, but the bank refused the transaction.
JUSPAY_DECLINED	22	User input is not accepted by the underlying PG.
AUTHORIZING	28	Transaction status is pending from bank.
STARTED	20	Transaction is pending. Juspay system isn't able to find a gateway to process a transaction
AUTO_REFUNDED	36	Transaction is automatically refunded
CAPTURE_INITIATED	33	Capture pending for the pre-authorized transaction
CAPTURE_FAILED	34	Capture failed for the pre-authorized transaction
VOID_INITIATED	32	Void pending for the pre-authorized transaction
VOIDED	31	Void is successful for the pre-authorized transaction
VOID_FAILED	35	Void failed for the pre-authorized transaction

Parameter	Type	Description
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:

Field	Type	Description
web	String	Link to checkout page that is optimized for Desktop for the given order.
mobile	String	Link to Mobile optimized checkout page for the given order.
iframe	String	Link 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:

Field	Type	Description	Example
txn_id	String	Transaction ID	"11327833"
rrn	String	Authorization Retrieval Reference Number	"502913366745"
resp_message	String	Result of API action	"Payment Successful"
resp_code	String	Numeric code of response message	"0"
epg_txn_id	String	Electronic Payment Gateway transaction ID	"1532690566017"
created	String	Date time (ISO representation) when order was created	"2020-04-28T06:31:37Z"
auth_id_code	String	Authorization ID Code	"475926"

txn_detail:wwwwwwwwwni       {param1, param2, ....}	Object String	Object containing transaction detailswwww

    Transaction Detail Object Parameters:

Field	Type	Description	Example
txn_uuid	String	Transaction UUID (available in Order Status API response)	"eulneT9JkaAPa1uv"
txn_id	String	Transaction ID	"11327833"
txn_amount	String	Amount of transaction	1
tax_amount	String	Amount of tax applied	null
surcharge_amount	String	Extra fee charged by merchant on payment	null
status	String	Status of the order (see Status Mapping table)	"CHARGED"
redirect	boolean	If true, the user is redirected to the return_url configured for the order.	false
order_id	String	Unique Identifier for the order.	"145678234"
net_amount	String	Net amount of order	1
gateway_id	String	Unique numeric identifier for your preferred gateway. (Refer to "Gateway Mapping" table.)	19
gateway	String	Name or your preferred gateway	"PAYTM_V2"
express_checkout	boolean	True if using Express Checkout	false
error_message	String	Bank error message	""
error_code	String	Numeric code of bank error message	""
currency	String	ISO string of the currency. Use INR for Indian Rupee. Among other accepted values are EUR, USD, GBP.	"INR"
created	String	Date 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:

Field	Type	Description
using_saved_card	boolean	True if using a saved card
saved_to_locker	boolean	True if card has been saved to locker
last_four_digits	String	Last four digits of card number
name_on_card	String	Card holder name. Should contain alphabetical characters only.
expiry_year	String	Expiry year of the card (Format: "yyyy")
expiry_month	String	Expiry month of the card (Format: "mm")
card_type	String	"CREDIT" or "DEBIT"
card_issuer	String	Code for bank that issued the card (Example: "HDFC Bank")
card_isin	String	International Securities Identification Number for card    (Example: "545721")
card_brand	String	Brand 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:

Field	Type	Description
id	String	ID generated for the refund
ref	String	Reference number provided by the bank for the refund
amount	Double	Amount refunded (or to be refunded)
created	String	Date time (ISO representation) when refund was created
status	String	Status of the refund. Can be one of PENDING, SUCCESS, FAILURE, MANUAL_REVIEW (see table below for meaning).

Status	Meaning
SUCCESS	This means that the refund has been successfully executed.
PENDING	This would mean that the refund has been queued with JusPay or with the downstream system.
FAILURE	We were unable to process the refund successfully. You have to try again with new unique_request_id.
MANUAL_REVIEW	This 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_id	String	Unique identifier for the merchant.
order_id	String	Unique 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.
id	String	Unique ID generated by Juspay for the given order.
customer_id	String	String that uniquely identifies the customer. Generated by Juspay when you created customer object.
customer_email	String	Email address of the customer. Must be present if backend gateway requires it.
customer_phone	String	Mobile number or fixed line number of the customer. Must be present if backend gateway requires it.
product_id	String	An 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.
status	String	Status of the order. If you receive “NEW”, then the order has been successfully created (see Status Mapping table above).
status_id	Integer	Status ID is a numeric id corresponding to the status value (see Status Mapping table above).
amount	double	This 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.
currency	String	ISO string of the currency. Use INR for Indian Rupee. Among other accepted values are EUR, USD, GBP.
refunded	Boolean	True if the order has been completely refunded. Will be false for partial refunds or if the order doesn’t have any refunds.
amount_refunded	double	Amount which has been refunded so far for this order.
date_created	String	Date-time of mandate or order creation
return_url	String	A 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.
udf1	String	udf1 to udf10 - User defined field which will be echoed back in the response from Juspay with a Max character limit of 255.
udf2	String
udf3	String
udf4	String
udf5	String
udf6	String
udf7	String
udf8	String
udf9	String
udf10	String
txn_id	String	Transaction ID
txn_uuid	String	Transaction UUID
gateway_id	Integer	Unique numeric identifier for your preferred gateway. (Refer to "Gateway Mapping" table.)

gateway_reference_id	String	Alphabetic reference to the payment gateway used
bank_error_code	String	Bank Error Code
bank_error_message	String	Bank Error Message
payment_method_type	String	Must be either CARD, NB, WALLET, or UPI. Entered when creating the order or mandate
payment_method	String	Entered when creating the order or mandate. Found in the given tables for the corresponding API and transaction type.
payer_vpa	String	Payer VPA used during setting up mandate
auth_type	String	Type of authentication used