Register Endpoint

To register your Webhooks URL, send the endpoint details to the Integrations team. Direct configuration of endpoints through the system isn’t currently available.

The Integrations team will complete the registration on your behalf and confirm once your endpoint is successfully configured.

Note: Ensure that your endpoint supports HTTPS and can handle requests sent from the integration team.

Secure Your Endpoint

Security is critical when working with webhooks. Integration team require integrators to:

• Use HTTPS endpoint.

• Restrict IP addresses (if applicable)

Verify Your Signature

Each webhook request includes a secure signature header to confirm its authenticity. Verifying this signature helps ensure the payload was sent by Xplor Pay.

Note: Signature verification is applicable only for only transaction alert webhook. Other webhook types do not include signature validation.

Webhook Notifications

Once your endpoint is registered and webhooks are configured, you will begin receiving event notifications relevant to your merchant account.

Refer to the sample structure of webhook notifications:

{
  "event": "Manual Review",
  "merchantId": "6588949900000011",
  "payload": null
}

Note: The payload value varies by event type. Some events return null, while others include additional JSON data relevant to the event.

Retry Logic

If your endpoint does not acknowledge receipt of a webhook (i.e., returns a non-2xx status), the system will automatically retry the callback. A 2xx status code (e.g., 200 OK) indicates successful receipt of the webhook, and no retry will be attempted.

Non-2xx status codes (e.g., 400 Bad Request, 500 Internal Server Error) indicate failure. The system will retry the request based on the retry policy.

• Total Attempts: Up to 3 delivery attempts

• Retry Strategy: Exponential backoff is applied between each attempt

This ensures reliable delivery of webhook events, even if your endpoint is temporarily unavailable.

Note: To avoid missed events, ensure your server responds with a 2xx status code upon successful receipt.

Testing Webhooks

To test your webhook integration, make sure your endpoint returns a proper HTTP status code to indicate the result of processing the request. To help you test different webhook response scenarios in the INT (integration) environment, the system recognizes special keywords in the merchant’s DBA (Doing Business As) name field. Use the following naming conventions to simulate specific onboarding outcomes:

• [DECL] – The application will be marked as Declined after signing. A webhook will be triggered with the "Declined" status.

• [PEND] – The application will move to Pended status after signing. You will receive a webhook indicating this status change.

• [APPR] – The application will be marked as Approved after signing, and a corresponding webhook will be sent.

Note: Ensure that the DBA name includes the exact keyword in brackets (e.g., MyStore [DECL]) to trigger the appropriate behavior in the INT environment.