Understanding Webhooks

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

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.

How Webhooks Work

Configure your webhook URL

Set up your webhook endpoint URL in the Payviox Dashboard

Payviox sends a POST request

When payment events occur, Payviox sends a POST request to your configured URL

Your server receives the notification

Your server endpoint receives the webhook with complete payment details

Verify the signature

Always verify the webhook signature to ensure it’s from Payviox and hasn’t been tampered with

Process the payment

Fulfill the order, send confirmation emails, update your database, etc.

Return 200 OK

Respond with HTTP 200 status to acknowledge receipt of the webhook

Webhook Payload Example

{
  "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"
  }
}

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.

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.

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`

Important: If you receive pending_review, do NOT ship or fulfill the order until you receive either succeeded or declined.

What Happens During Payment?

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.

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

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

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

Next Steps

Webhook Integration Guide

Complete webhook implementation guide

Code Examples

See webhook handler examples

Best Practices

Security and best practices

Dashboard

Configure your webhook URL