Managing Webhooks

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

Identify which events you want to monitor.


Identify which events you want to monitor and which event payloads you need to parse.

Refer to Payment Statuses to expand your understanding of Maya’s payment statuses and how they can change over time.

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 the Sandbox environment before proceeding to the 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. 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 the Sandbox environment before proceeding to the 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 a 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.
RECURRING_PAYMENT_SUCCESSProduct/s: VAULT

An event to describe the successful completion of a payment transaction using the vaulted card.
RECURRING_PAYMENT_FAILUREProduct/s: VAULT

An event when the transaction using the vaulted card is not successful.

2 Create a webhook endpoint

Set up and prepare your webhook.

Webhooks must be secured with SSL-secured (https) and publicly accessible. Set up a webhook URL that accepts JSON payloads via POST requests from Maya.

It is recommended that you configure SSL on port 443, otherwise your application may experience network issues when integrating with Maya.

3 Handle requests from Maya

You must handle webhook events correctly to ensure 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 code.

Webhook notifications

Webhook notifications should come from this IP address list. It is recommended to whitelist the list in your network.

EnvironmentIP Addresses
Sandbox13.229.160.234
3.1.199.75
Production18.138.50.235
3.1.207.200

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



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 minutes after the previous webhook call failed.
  • 15 minutes after the previous webhook call failed
  • 45 minutes after the 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

Test to validate 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


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

Deploy and register your webhook.


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

1 Login to Maya Business Manager

Log in 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 set up 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 before 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 .

6 Process webhook notifications coming from Maya

Whitelist Maya IP Addresses.


To boost security, apply a whitelisting mechanism and whitelist Maya IP Addresses. Webhook notifications should come from the IPs listed below:

Webhook notifications should come from this IP address list. It is recommended to whitelist the list in your network.

EnvironmentIP Addresses
Sandbox13.229.160.234
3.1.199.75
Production18.138.50.235
3.1.207.200

Frequently Asked

Test webhook responded with failed to connect: getaddrinfo: Name or service not known

Answer: The Webhook Test tool in Maya Manager is under maintenance. We recommend testing your webhooks via cURL in your terminal or Postman.

Test webhook responded with failed to connect: getaddrinfo: Name or service not known when I click “Save and Test”

Answer: The Webhook Test tool in Maya Manager is under maintenance but your webhook is saved. We recommend testing your webhooks via cURL in your terminal or Postman.