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?
Please connect with the onboarding and configuration team for webhook registration & event triggering.
How Webhook Responses are Used
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.
Webhook Events
| ID | Name |
|---|---|
| 1 | payment.pending |
| 2 | payment.failed |
| 3 | payment.refund.success |
| 4 | payment.captured |
| 5 | payment.completion |
JSON Webhook Response
Below is a sample JSON webhook response illustrating the data you might receive for a successful payment event:
Event Name: payment.captured
{"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 (Only in case of UPI)
{"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
{"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.pending
{"event_name":"payment.pending","merchant_response":{"merchant_id":"312827","payment_mode":"UPI","merchant_access_code":"07ccfc3c-a880-425a-b1f4-bf2511799224","unique_merchant_txn_id":"makeO-ord_yuiGhYrKodXbE9-1","pine_pg_txn_status":"1","txn_completion_date_time":"03/03/2024 12:41:03 PM","captured_amount_in_paisa":"0","refund_amount_in_paisa":"0","txn_response_code":"-966","amount_in_paisa":"9900","txn_response_msg":"Debit Failure","acquirer_name":"KOTAK_SETU","pine_pg_transaction_id":"294776679","rrn":"1709449852127361869","udf_field_2":"ICICI10","parent_txn_status":"","parent_txn_response_code":"","parent_txn_response_message":""}}
Event Name: payment.refund.success
{"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":""}}
Description
| 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 |