Webhook Integration Guide

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 follow this link for details prerequisites 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 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 { "merchant order id" "\<merchant order id>", "latitudepay order id" "1000000466", "event name" "payment confirmed", "amount" "1000 0000", "event id" "\<uuid>" "signature" "\<checksum>", "additional data" { "charge id" "\<charge id>" } } sample json { "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 { "merchant order id" "\<merchant order id>", "latitudepay order id" "1000000466", "event name" "partial refund", "amount" "1000 0000", "event id" "\<uuid>" "signature" "\<checksum>", "additional data" { "charge id" "\<charge id>" } } sample json { "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 { "merchant order id" "\<merchant order id>", "latitudepay order id" "\<latitudepay order id>", "event name" "order cancellation", "amount" "100 0000", "event id" "\<uuid>" "signature" "\<checksum>", "additional data" { "charge id" "\<charge id>" } } sample json { "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 { "merchant order id" "\<merchant order id>", "latitudepay order id" "1000000466", "event name" "order timeout", "amount" "0", "event id" "\<uuid>" "signature" "\<checksum>", "additional data" { "charge id" "\<charge id>" } } sample json { "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 event id from payload your private api key total amount of order 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 the private key used for creating signature may difers for offline and ecommerce orders based on which key is used by the merchant for offline orders the private key will always be the latest private key generated by the merchant 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 ip address 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 sg ip address 35 247 129 177 malaysia the full list of ip addresses that app my latitudepay com , k2 my latitudepay com may resolve to is my ip address 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!