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 EventDescription
PAYMENT_SUCCESSProduct/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_FAILEDProduct/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_EXPIREDProduct/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_CANCELLEDProduct/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.
AUTHORIZEDProduct/s: CHECKOUTVAULT

ℹ️ This is only applicable to Card Payments.


An event when a hold was successfully placed on the customer’s account for the specific transaction.
3DS_PAYMENT_SUCCESSProduct/s: VAULT

An event that occurs when the customer completes the 3D Secure authentication step.
3DS_PAYMENT_FAILUREProduct/s: VAULT

An event when customer fails the 3D Secure authentication step.
3DS_PAYMENT_DROPOUTProduct/s: VAULT

This is when the 3D Secure authentication is not completed within a certain period of time.
RECURRING_PAYMENT_SUCCESSProduct/s: VAULT

An event to describe the successful completion of a payment transaction using vaulted card.
RECURRING_PAYMENT_FAILUREProduct/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.

  1. Immediately after the status event is triggered
  2. 5 minutes after the previous webhook call failed
  3. 15 minutes after the previous webhook call failed
  4. 45 minutes after previous webhook call failed

If Maya doesn’t quickly receive a 2xx response 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.