Webhook Integration Guide
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.
ο»Ώ
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 these steps to integrate LatitudePay's webhook functionality into your system:
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.
ο»Ώ
Specifications of events and the payloads are given below.
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:
This event is triggered when order is partially refunded by merchant.
Event Name: PARTIAL_REFUND
Payload:
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:
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:
ο»Ώ
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.
ο»Ώ
The full list of IP addresses that latitudepay.me, k2.latitudepay.me may resolve to is:
Singapore
The full list of IP addresses that app.sg.latitudepay.com, k2.sg.latitudepay.com may resolve to is:
Malaysia
The full list of IP addresses that app.my.latitudepay.com, k2.my.latitudepay.com may resolve to is:
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!
ο»Ώ