# PayMaya Payment Gateway - Webhook Guide
## Actors
In the Payment Gateway purchase flow, the actors are defined as the following:
- Customer - Person who is buying the item/service.
- Merchant - Person who is providing the item/service.
- PayMaya Payment Gateway - Payment acceptance platform.
## Transaction flow
```mermaid
graph LR
A(Customer) -- 1. Request to purchase from --> B(Merchant)
B -- 2. Redirects Customer to PayMaya --> A
A -- 3. Completes payment on --> C(PayMaya Payment Gateway)
C -- 4. Inform of payment status --> B
```
In this flow step 4 is the webhook trigger.
# Best Practice
:::danger
:warning: It is required to implement and use webhooks when integrating your application with our services. This is to ensure payment statuses are communicated to your application in real-time.
:::
# FAQ
## Q. What is a webhook exactly?
A webhook is a simple HTTP request done by PayMaya over the web to inform the Merchants of changes of the statuses of their Payments.
## Q. The customer is redirected to our success URL. Can we skip the webhook?
No. In the transaction flow only PayMaya can reliably give the Merchant the correct Payment Status information. This is provided in either the webhook or the GET Payment API.
## Q. We are doing a GET Payment after Redirection. Can we skip the webhook?
No. Redirection is still unreliable. There are many use cases wherein the Customer does not redirect back to the Merchant website.
To name a few:
- User cancellation
- Loss of power
- Loss of connectivity
## Q. What happens if we do not implement the webhooks?
Your system will be vulnerable to the following issues:
- Uninformed status changes. - Customers are debited funds but your website will not release the goods.
- Spoofing Attacks. - Malicious actors can skip the Payment step and redirect direct to the success page to get the goods.
## Q. I am on Shopify / Woocommerce / Magento do I still need to setup webhooks?
For Shopify, No.
For Woocommerce, it comes with a built in webhook receiver. You only need to register the URL.
For Magento, you need to set it up.
## Q. How should we create the webhook endpoint?
It must accept a POST request on SSL port 443. Port 80 is allowed for Sandbox only. The recommended processing is as follows:
1. Find related Merchant transaction record using Payment Request Reference Number
2. Check currency and amount against Merchant records.
3. Check payment status
4. Update Merchant transaction record status accordingly
For the responses:
- If completed successfully,
- respond with HTTP 200 Ok
- If Merchant transaction record was already updated,
- respond with HTTP 202 Accepted
- If no related Merchant transaction record was found,
- respond with HTTP 204 No Content
- On failure,
- respond with appropriate error code
> Body is **not** required in the webhook response.
## Q. Webhook endpoint has been created. How do we tell PayMaya?
You may register your webhook endpoints thru the Settings page on PayMaya Manager or via the webhook API of your availed Product.
[Checkout Webhook](https://s3-us-west-2.amazonaws.com/developers.paymaya.com.pg/checkout/checkout.html#webhook-webhook-endpoints)
[Payment Vault Webhook](https://s3-us-west-2.amazonaws.com/developers.paymaya.com.pg/payment-vault/paymentvault.html#webhooks-webhook-endpoints)
[Pay With PayMaya Webhook](https://s3-ap-southeast-1.amazonaws.com/developers.paymaya.com.pay-by-paymaya/index.html#wallet-payment-recurring-payment-get)
## Q. When are the webhooks triggered?
Webhooks are triggered on the following events
|Webhook Name|Event
|-|-
|CHECKOUT_SUCCESS|On successful Checkouts
|CHECKOUT_FAILURE|On failed Checkouts
|CHECKOUT_DROPOUT|On expired Checkouts
|3DS_PAYMENT_SUCCESS|On success Payment Vault 3ds Payments
|3DS_PAYMENT_FAILURE|On failure of Payment Vault 3ds Payments
|3DS_PAYMENT_DROPOUT|On expiry of Payment Vault 3ds Payments
|RECURRING_PAYMENT_SUCCESS|On success of Subscription Payments
|RECURRING_PAYMENT_FAILURE|On failure of Subscription Payments
|PAYMENT_SUCCESS|On ANY Payment Success
|PAYMENT_FAILED|On ANY Payment Failed
|PAYMENT_EXPIRED|On ANY Payment Expiry
> It is recommended to use the generic PAYMENT_SUCCESS, PAYMENT_FAILED, PAYMENT_EXPIRED webhooks.
## Q. What are the minimum webhooks we need to set?
It is recommend to set all three webhooks for the set of the product you availed or all three generic webhooks. The bare minimum would be at least the success webhook of your availed product.
## Q. What data is being sent over the webhooks?
For Checkout webhooks the payload is equivalent to the contents of the GET Checkout API.
For all other webhooks the payload is equivalent to the contents of the GET Payment API.
## Q. What happens when the webhook request fails?
PayMaya's Webhook will trigger a maximum of 4 times.
- Immediately after the status event is triggered
- 5mins after the previous webhook call failed
- 15mins after the previous webhook call failed
- 45mins after previous webhook call failed
## Q. Our system went down and the webhook was not able to retry within the timeframe. How can we update our records?
You may do a GET Payment to update your records. You may also manually trigger webhook calls via PayMaya Manager.
## Q. The webhook tester on PayMaya Manager does not send the correct payload!
The webhook tester is for connectivity purposes and sends a dummy payload over POST. Use this to smoke test connections from PayMaya to your servers.
For actual testing of your webhook endpoints, we recommend doing test transactions or using the retrigger webhook on PayMaya Manager.
## Q. PayMaya Webhooks can be spoofed or be hit by man in the middle attacks. What can we do to prevent it?
Always use HTTPS with at least TLS 1.2 for the webhook endpoint. We recommend whitelisting our webhook servers IP address.
The following IP addresses are for Sandbox:
- 13.229.160.234
- 3.1.199.75
The following IP addresses are for Production:
- 18.138.50.235
- 3.1.207.200
- 52.76.121.68
## Q. We have setup our webhook but we are not receiving any requests.
Please make sure your endpoint is accessible publicly thru the web.
PayMaya cannot send webhooks to "localhosts". You might want to check [https://ngrok.com/](https://ngrok.com/)
Please make sure your SSL certificate is not self signed, missing any certificate chains, and supports TLS1.2.
## Q. My webhook is setup! How can I proceed?
Our Merchant Services team will validate your setup. Please send us a few Payment Ids wherein you did you testing.
---
##### Thank you for reading this document :3
> Last updated on 5/12/2020