​
Overview

This page explains how to set up and use webhooks. To begin, you must configure a single URL endpoint that will receive POST requests. This endpoint should be hosted on a server you control and be capable of processing incoming webhook payloads. All webhook events—such as initiated, processing, success, failed, and rejected—will be sent to the configured URL.

​
Where To Setup

​
Sandbox

To configure webhooks in the Sandbox environment:
  1. Go to Sandbox Dashboard → URLs.
  2. Enter your webhook endpoint URL in the provided field.

​
Production

To configure webhooks in the Production environment:
  1. Go to Production Dashboard → URLs.
  2. Enter your webhook endpoint URL in the provided field.

​
Webhook Events

Below is the list of webhook events sent by Paywint.
Event NameDescription
payment.initiatedPayment was initiated.
payment.processingPayment is being processed.
payment.successPayment was successful.
payment.failedPayment failed.
payment.rejectedPayment was rejected.
payment.retriedPayment was retried with new payment ID.
payment.openedPayment link was opened by the user.
payment.expiredPayment link has been expired.

​
Basic Structure

FieldDescription
eventThe type of event that occurred (e.g., payment.success).
idA unique identifier for this webhook delivery.
dataThe event-specific payload object.
eventGeneratedTimeUNIX timestamp (in seconds) when the event was generated.
Example payload: 
{
  "event": "payment.success",
  "id": "a891bfc2-ffff-464b-89e4-xxxxx",
  "data": {
    "payment_id": "b91a0f36-b10b-4a31-ae12-e8b4c5ee71f4",
    "status": "success",
    "amount": 599
  },
  "eventGeneratedTime": 1718006400.0
}

​
Delivery & Retry Behavior

If your webhook endpoint fails to return a 2xx HTTP response, Paywint will automatically retry delivery up to two more times, for a total of three attempts per event.
  • Retries are sent within a predefined timeframe.
  • If all three attempts fail, Paywint will notify your email with details of the failed event.
Note: To avoid missed events, ensure your webhook endpoint is highly available and returns 200 OK quickly. Any internal processing should happen asynchronously to avoid missed events.

​
Detailed Webhook Responses

For complete webhook payload examples and detailed field descriptions for each event type, see our Webhook Responses documentation page.

Webhook Responses

View detailed webhook payload examples, field descriptions, and implementation guidance for all payment events.