Skip to main content

​
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

Use the Sandbox environment to test your webhook setup before moving to production.
  1. Create a Sandbox Account:
    Sign up for a Sandbox Account to start testing your integration.
  2. Get API Key:
    Go to the Developer Panel → API Key section to generate your Sandbox API key.
  3. Configure Webhook URLs:
    In the Developer Panel → Redirect/Webhook section, you’ll find fields to enter your test endpoint:
    • Webhook URL:
      The endpoint that receives specific event webhooks for payment status updates (e.g., payment.success, payment.failed).
      Example: https://example.com/webhook

​
Production

Once your Sandbox testing is complete, you can move to the Production environment. Before enabling your Production setup, please contact our support team to ensure your API and webhook configurations are properly activated.
  1. Create a Production Account:
    Sign up for a Production Account.
  2. Enable Production Access:
    Contact our support team to request activation of your Production API and webhook setup.
  3. Get API Key:
    Go to the Developer Panel → API Keys section to obtain your Production API key.
  4. Configure Webhook URLs: In the Developer Panel → Redirect/Webhook section, enter your live endpoint:
  • Webhook URL:
    The live endpoint that receives real-time payment event webhooks.
    Example: https://yourapp.com/webhook
  1. Support Contacts:
    If you need assistance during setup:

​
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.