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

# Understanding Webhooks

> Learn how webhooks work for payment notifications

## Understanding Webhooks

Webhooks are **essential** for confirming payments. They provide real-time notifications when payment events occur.

<Warning>
  **Important:** Always use webhooks to confirm payments. Don't rely solely on customer redirects, as customers may close their browser before returning to your site.
</Warning>

## How Webhooks Work

<Steps>
  <Step title="Configure your webhook URL">
    Set up your webhook endpoint URL in the [Payviox Dashboard](https://dash.payviox.com)
  </Step>

  <Step title="Payviox sends a POST request">
    When payment events occur, Payviox sends a POST request to your configured URL
  </Step>

  <Step title="Your server receives the notification">
    Your server endpoint receives the webhook with complete payment details
  </Step>

  <Step title="Verify the signature">
    Always verify the webhook signature to ensure it's from Payviox and hasn't been tampered with
  </Step>

  <Step title="Process the payment">
    Fulfill the order, send confirmation emails, update your database, etc.
  </Step>

  <Step title="Return 200 OK">
    Respond with HTTP 200 status to acknowledge receipt of the webhook
  </Step>
</Steps>

## Webhook Payload Example

```json theme={null}
{
  "amount": 10000,
  "currency": "USD",
  "fees": 350,
  "metadata": {
    "integration_session_id": "sess_abc123xyz"
  },
  "type": "succeeded",
  "provider": "stripe",
  "order_id": "order_123456",
  "items": [
    {
      "name": "Premium Subscription",
      "quantity": 1,
      "price": 10000
    }
  ],
  "payment_method": "card",
  "customer": {
    "name": "John Doe",
    "email": "john@example.com"
  }
}
```

<Tip>
  The `type` field indicates the payment event type: `succeeded`, `pending_review`, `declined`, `refunded`, `expired`, `incomplete`. The `fees` field indicates total fees in the smallest currency unit - customer pays `amount + fees = total`. On `incomplete` events, an `amount_remaining` field indicates how much is still due.
</Tip>

<Info>
  The `customer` field is optional and only present when customer data was collected during payment. It may include `name`, `email`, `phone`, and `address` depending on the payment provider.
</Info>

## Webhook Event Types

Payviox sends different webhook events based on the payment lifecycle:

| Event            | Description                                                           | Action Required                         |
| ---------------- | --------------------------------------------------------------------- | --------------------------------------- |
| `succeeded`      | Payment completed successfully                                        | ✅ Fulfill order                         |
| `pending_review` | Payment flagged for fraud review                                      | ⏳ Wait for final decision               |
| `declined`       | Payment declined by fraud prevention (auto-refunded)                  | ❌ Do NOT fulfill                        |
| `refunded`       | Refund processed for a transaction                                    | 📦 Handle return/cancellation           |
| `expired`        | Payment session expired without completion                            | 🕐 Clean up pending order               |
| `incomplete`     | Crypto payment underpaid — includes `amount_remaining` (opt-in event) | ⏳ Do NOT fulfill — wait for `succeeded` |

<Warning>
  **Important:** If you receive `pending_review`, do NOT ship or fulfill the order until you receive either `succeeded` or `declined`.
</Warning>

## What Happens During Payment?

<AccordionGroup>
  <Accordion title="1. Session Creation (Your Application)">
    Your application creates a payment session by calling Payviox with:

    * **Amount** (in smallest currency unit, e.g., cents)
    * **Currency** (USD, EUR, GBP, etc.)
    * **Order details** (customer ID, order ID, items)
    * **Payment method** (card, crypto, bank transfer, etc.)

    Payviox returns a session ID and secure payment URL.
  </Accordion>

  <Accordion title="2. Payment Processing (Payviox)">
    The customer is redirected to Payviox's secure payment page where:

    * Payment form is displayed with selected payment method
    * Customer enters payment details
    * Payment is processed through the appropriate provider (Stripe, PayPal, etc.)
    * Transaction is encrypted and secured
  </Accordion>

  <Accordion title="3. Webhook Notification (Payviox → Your Server)">
    Immediately after payment processing:

    * Payviox sends a webhook POST request to your configured URL
    * Includes payment status, amount, order ID, and all details
    * **This is your source of truth** for payment confirmation
    * Retries automatically if your server doesn't respond
  </Accordion>

  <Accordion title="4. Customer Redirect (Back to Your Site)">
    After payment:

    * Customer is redirected back to your website
    * URL includes session ID as parameter
    * You can show a confirmation page
    * **Note:** Always rely on webhooks, not just redirects
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Webhook Integration Guide" icon="webhook" href="/webhooks/integration">
    Complete webhook implementation guide
  </Card>

  <Card title="Code Examples" icon="file-code" href="/quickstart/examples">
    See webhook handler examples
  </Card>

  <Card title="Best Practices" icon="shield-check" href="/quickstart/best-practices">
    Security and best practices
  </Card>

  <Card title="Dashboard" icon="gauge" href="https://dash.payviox.com">
    Configure your webhook URL
  </Card>
</CardGroup>