Webhooks

What are Webhooks?

Webhooks are a method of communication between two applications in real-time. They enable merchants to receive notifications or trigger actions automatically when certain events occur in the payment system.

Why Webhooks?

Real-time Updates: Webhooks provide merchants with instant notifications about important events, such as successful payments, refunds, or chargebacks, allowing them to respond promptly.
Automated Processes: By integrating with webhooks, merchants can automate various tasks, such as updating order statuses, sending confirmation emails, or updating inventory levels, without manual intervention.
Enhanced User Experience: With webhooks, merchants can provide a seamless and efficient checkout experience for customers by triggering actions instantly, ensuring timely communication and order processing.

How do Webhooks Work?

When you integrate webhooks into your system, you'll receive HTTP POST requests containing JSON data whenever specific events occur in the payment system. These requests, known as webhook responses, provide real-time notifications about important events such as successful payments and refunds. Please connect with the onboarding and configuration team for webhook registration & event triggering.

Webhook Events

ID	Name
1	payment.captured
2	payment.completion
3	payment.failed
4	payment.refund.success

Sample Webhook Response

payment.captured
payment.completion
payment.failed
payment.refund.success

{
    "event_name": "payment.captured",
    "merchant_response": {
        "merchant_id": "29792",
        "payment_mode": "EMI",
        "merchant_access_code": "d860a376-2182-4448-9d87-2b2c752b8991",
        "unique_merchant_txn_id": "c-947711168513-03070150-1",
        "pine_pg_txn_status": "4",
        "txn_completion_date_time": "03/03/2024 12:33:02 PM",
        "product_code": "273865",
        "captured_amount_in_paisa": "13559000",
        "refund_amount_in_paisa": "0",
        "txn_response_code": "1",
        "amount_in_paisa": "14059000",
        "txn_response_msg": "SUCCESS",
        "acquirer_name": "HDFC_FSS_IN_HOUSE",
        "pine_pg_transaction_id": "294774500",
        "rrn": "406358019945",
        "auth_code": "055712",
        "masked_card_number": "************2562",
        "card_holder_name": "name",
        "mobile_no": "9810505359",
        "salted_card_hash": "651BB095DE12C950EF09401518017A06C5DC1A1FE5D0E7782A373F7CFB5482A3",
        "udf_field_1": "110014C25 1st FloorJangpura extension jangpura new delhiDELHIDELHI",
        "udf_field_2": "492001Hudco Regional Office 1B Surya ApartmentsKatora Talab Civil Lines RaipurRAIPURCHHATTISGARH",
        "udf_field_3": "273865",
        "udf_field_4": "01eae2ec05761000bbea86e16dcb4b79CROMA41646",
        "emi_tenure_month": "1",
        "emi_interest_rate_percent": "0.00",
        "emi_principal_amount_in_paisa": "13559000",
        "emi_amount_payable_each_month_in_paisa": "0",
        "is_brand_emi_txn": "1",
        "emi_cashback_type": "0",
        "parent_txn_status": "",
        "parent_txn_response_code": "",
        "parent_txn_response_message": "",
        "issuer_name": "HDFC",
        "product_category": "MacBook Air",
        "manufacturer": "Apple Macbook",
        "product_discount": "500000"
    }
}

{
    "event_name": "payment.completion",
    "merchant_response": {
        "merchant_id": "324915",
        "payment_mode": "UPI",
        "merchant_access_code": "a46ee454-20c9-4dd8-8c4e-1773bc631c4c",
        "unique_merchant_txn_id": "6363240303123137",
        "pine_pg_txn_status": "4",
        "txn_completion_date_time": "03/03/2024 12:32:22 PM",
        "captured_amount_in_paisa": "208450",
        "refund_amount_in_paisa": "0",
        "txn_response_code": "1",
        "amount_in_paisa": "208450",
        "txn_response_msg": "SUCCESS",
        "acquirer_name": "UPI_HDFC",
        "pine_pg_transaction_id": "294774320",
        "rrn": "406348028427",
        "auth_code": "NA",
        "parent_txn_status": "",
        "parent_txn_response_code": "",
        "parent_txn_response_message": ""
    }
}

{
    "event_name": "payment.failed",
    "merchant_response": {
        "merchant_id": "321999",
        "payment_mode": "CREDIT_DEBIT_CARD",
        "merchant_access_code": "0164c5ab-bdec-4072-ba65-2705a7d167e2",
        "unique_merchant_txn_id": "op-202403030706319383572-1",
        "pine_pg_txn_status": "-7",
        "txn_completion_date_time": "03/03/2024 12:37:25 PM",
        "captured_amount_in_paisa": "0",
        "refund_amount_in_paisa": "0",
        "txn_response_code": "-1",
        "amount_in_paisa": "2699900",
        "txn_response_msg": "FAILURE",
        "acquirer_name": "HDFC_FSS_IN_HOUSE",
        "pine_pg_transaction_id": "294775759",
        "rrn": "406379027843",
        "masked_card_number": "************7523",
        "card_holder_name": "name",
        "mobile_no": "9597874830",
        "salted_card_hash": "1C857604514EC029415325BE2DB5B0AC6627CF6AC9EA429FF005F68A1B99E1FE",
        "udf_field_1": "M112403036446004968",
        "parent_txn_status": "",
        "parent_txn_response_code": "",
        "parent_txn_response_message": ""
    }
}

{
    "event_name": "payment.refund.success",
    "merchant_response": {
        "merchant_id": "325742",
        "payment_mode": "UPI",
        "merchant_access_code": "fb5d3fe0-340f-49bd-bd28-7026646744b0",
        "unique_merchant_txn_id": "325742_0103202412284150866_325742_0103202417002419855",
        "pine_pg_txn_status": "6",
        "txn_completion_date_time": "02/03/2024 09:36:25 AM",
        "captured_amount_in_paisa": "0",
        "refund_amount_in_paisa": "730000",
        "txn_response_code": "1",
        "amount_in_paisa": "730000",
        "txn_response_msg": "SUCCESS",
        "acquirer_name": "KOTAK_SETU",
        "pine_pg_transaction_id": "294176488",
        "rrn": "1706959061633674606",
        "parent_txn_status": "",
        "parent_txn_response_code": "",
        "parent_txn_response_message": ""
    }
}

Response Parameters

Description of Response Parameters

Parameter Name	Type	Description
merchant_id	Integer	In response, you can see the merchant ID which you have sent as one of the parameters in Pine Labs payment gateway API request parameters.
merchant_access_code	String	In response, you can find the merchant access code which you have sent as one of the parameters.
pine_pg_txn_status	Integer	Transaction status.
txn_completion_date_time	DateTime	The date-time of the transaction completion at Pine Labs payment gateway server.
amount_in_paisa	Long	It is the amount for which payment transaction is being done.
txn_response_code	Integer	Represent the response of the API request and response code is returned based on the transaction result.
txn_response_msg	String	Transaction response message.
acquirer_name	String	Acquirer Bank.
pine_pg_transaction_id	Long	Unique transaction id generated by Pine Labs.
payment_mode	Integer	Payment mode chosen at landing page.
is_bank_emi_txn	Bool	Flag to indicate Bank EMI transaction.
is_brand_emi_txn	Bool	Flag to indicate Brand EMI transaction.
emi_tenure_month	Integer	Tenure month of EMI transaction.
emi_principal_amount_in_paisa	Long	Principal EMI amount in Paise.
emi_amount_payable_each_month_in_paisa	Long	Monthly Installment.
emi_interest_rate_percent	Integer	Interest rate charged by bank multiplied by 10000.
emi_cashback_type	Integer	Its value will be 0, 1,2 and 3. 0- Standard EMI, 1- Pre cash back, 2- Post cash back, 3- Instant Cashback
emi_total_discount_cashback_amount_in_paisa	Long	Total discount or cashback amount applicable in EMI transaction in paise.
emi_total_discount_cashback_percent	Integer	Total discount or cashback percent applicable in EMI transaction multiplied by 10000.
emi_merchant_discount_cashabck_perecent	Integer	Merchant discount or cashback percent applicable in EMI transaction multiplied by 10000.
emi_merchant_discount_cashback_fixed_amount_in_paisa	Long	Merchant fixed discount or cashback amount applicable in EMI transaction in paise.
emi_issuer_discount_cashabck_perecent	Integer	Issuer discount or cashback percent applicable in EMI transaction multiplied by 10000.
emi_issuer_discount_cashback_fixed_amount_in_paisa	Long	Issuer fixed discount or cashback amount applicable in EMI transaction in paise.
emi_additional_cashback	String	Additional Cashback in case of EMI Transaction
txn_additional_info	String	Base64 encoded string
merchant_return_url	String	Merchant return URL
emi_processing_fee	Long	Processing fee amount in paise.
manufacturer	String	Manufacturer name in case of brand emi transaction
product_category	String	Product category in case of brand emi transaction
product_description	String	Product description in case of brand emi transaction
product_discount	Long	Product discount in case of brand emi transaction. It is the flat discount given on product
captured_amount_in_paisa	Long	Captured amount for a transaction
refund_amount_in_paisa	Long	Refund amount for a transasction
parent_txn_status	Integer	Parent txn status
parent_txn_response_code	Integer	Parent txn response code
parent_txn_response_message	String	Parent txn response message
issuer_name	String	Issuing bank name
udf_field_1	String	Udf field1 which comes in payment initiation request
udf_field_2	String	Udf field2 which comes in payment initiation request
udf_field_3	String	Udf field3 which comes in payment initiation request
udf_field_4	String	Udf field4 which comes in payment initiation request
card_holder_name	String	Card holder name in case of card transaction
salted_card_hash	String	Salted card hash in case of card transaction
masked_card_number	String	Masked Card number in case of card transaction
auth_code	String	Auth code received from acquirer in authorization response
rrn	String	RRN number received from acquirer in authorization response
Acquirer_Response_Code	String	Acquirer response code received from acquirer in authorization response
Acquirer_Response_Message	String	Acquirer response message received from acquirer in authorization response
is_surcharge_txn	Integer	1 value will be come if transaction is convenience fee else 0
convenience_fees_in_paise	Long	Total convenience fees applied on transaction
convenience_gst_in_paise	Long	Total convenience fees GST applied on transaction
convenience_additional_charges_in_paise	Long	Total convenience fees additional fees applied on transaction
auth_id	String	Auth ID received in authorization response

Signature Verification

This is a mandatory step to confirm the authenticity of the details returned to you on the return URL for successful payments. Refer to the steps below to ensure that the data is authentic and not tampered with.

To find the signature refer to the header X-verify in the response parameters.

x - verify{{ FF0014009BE78864DA6880349F1F2D273DE6920B4480B65C3EF8D20A76990409}}

Sample Response

{ 
    "event_name": "payment.captured", 
    "merchant_response": { 
        "merchant_id": "113484", 
        "merchant_access_code": "7f532770-f8a7-46f8-a463-182727a29350", 
        "unique_merchant_txn_id": "104943038807791693", 
        "pine_pg_txn_status": "4", 
        "txn_completion_date_time": "29/11/2023 12:18:49 PM", 
        "amount_in_paisa": "20000", 
        "txn_response_code": "1", 
        "txn_response_msg": "SUCCESS", 
        "acquirer_name": "HDFC", 
        "pine_pg_transaction_id": "7831007", 
        "captured_amount_in_paisa": "20188", 
        "refund_amount_in_paisa": "0", 
        "payment_mode": "CREDIT_DEBIT_CARD", 
        "parent_txn_status": "", 
        "parent_txn_response_code": "", 
        "parent_txn_response_message": "", 
        "masked_card_number": "************1112", 
        "card_holder_name": "mojiz", 
        "salted_card_hash": "B6B6A7CE1E6E2AA0DD7C028385446A3BBADCEE026A283859C69F5D2B8CC645AD", 
        "rrn": "425847096720", 
        "auth_code": "999999" 
    } 
}   

Step 1: Convert the response into CSV without spaces:

{"event_name":"payment.captured","merchant_response":{"merchant_id":"113484","merchant_access_code":"7f532770-f8a7-
46f8-a463-
182727a29350","unique_merchant_txn_id":"104943038807791693","pine_pg_txn_status":"4","txn_completion_date_time":"29/
11/2023 12:18:49 
PM","amount_in_paisa":"20000","txn_response_code":"1","txn_response_msg":"SUCCESS","acquirer_name":"HDFC","pine_pg_tr ansaction_id":"7831007","captured_amount_in_paisa":"20188","refund_amount_in_paisa":"0","payment_mode":"CREDIT_DEBIT _CARD","parent_txn_status":"","parent_txn_response_code":"","parent_txn_response_message":"","masked_card_number":"**
**********1112","card_holder_name":"mojiz","salted_card_hash":"B6B6A7CE1E6E2AA0DD7C028385446A3BBADCEE026A28385
9C69F5D2B8CC645AD","rrn":"425847096720","auth_code":"999999"}} 

Step 2: Convert the payload into base64 format:

eyJldmVudF9uYW1lIjoicGF5bWVudC5jYXB0dXJlZCIsIm1lcmNoYW50X3Jlc3BvbnNlIjp7Im1lcmNoYW50X2lkIjoiMTEzNDg0IiwibWVyY 2hhbnRfYWNjZXNzX2NvZGUiOiI3ZjUzMjc3MC1mOGE3LTQ2ZjgtYTQ2My0xODI3MjdhMjkzNTAiLCJ1bmlxdWVfbWVyY2hhbnRfdHhu
X2lkIjoiMTA0OTQzMDM4ODA3NzkxNjkzIiwicGluZV9wZ190eG5fc3RhdHVzIjoiNCIsInR4bl9jb21wbGV0aW9uX2RhdGVfdGltZSI6IjI5Lz
ExLzIwMjMgMTI6MTg6NDkgUE0iLCJhbW91bnRfaW5fcGFpc2EiOiIyMDAwMCIsInR4bl9yZXNwb25zZV9jb2RlIjoiMSIsInR4bl9yZXNwb 25zZV9tc2ciOiJTVUNDRVNTIiwiYWNxdWlyZXJfbmFtZSI6IkhERkMiLCJwaW5lX3BnX3RyYW5zYWN0aW9uX2lkIjoiNzgzMTAwNyIsImN hcHR1cmVkX2Ftb3VudF9pbl9wYWlzYSI6IjIwMTg4IiwicmVmdW5kX2Ftb3VudF9pbl9wYWlzYSI6IjAiLCJwYXltZW50X21vZGUiOiJDUkV ESVRfREVCSVRfQ0FSRCIsInBhcmVudF90eG5fc3RhdHVzIjoiIiwicGFyZW50X3R4bl9yZXNwb25zZV9jb2RlIjoiIiwicGFyZW50X3R4bl9yZX Nwb25zZV9tZXNzYWdlIjoiIiwibWFza2VkX2NhcmRfbnVtYmVyIjoiKioqKioqKioqKioqMTExMiIsImNhcmRfaG9sZGVyX25hbWUiOiJtb2 ppeiIsInNhbHRlZF9jYXJkX2hhc2giOiJCNkI2QTdDRTFFNkUyQUEwREQ3QzAyODM4NTQ0NkEzQkJBRENFRTAyNkEyODM4NTlDNjlGN UQyQjhDQzY0NUFEIiwicnJuIjoiNDI1ODQ3MDk2NzIwIiwiYXV0aF9jb2RlIjoiOTk5OTk5In19 

Step 3: Hashing the payload Pass the base64 payload through SHA256 algorithm along with the MID secret to generate the signature.

FF0014009BE78864DA6880349F1F2D273DE6920B4480B65C3EF8D20A76990409

Step 4: Match the generated signature with the received signature in the x-verify header

What are Webhooks?​

Why Webhooks?​

How do Webhooks Work?​

Webhook Events​

Sample Webhook Response​

Response Parameters​

Signature Verification​