--- title: Webhook Integration Guide slug: webhook-integration-guide icon: {"faIcon":"fa-solid fa-circle-nodes"} docTags: createdAt: 2023-09-28T08:42:51.990Z --- ## Overview This documentation provides instructions for integrating LatitudePay's webhook functionality into the caller(your) system. LatitudePay allows caller to receive real-time events and updates related to successful orders, cancellations, partial refunds, and order timeouts. Follow the steps outlined below to integrate the webhooks. We recommend to whitelist LatitudePay NAT ip on your cloud for webhooks, so that only LatitudePay system is able to send the webhooks successfully. As of now, there is no provision to support APIs which requires authentication, if you have any specific requirements on this, we request you to kindly get in touch with us. ### Prerequisites Before proceeding with the integration, make sure the following prerequisites are met: - *You* should have an activated LatitudePay Merchant Account. - Configure your webhook URL with latitudePay :::BlockQuote Follow this link for details: [Prerequisites](https://docs.sg.latitudepay.com/integration-prerequisite) ::: ## Integration Steps Follow these steps to integrate LatitudePay's webhook functionality into your system: ## Step 1: Configure the webhook To get started, you should have built a POST API endpoint to receive order updates. We strongly recommend exposing HTTPS endpoint. The specifications of payloads that will be posted to this API are given below. Once the endpoint is ready to receive webhook updates, you need to provide the webhook URL to our technical team, and we will get the webhook registered and enabled for you. :::hint{type="warning"} LatitudePay is offering webhook integration for Online and Offline orders. During the configuration please make sure to inform the team about the type of order you would like to receive the webhook event for. ::: ## Step 2: Receive Webhook Events Specifications of events and the payloads are given below. ### Order Confirmation LatitudePay is offering webhook integration for Online and Offline orders. During the configuration please make sure to inform the team about the type of order you would like to receive the webhook event for. This webhook is triggered when an order is confirmed at LatitudePay. If you receive this webhook, you can be rest assured that order is placed successfully. **Event Name: PAYMENT\_CONFIRMED** **Payload:** :::CodeblockTabs ```json { "merchant_order_id": "", "latitudepay_order_id" : "1000000466", "event_name": "PAYMENT_CONFIRMED", "amount": "1000.0000", "event_id": "" "signature": "", "additional_data": { "charge_id": "" } } ``` Sample Json ```none { "merchant_order_id": "TEST_MERCHANT_ORDER_001", "latitudepay_order_id": "1000000001", "event_name": "PAYMENT_CONFIRMED", "amount": "100.0000", "event_id": "1275dce7-e4ec-46d9-be79-939df4fe0d47", "signature": "ea6b98d1fb0523ed7970364fa3528083", "additional_data": { "charge_id": "a05eb901-c165-4aad-bfc9-c7731cd7b341" } } ``` ::: ### Partial Refund This event is triggered when order is partially refunded by merchant. **Event Name: PARTIAL\_REFUND** **Payload:** :::CodeblockTabs ```json { "merchant_order_id": "", "latitudepay_order_id" : "1000000466", "event_name": "PARTIAL_REFUND", "amount": "1000.0000", "event_id": "" "signature": "", "additional_data": { "charge_id": "" } } ``` Sample Json ```none { "merchant_order_id": "TEST_MERCHANT_ORDER_001", "latitudepay_order_id": "1000000006", "amount": "25.0000", "event_name": "PARTIAL_REFUND", "event_id": "38ee222b-d07f-4723-9201-9ca5d7bc8f45", "signature": "0b8965b1cd35948f09db6a73cdf6d4eb", "additional_data": { "charge_id": "" } } ``` ::: ### Order Cancellation This event is triggered when order is cancelled by merchant. Merchant can cancel order from merchant console or merchant app. **Event Name: ORDER\_CANCELLATION** **Payload:** :::CodeblockTabs ```json { "merchant_order_id": "", "latitudepay_order_id" : "", "event_name": "ORDER_CANCELLATION", "amount": "100.0000", "event_id": "" "signature": "", "additional_data": { "charge_id": "" } } ``` Sample Json ```none { "merchant_order_id": "TEST_MERCHANT_ORDER_001", "latitudepay_order_id": "1000000001", "amount": "91.0000", "event_name": "ORDER_CANCELLATION", "event_id": "bedd6aa3-7a4d-4c63-a00e-137bf2751092", "signature": "76c0c6364dfd4ad13bb44c85f906fde4", "additional_data": { "charge_id": "" } } ``` ::: ### Order Timeout (ORDER\_TIMEOUT) This event is triggered when order is timed out at latitudepay. This is one of very important event for reconcilation perspective. In case the merchant is ecommerce and redirects customer to LatitudePay website for payment, there are various scenarios where customer might abdoned the journey like closing browser without doing payment, in such cases its important that merchant system be informed that customer has left the payment in between and order is expired so that both the systems are in sync. **Event Name: ORDER\_TIMEOUT** **Payload:** :::CodeblockTabs ```json { "merchant_order_id": "", "latitudepay_order_id" : "1000000466", "event_name": "ORDER_TIMEOUT", "amount": "0", "event_id": "" "signature": "", "additional_data": { "charge_id": "" } } ``` Sample Json ```none { "merchant_order_id": "TEST_MERCHANT_ORDER_001", "latitudepay_order_id": "1000000001", "amount": "0.0000", "event_name": "ORDER_TIMEOUT", "event_id": "d67de884-078f-41f3-9722-b46825117891", "signature": "a9e0cdd966da816ea26cdbc4900e1e05", "additional_data": { "charge_id": "" } } ``` ::: **Verify Webhook Signature** To verify the authenticity of event, we generate checksum and send it as part of payload (signature) which is hexadecimal string. This signature is generated by concatinating following strings together and generating MD5 hash of concatinated string. 1. Event ID from payload 2. Your Private API Key 3. Total Amount of Order 4. Merchant Order ID (for ecom Merchant only) e.g: - Consider the sample paylod from ORDER\_TIMEOUT event above - Assume your private key is : demo\_hardcoded\_private\_key\_btL7eqg9 - concatinated\_string = concat("d67de884-078f-41f3-9722-b46825117891" + "demo\_hardcoded\_private\_key\_btL7eqg9"+"0.0000"+"TEST\_MERCHANT\_ORDER\_001") - MD5(concatinated\_string) => "a9e0cdd966da816ea26cdbc4900e1e05" The generated string can be compared to recieved signature in the event json to verify that event was indeed sent by LatitudePay system itself. Ensure that your private keys are stored safe and is not publicly exposed. :::hint{type="info"} The Private Key used for creating signature may difers for Offline and Ecommerce orders. Based on which key is used by the merchant. 1. For Offline orders the private key will always be the latest private key generated by the merchant. 2. For Ecommerce orders the private key will be the key corresponding to the public key provided by the Merchant Site during order creation. It can be the latest generated key or an old public key. ::: ## ## Step 3: IP whitelist ### Staging: The full list of IP addresses that **latitudepay.me**, **k2.latitudepay.me** may resolve to is: :::CodeblockTabs IP Address ```ini 34.150.108.124 35.241.120.114 ``` ::: ### Production : **Singapore** The full list of IP addresses that **app.sg.latitudepay.com**, **k2.sg.latitudepay.com** may resolve to is: :::CodeblockTabs SG: IP Address ```ini 35.247.129.177 ``` ::: **Malaysia** The full list of IP addresses that **app.my.latitudepay.com**, **k2.my.latitudepay.com** may resolve to is: :::CodeblockTabs MY: IP Address ```ini 34.124.177.2 ``` ::: ## Conclusion Reconciliation is an important activity where two different systems are involved in transaction. By integrating the webhook provided by LaitudePay, merchant can be rest assured to receive updates of activities over API call, which can be further used to trigger various internal processes, and also helps mitigate the complex dangling scenarios where customer can abonden the journey at any point during checkout. If you have any further questions or need assistance during integration, please contact our support team. Happy integrating!