To integrate Ezypay webhooks, you need an HTTPS public endpoint capable of receiving real-time event notifications. Each merchant must subscribe to their own webhook - though multiple webhooks can target the same URL. Use the merchantId in the webhook payload to identify the merchant associated with each event. Webhooks are critical for handling asynchronous events, such as bank transactions, failed payments etc.

Prerequisites

Public Endpoint

Ensure your webhook endpoint is publicly accessible so Ezypay can deliver event notifications. Without public accessibility, event delivery will fail.

Response Requirements

Ensure the webhook endpoint responds with a 2xx HTTP status code upon successful event processing. Otherwise, Ezypay will treat the delivery as failed and attempt retries.

Get Started

Use Create Webhook API to subscribe merchants to relevant events.

1. Provide the webhook endpoint URL and specify the events to subscribe to in the API request body.
2. Upon success, a unique webhook ID (id) is returned. Save this ID for future maintenance.

{
  "url": "https://companyName.net/callback",
  "eventTypes": [
    "invoice_created",
    "customer_create",
    "subscription_activate",
    "subscription_payment_reactivate",
    "payment_method_invalid",
    "payment_method_replaced",
    "invoice_paid",
    "invoice_past_due",
    "subscription_create",
    "subscription_cancel",
    "invoice_batch_created",
    "invoice_batch_processing",
    "invoice_batch_success",
    "invoice_batch_invoice_failed"
  ]
}

{
  "url": "https://companyName.net/callback",
  "eventTypes": [
    "invoice_created",
    "customer_create",
    "subscription_activate",
    "subscription_payment_reactivate",
    "payment_method_invalid",
    "payment_method_replaced",
    "invoice_paid",
    "invoice_past_due",
    "subscription_create",
    "subscription_cancel",
    "invoice_batch_created",
    "invoice_batch_processing",
    "invoice_batch_success",
    "invoice_batch_invoice_failed"
  ],
  "id": "2c4e8865-1e9f-4dcb-88d4-c36f3cc9ea83",
  "createdOn": "2019-07-12T06:55:54.526"
}

3. Simulate subscribed events to test your webhook implementation. Refer to webhook behaviour and full webhook events list

Best Practice

Minimum required events

Ezypay recommends including the following key events in all integrations:

* Important if integrating with PayTo.
** Important for subscription models.

Handle Duplicate Events

Log the requestId of each received event. Duplicate requestIds indicates retry attempts and can be safely ignored.

Webhook Failure Monitoring

Ezypay does not notify integrators when the webhook endpoint returns a failure response. Implement error logging and monitoring within your system to detect consistent failures and reach out to Ezypay support if they persist. For sporadic failures, you may rely on automatic retry attempts.

Automated Webhook Creation

To streamline onboarding, automate the webhook creation process via API calls when provisioning new merchant credentials. This reduces manual errors and ensures timely setup.