Webhooks for Payment Solutions
Receive real-time payment information using webhooks
Use incoming webhooks to get real-time updates
Maya uses webhooks to notify your application when a specific event occurs with your payment request, such as when a customer decides not to authorize a payment, when a payment fails, or when a payment succeeds.
1 Identify the events
Click here to view full details
Identify which events you want to monitor and which event payloads you need to parse.
Expand your understanding on Maya’s payment statuses and the ways in which they can change over time. See Payment Statuses.
Webhook Events for Online Payment Solutions
| Webhook Event | Description |
|---|---|
| PAYMENT_SUCCESS | Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS An event to describe the successful completion of a payment transaction. Merchants who are still subscribed to CHECKOUT_SUCCESS endpoint should start subscribing to the PAYMENT_SUCCESS webhook soon and discontinue their subscription to the CHECKOUT_SUCCESS webhook. Please test any changes made in Sandbox environment before proceeding to Production environment. |
| PAYMENT_FAILED | Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS An event when the transaction is not successful due to a variety of reasons. Common reasons for payment failure include insufficient funds, closed accounts and suspected fraud. Merchants who are still subscribed to CHECKOUT_FAILURE endpoint should start subscribing to the PAYMENT_FAILED webhook soon and discontinue their subscription to the CHECKOUT_FAILURE webhook. Please test any changes made in Sandbox environment before proceeding to Production environment. |
| PAYMENT_EXPIRED | Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS An event that occurs when a payment transaction is not completed within a certain period of time. This can happen when customer decided not to authorize the transaction or did not complete the authentication. Merchants who are still subscribed to CHECKOUT_DROPOUT endpoint should start subscribing to the PAYMENT_EXPIRED webhook soon and discontinue their subscription to the CHECKOUT_DROPOUT webhook. Please test any changes made in Sandbox environment before proceeding to Production environment. |
| PAYMENT_CANCELLED | Product/s: INVOICE CHECKOUTPAY WITH MAYAVAULTPLUGINS This is when a payment is stopped or reversed, either by the payer or the payee. This can occur for a variety of reasons, such as incorrect information, insufficient funds, or for security reasons. Merchants who are still subscribed to CHECKOUT_CANCELLED endpoint should start subscribing to the PAYMENT_CANCELLED webhook soon and discontinue their subscription to the CHECKOUT_CANCELLED webhook. Please test any changes made in Sandbox environment before proceeding to Production environment. |
| AUTHORIZED | Product/s: CHECKOUTVAULT
An event when a hold was successfully placed on the customer’s account for the specific transaction. |
| 3DS_PAYMENT_SUCCESS | Product/s: VAULT An event that occurs when the customer completes the 3D Secure authentication step. |
| 3DS_PAYMENT_FAILURE | Product/s: VAULT An event when customer fails the 3D Secure authentication step. |
| 3DS_PAYMENT_DROPOUT | Product/s: VAULT This is when the 3D Secure authentication is not completed within a certain period of time. |
| RECURRING_PAYMENT_SUCCESS | Product/s: VAULT An event to describe the successful completion of a payment transaction using vaulted card. |
| RECURRING_PAYMENT_FAILURE | Product/s: VAULT An event when the transaction using the vaulted card is not successful. |
2 Create a webhook endpoint
Click here to view full details
Set up an HTTP webhook URL that can accept a JSON payload via a POST request from Maya.
Keep in mind
Webhooks should be SSL-secured (https) and publicly accessible.
In addition, it is recommended that you configure SSL on port 443, otherwise your application may experience network issues when integrating with Maya.
const express = require('express');
const app = express();
app.post('/webhook', async (req, res) => {
// TODO: You will have to implement the logic of this method.
processMayaWebhookNotificationData(req.body);
res.send({
success: true
})
});
app.listen(8080, () => console.log('Listening on port ${8080}!'));
3 Handle requests from Maya
Click here to view full details
It is crucial that you handle webhook events correctly to ensure that your integration's logic works as expected.
Maya sends events to your webhook endpoint as part of a POST request with a JSON payload. Your endpoint must be configured to receive it for a given event and is expected to return a 2xx response status codes.
Check JSON payload
Each event is structured as an object with an id, paymentStatus and other payment details. Your endpoint must check the paymentStatus and parse the payload of each event.
Explore Maya's sample JSON webhook payloads.
$ curl -s -D - -o /dev/null -X POST -H "Content-Type: application/json" \
-d '{
"id": "fa4da2ff-dcda-4367-a97d-0c9445147b73",
"items": [...],
"requestReferenceNumber": "5fc10b93-bdbd-4f31-b31d-4575a3785009",
"receiptNumber": "7fa0ff6fa5a6",
"createdAt": "2021-07-13T15:25:45.000Z",
"updatedAt": "2021-07-13T15:26:49.000Z",
"paymentScheme": "master-card",
"expressCheckout": true,
"refundedAmount": "0",
"canPayPal": false,
"expiredAt": "2021-07-13T16:25:45.000Z",
"status": "COMPLETED",
"paymentStatus": "PAYMENT_SUCCESS",
...
}' \
https://83ef-130-105-160-253.ngrok.io/webhook
Return a 2xx response
Before executing any complex logic that may cause a timeout or validation error, your endpoint should promptly respond with a successful status code (2xx).
Built-in retries
The webhooks of Payment Solutions come with automatic retry mechanisms for response status codes of 3xx, 4xx, or 5xx. The system will attempt a maximum of four (4) retries.
- Immediately after the status event is triggered
5 minutesafter the previous webhook call failed15 minutesafter the previous webhook call failed45 minutesafter previous webhook call failedIf Maya doesn’t quickly receive a
2xxresponse status code for an event, we mark the event as failed and stop trying to send it to your endpoint.
Handle duplicate events
We recommend that you process webhooks in an idempotent manner as your webhook endpoints might receive the same event from Maya more than once (e.g. you manually invoked webhook via Maya Manager, or from Maya's built-in retries). An effective approach is to log the events you have already processed and avoid processing events that have already been logged.
4 Test your webhook endpoint
Click here to view full details
Test that your webhook endpoint is working properly. You can execute your webhook endpoint via a simple curl command or through an API client application like Postman.
Sample Webhook Endpoint Test via curl
$ curl -s -D - -o /dev/null -X POST -H "Content-Type: application/json" \
-d '{
"id": "fa4da2ff-dcda-4367-a97d-0c9445147b73",
"items": [
{
"name": "Canvas Slip Ons",
"code": "CVG-096732",
"description": "Shoes",
"quantity": "1",
"amount": {
"value": 1000
},
"totalAmount": {
"value": 1000
}
}
],
"requestReferenceNumber": "5fc10b93-bdbd-4f31-b31d-4575a3785009",
"receiptNumber": "7fa0ff6fa5a6",
"createdAt": "2021-07-13T15:25:45.000Z",
"updatedAt": "2021-07-13T15:26:49.000Z",
"paymentScheme": "master-card",
"expressCheckout": true,
"refundedAmount": "0",
"canPayPal": false,
"expiredAt": "2021-07-13T16:25:45.000Z",
"status": "COMPLETED",
"paymentStatus": "PAYMENT_SUCCESS",
"paymentDetails": {
"responses": {
"efs": {
"paymentTransactionReferenceNo": "0bea058b-ae8e-4bfc-90d0-7fa0ff6fa5a6",
"status": "SUCCESS",
"receipt": {
"transactionId": "b8bb70e1-f44f-4db3-bcb9-a939d38455a4",
"receiptNo": "7fa0ff6fa5a6",
"approval_code": "00001234",
"approvalCode": "00001234"
},
"payer": {
"fundingInstrument": {
"card": {
"cardNumber": "542482******7140",
"expiryMonth": 9,
"expiryYear": "2023"
}
}
},
"amount": {
"total": {
"currency": "PHP",
"value": 1000
}
},
"created_at": "2021-07-13T15:26:49.514Z"
}
},
"paymentAt": "2021-07-13T15:26:49.000Z",
"3ds": false
},
"buyer": {
"contact": {
"phone": "+639086216587",
"email": "[email protected]"
},
"firstName": "John",
"lastName": "Doe",
"billingAddress": {
"line1": "6F Launchpad",
"line2": "Reliance Street",
"city": "Mandaluyong City",
"state": "Metro Manila",
"zipCode": "1552",
"countryCode": "PH"
},
"shippingAddress": {
"line1": "6F Launchpad",
"line2": "Reliance Street",
"city": "Mandaluyong City",
"state": "Metro Manila",
"zipCode": "1552",
"countryCode": "PH"
}
},
"merchant": {
"currency": "PHP",
"email": "[email protected]",
"locale": "en",
"homepageUrl": "https://www.paymaya.com",
"isEmailToMerchantEnabled": true,
"isEmailToBuyerEnabled": true,
"isPaymentFacilitator": false,
"isPageCustomized": true,
"supportedSchemes": [
"Visa",
"Mastercard",
"JCB"
],
"canPayPal": false,
"payPalEmail": null,
"payPalWebExperienceId": null,
"expressCheckout": true,
"name": "Omni Merchant via Mock Processor"
},
"totalAmount": {
"amount": "1000",
"currency": "PHP",
"details": {
"discount": "100.00",
"serviceCharge": "0.00",
"shippingFee": "200.00",
"tax": "120.00",
"subtotal": "780.00"
}
},
"redirectUrl": {
"success": "https://www.merchantsite.com/success?id=5fc10b93-bdbd-4f31-b31d-4575a3785009",
"failure": "https://www.mechantsite.com/failure?id=5fc10b93-bdbd-4f31-b31d-4575a3785009",
"cancel": "https://www.merchantsite.com/cancel?id=5fc10b93-bdbd-4f31-b31d-4575a3785009"
},
"transactionReferenceNumber": "0bea058b-ae8e-4bfc-90d0-7fa0ff6fa5a6"
}' \
https://83ef-130-105-160-253.ngrok.io/webhook
When the output of the curl command shows a 200 response code that means that your webhook endpoint is reachable and will return a status 200 OK.
HTTP/2 200
content-type: application/json; charset=utf-8
date: Mon, 14 Feb 2022 01:08:14 GMT
ngrok-agent-ips: 130.105.160.253
content-length: 18
5 Register your webhook URLs to Maya
Click here to view full details
Keep in mind
For plugin users: To ensure that your webhooks are properly registered when using plugins, register them through the plugin dashboard. It will automatically populate Maya Manager. It is important to avoid editing the auto-generated webhook URLs in Maya Manager.
Maya needs to know where to send the events. To do so, you should provide the publicly accessible HTTPS URL for your webhook endpoint and indicate the type of events that you wish to receive.
You can register your webhook endpoints by accessing the Settings menu in Maya Business Manager, or by using the Create Webhook endpoint.
When you register webhooks using the Create Webhook endpoint, they will also be visible in Maya Business Manager under the Settings section.
Register via Maya Business Manager
Click here to see the steps
1 Login to Maya Business Manager
Login using your Maya Business Manager account.
2 Go to Settings
Click Settings on the left-hand navigation of the dashboard.
3 Click Webhooks
Click Webhooks under Settings, on the left-hand navigation of the dashboard.
4 Select your Merchant
Select the Merchant account where you want to setup your webhook.
5 Input your webhook
Provide the publicly accessible HTTPS URL for your webhook endpoint on the type of events that you wish to receive.
6 Test your webhook
Utilize these Test buttons to check if your webhooks are reachable prior to saving it.
7 Save your webhook
Click the Save and Test button to complete the registration of your webhooks.
Do you have any questions? Check out our Webhook FAQ.
Updated over 1 year ago