Configuring Your Webhook for Maya Checkout

Overview

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

Instead of polling the API for updates or expecting the Create Checkout endpoint to return the final payment status, your system should listen for server-to-server webhook events. This ensures you always receive the final payment status and react automatically. For example, by updating an order status, triggering internal workflows, or notifying customers.

This guide explains how to implement, secure, test, and register webhooks for Maya Checkout.

Webhook Events in Maya Checkout

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

Migration Notice

To merchants who are still subscribed to CHECKOUT_* events (CHECKOUT_SUCCESS, CHECKOUT_FAILED, CHECKOUT_DROPOUT, CHECKOUT_CANCELLED), you should:

• Subscribe to the corresponding PAYMENT_* events as soon as possible
• Discontinue your subscription to the legacy CHECKOUT_* events

This ensures compatibility with the latest API updates and provides more consistent event handling. Always test webhook handling in the Sandbox environment before moving to Production.

Interpreting Webhook Payloads

Every webhook event sent by Maya Checkout is a JSON object that includes an id, paymentStatus, and other payment details. Your integration must parse this payload and process the event accordingly (e.g., mark an order as paid, log the attempt, or trigger downstream workflows).

Handling webhook events for QRPH payments:

• If fundSource.type = maya-wallet: always use the id (or payment ID) where the last 12 characters align with the Maya App receipt. This is to ensure accurate tracking and correlation with Maya App receipts.
• If fundSource.type = qrph: use the receiptNumber, which serves as the issuer-generated reference number, which is also mirrored in the issuer receipts. This approach ensures a reliable method for transaction identification and reconciliation.

For more details, refer to QRPH Payments.

Getting Started with your Webhooks for Maya Checkout

To start receiving webhook events from Maya Checkout, 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

Maya Checkout 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

Webhook requests from Maya contain a JSON payload equal to the successful response of the GET Payment endpoint.

Your implementation should:

• 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

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

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.

You can register webhooks in three 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.

FAQs

Q: Test webhook 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 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.

Q: What should I do if there’s an error when Maya sends a webhook to our endpoint?

Answer:

• Review how your system parses and validates the webhook payload. You can refer to the Handling Webhooks from Maya section for more details.
• Implement fallback APIs, like the GET /payments endpoints, to recover from errors when processing webhook notifications from Maya Checkout.

Next Steps

You now have a secure, idempotent, and reliable webhook integration for Maya Checkout. To move forward:

1. Complete End-to-End Testing
   • Follow the Testing and Validating Your Maya Checkout Integration
   • Simulate all relevant webhook events (e.g., PAYMENT_SUCCESS, PAYMENT_FAILED, PAYMENT_EXPIRED)
   • 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