Configuring Webhooks for Create Payment V2

Overview

Webhooks (or sometimes called callbacks) let Create Payment V2 notify your server in real-time whenever important payment events occur, such as a successful payment or a failed transaction.

For Create Payment V2, customer information is also sent to your system via webhook.

This guide explains how to implement, secure, test, and register webhooks for Create Payment V2.

Webhook Events in Payment V2

Payment V2 Events:

Maya triggers webhook events based on the paymentStatus of a transaction. Each event represents a specific state in the payment lifecycle.

Document Event:

Getting Started with your Webhooks for Create Payment V2

To start receiving webhook events from Create Payment V2, follow these steps:

1. Create a webhook endpoint
2. Secure your webhook
3. Handle webhook events
4. Respond to webhooks
5. Test your integration
6. Register your webhook endpoint

You can configure a single webhook endpoint to handle multiple event types, or set up separate endpoints for specific events depending on your requirements.

1. Create a Webhook Endpoint

Set up an HTTPS endpoint on your server that can receive POST requests.

Requirements:

• Must use SSL (https) on port 443
• Must return a 200 OK response to acknowledge receipt
• Must be accessible so Maya can deliver events

2. Secure Your Webhook

Before handling events, make sure your webhook endpoint only accepts traffic from Maya.

Restrict incoming traffic to Maya’s official IP addresses:

Best practices:

• Whitelist the correct set of IPs based on your environment
• Production systems should only allow Maya’s production IPs
• Reject requests from unlisted sources

3. Respond to webhooks

Your webhook endpoint should always return a 200 OK response as quickly as possible (within 5 seconds) or before executing complex logic or validations. If your server fails to acknowledge, Maya will retry the webhook multiple times with exponential backoff.

Retry Mechanism on Webhooks

Create Payment V2 automatically retries failed webhook deliveries if your endpoint does not return a 2xx response. Retries occur when your server responds with a 3xx, 4xx, or 5xx status code, or if the request times out.

Maya will attempt delivery up to four (4) times total, including the initial attempt when the payment event is triggered:

1. Initial attempt, sent immediately after the event occurs
2. 5 minutes after the previous attempt failed
3. 15 minutes after the previous attempt failed
4. 45 minutes after the previous attempt failed

If, after the final attempt, Maya still does not receive a valid 2xx response, the event is marked as failed, and no further retries will be made.

After responding to the webhook, your system can proceed to apply your business logic (e.g., reconciliation, mark an order as paid)

4. Handle Webhook Events

For Payment Events (PAYMENT_SUCCESS, PAYMENT_FAILED):

• Parse the JSON payload
• Inspect the paymentStatus field to identify which event occurred
• Store or log the event for auditing
• Process webhooks in an idempotent manner

For DOCUMENT_READY:

• Parse the JSON payload
• Inspect the id field to identify for which paymentId the DOCUMENT_READY is.
• Process the pre-signed url

Handling duplicate webhook events

Your webhook endpoint may receive the same event multiple times. This can happen due to:

• Maya’s built-in retry mechanism
• Manual webhook replays from Maya Manager (for Payment V2 Events ONLY)

An effective approach is to log the events you have already processed and avoid processing events that have already been logged.

5. Test your integration

You can execute your webhook endpoint via a simple curl command or through an API client application like Postman.

If your endpoint responds with 200 OK, it is reachable and working.

6. Register your webhooks to Maya

Maya needs to know where to send the events. To do so, you should register the publicly accessible HTTPS URL of your webhook endpoint and indicate the type of events that you wish to receive.

6.1. For Payment V2 Events (PAYMENT_SUCCESS, PAYMENT_FAILED):

You can register webhooks in two ways:

• UI-based via Maya Manager (Maya Business Manager or Maya Manager 1.0)
• Create Webhook API endpoint (programmatic)

A. Settings menu in Maya Manager

1. Log in to your Maya Manager account.
2. Go to Settings from the left navigation panel.
3. Click Webhooks under Settings.
4. Select the Merchant Account where you want to configure the webhook.
5. The event types you want to subscribe to (e.g., PAYMENT_SUCCESS, PAYMENT_FAILED) and provide your HTTPS webhook endpoint URL
6. Use the Test button to verify reachability.
7. Click Save and Test to complete registration.

B. Using the Create Webhook endpoint

You can register webhooks directly via API for automation or CI/CD flows. For reference, see Create Webhook endpoint.

Request:

• Method: POST
• Endpoint: /payments/v1/webhooks
• API Authentication: Basic Authentication (using your API secret key)

Body (example JSON):

{
  "name": "PAYMENT_SUCCESS",
  "callbackUrl": "https://yourdomain.com/webhooks/payment"
}

Response:

A successful registration will propagate to the Settings > Webhooks section in your Maya Manager dashboard.

6.2. For DOCUMENT_READY:

Submit the webhook endpoint for the DOCUMENT_READY event to the Maya Representative for registration.

FAQs

Q: Test webhook in Maya Manager responded with failed to connect: getaddrinfo: Name or service not known.

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

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

A: 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.

Next Steps

You now have a secure, idempotent, and reliable webhook integration for Create Payment V2. To move forward:

1. Complete End-to-End Testing
   • Simulate all relevant webhook events (e.g., PAYMENT_SUCCESS, PAYMENT_FAILED)
   • Verify that your system correctly logs, updates order statuses, and reconciles transactions
2. Document Your Test Results
   • Record sample payloads, responses, and observed system behavior
   • Include details on error handling and retry validations