> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywint.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Learn how to receive and handle Paywint webhook events.

## 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](https://sandbox.app.paywint.com) to start testing your integration.

2. **Get API Key:**\
   Go to the [Developer Panel → API Key](https://sandbox.app.paywint.com/app/developer-panel/api-credentials) section to generate your Sandbox API key.

3. **Configure Webhook URLs:**\
   In the [Developer Panel → Redirect/Webhook](https://sandbox.app.paywint.com/app/developer-panel/urls) 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](https://paywint.com/contact) to ensure your API and webhook configurations are properly activated.

1. **Create a Production Account:**\
   Sign up for a [Production Account](https://app.paywint.com).

2. **Enable Production Access:**\
   Contact our [support team](https://paywint.com/contact) to request activation of your Production API and webhook setup.

3. **Get API Key:**\
   Go to the [Developer Panel → API Keys](https://app.paywint.com/app/developer-panel/api-credentials) section to obtain your Production API key.

4. **Configure Webhook URLs:**
   In the [Developer Panel → Redirect/Webhook](https://app.paywint.com/app/developer-panel/urls) section, enter your live endpoint:

* **Webhook URL:**\
  The live endpoint that receives real-time payment event webhooks.\
  Example: `https://yourapp.com/webhook`

5. **Support Contacts:**\
   If you need assistance during setup:

* **Email:** [support@paywint.com](mailto:support@paywint.com)
* **Phone:** [+1 (408) 461-5543](tel:+14084615543)
* **Live Chat:** Available via the Paywint Dashboard

***

## Webhook Events

Below is the list of webhook events sent by Paywint.

| Event Name           | Description                              |
| -------------------- | ---------------------------------------- |
| `payment.initiated`  | Payment was initiated.                   |
| `payment.processing` | Payment is being processed.              |
| `payment.success`    | Payment was successful.                  |
| `payment.failed`     | Payment failed.                          |
| `payment.rejected`   | Payment was rejected.                    |
| `payment.retried`    | Payment was retried with new payment ID. |
| `payment.opened`     | Payment link was opened by the user.     |
| `payment.expired`    | Payment link has been expired.           |

***

## Basic Structure

| Field                | Description                                                |
| -------------------- | ---------------------------------------------------------- |
| `event`              | The type of event that occurred (e.g., `payment.success`). |
| `id`                 | A unique identifier for this webhook delivery.             |
| `data`               | The event-specific payload object.                         |
| `eventGeneratedTime` | UNIX timestamp (in seconds) when the event was generated.  |

Example payload:

```json theme={null}
{
  "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](/webhook-response) documentation page.

<Card title="Webhook Responses" icon="code" href="/webhook-response">
  View detailed webhook payload examples, field descriptions, and implementation guidance for all payment events.
</Card>