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

The type field indicates the payment status: succeeded, processing, canceled, requires_action, etc.

Payment States

A payment can be in one of several states during its lifecycle:

State	Description	Action Required
`succeeded`	Payment completed successfully	Fulfill order
`processing`	Payment is being processed	Wait for final status
`canceled`	Payment was canceled	Cancel order
`requires_action`	Customer action needed	Notify customer
`requires_payment_method`	Payment method required	Request new method
`requires_confirmation`	Confirmation needed	Confirm payment

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

Quickstart