Webhook Integration - Payviox Documentation

Overview

Webhooks allow Payviox to send real-time notifications to your server when payment events occur. When a payment is processed, Payviox sends an HTTP POST request to your configured webhook URL with the payment details.

Webhooks are essential for keeping your application synchronized with payment statuses. Configure your webhook URL in the Payviox Dashboard under Settings > Webhooks.

Webhook Configuration

Setting Up Your Webhook URL

Configure Your Endpoint

Create an endpoint on your server to receive POST requests (e.g., https://yourdomain.com/api/webhook)

Add URL to Dashboard

Go to your Payviox Dashboard and navigate to Settings > Webhooks

Enter Your Webhook URL

Paste your endpoint URL in the webhook URL field

Save Your Webhook Token

Copy your webhook token - you’ll need it to verify webhook signatures

Select Webhook Events

Choose which events you want to receive. By default, only succeeded is enabled.

Available Events

You can subscribe to the following webhook events:

Event	Description	Recommended
`succeeded`	Payment completed successfully	✅ Always enable
`pending_review`	Payment flagged for fraud review	✅ If using fraud detection
`declined`	Payment declined by fraud prevention	✅ If using fraud detection
`refunded`	Refund processed	✅ If you process refunds
`expired`	Payment session expired without completion	⚪ Optional
`incomplete`	Crypto payment underpaid — customer sent less than requested	⚪ Optional (crypto only)

Always verify webhook signatures to ensure requests are coming from Payviox and not from malicious actors.

Webhook Payload Structure

Payviox sends webhooks with the following structure:

{
  "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",
    "phone": "+1234567890",
    "address": {
      "line1": "123 Main St",
      "city": "Paris",
      "postal_code": "75001",
      "country": "FR"
    }
  }
}

Payload Fields

integer

required

The payment amount in the smallest currency unit (e.g., cents for USD)

string

required

Three-letter ISO currency code (e.g., USD, EUR, GBP)

integer

Total fees amount in the smallest currency unit (e.g., cents for USD). The customer pays amount + fees = total. This field is present when fees have been calculated for the transaction.

object

required

Custom metadata associated with the payment session

Show metadata properties

string

The unique session identifier from Payviox

string

required

The payment event type. Possible values:

succeeded: Payment completed successfully. You can fulfill the order.
pending_review: Payment flagged for fraud review. Do NOT ship until you receive succeeded or declined.
declined: Payment declined by fraud prevention. Customer has been automatically refunded.
refunded: A refund has been processed for this transaction.
expired: Payment session expired without completion.
incomplete: A crypto payment came in short (less than the requested amount). Opt-in event. Includes amount_remaining (how much is still due). Do NOT fulfill until you receive succeeded.

string

required

The payment provider used (e.g., stripe, paypal, crypto)

string

required

Your unique order identifier

array

required

Array of items purchased

Show item properties

string

Item name

integer

Quantity purchased

integer

Item price in smallest currency unit

string

Specific payment method used (e.g., card, bank_transfer)

object

Optional. Customer information if available from the payment provider. This field is only present when customer data was collected during payment.

Show customer properties

string

Optional. Customer’s full name

string

Optional. Customer’s email address

string

Optional. Customer’s phone number

object

Optional. Customer’s billing address

Show address properties

string

Optional. Street address line 1

string

Optional. Street address line 2

string

Optional. City

string

Optional. State/Province

string

Optional. Postal/ZIP code

string

Optional. Two-letter country code (ISO 3166-1 alpha-2)

integer

Only present on incomplete events. The amount still due, in the smallest currency unit (e.g., cents for USD) — how much more the customer must send to complete the payment. The amount already received equals amount - amount_remaining.

Event Types

Payviox sends different webhook events based on the payment lifecycle. Here’s what each event means and how to handle it:

`succeeded` - Payment Successful

✅ Payment Successful

The payment has been validated by the payment processor. You can safely fulfill the order.Typical flow:

Customer completes payment
Payment processor confirms the charge
You receive succeeded webhook
Ship the order / provide the service

`pending_review` - Fraud Review Required

⚠️ Pending Review

The payment has been flagged by our fraud detection system for manual review. Do NOT ship until you receive a final decision.Typical flow:

Customer completes payment
Fraud detection flags the transaction
You receive pending_review webhook
Admin reviews the transaction
You receive either succeeded or declined webhook

Never fulfill orders that are in pending_review status. Wait for the final succeeded or declined webhook.

`declined` - Fraud Declined

❌ Declined (Fraud)

The payment was automatically declined by the fraud prevention system. The customer has been automatically refunded.Typical flow:

Customer completes payment
Fraud score exceeds threshold
Automatic refund is issued
You receive declined webhook
Do NOT ship the order

`refunded` - Payment Refunded

↩️ Refunded

A refund has been processed for this transaction.Typical flow:

Original payment was successful
Refund is requested (by you or the customer)
Refund is processed
You receive refunded webhook

`expired` - Session Expired

⏰ Expired

The payment session expired before the customer completed payment.Typical flow:

Payment session is created
Customer does not complete payment within the session lifetime
Session expires automatically
You receive expired webhook

`incomplete` - Crypto Payment Underpaid

⚠️ Incomplete

A crypto payment came in short — the customer sent less than the requested amount. This is an opt-in event (enable it in your webhook settings), and only applies to crypto payments.The payload includes amount_remaining (how much is still due, in the smallest currency unit). The amount already received equals amount - amount_remaining.Typical flow:

Customer pays a crypto invoice but sends less than the requested amount
You receive incomplete (with amount_remaining)
Customer sends the remaining amount to the same address
You receive succeeded

Do NOT fulfill the order until you receive succeeded.

Webhook Headers

Every webhook request includes these headers:

Header	Description
`Content-Type`	Always `application/json`
`Signature`	HMAC SHA256 signature for verification

Signature Verification

Critical Security Step: Always verify the webhook signature before processing the payload. This ensures the request is legitimate and from Payviox.

The Signature header contains an HMAC SHA256 hash of the request body, signed with your webhook token. Here’s how to verify it:

Verification Algorithm

Get the raw request body (JSON string)
Compute HMAC SHA256 hash using your webhook token as the secret key
Compare the computed signature with the Signature header
Only process the webhook if signatures match

Implementation Examples

<?php

function verifyWebhookSignature($payload, $receivedSignature, $webhookToken) {
    // Compute the expected signature
    $computedSignature = hash_hmac('sha256', $payload, $webhookToken);
    
    // Use hash_equals to prevent timing attacks
    return hash_equals($computedSignature, $receivedSignature);
}

// Example usage in a Laravel controller
public function handleWebhook(Request $request) {
    // Get the raw payload
    $payload = $request->getContent();
    
    // Get the signature from headers
    $receivedSignature = $request->header('Signature');
    
    // Your webhook token from the dashboard
    $webhookToken = env('PAYVIOX_WEBHOOK_TOKEN');
    
    // Verify the signature
    if (!verifyWebhookSignature($payload, $receivedSignature, $webhookToken)) {
        // Invalid signature - reject the request
        return response()->json(['error' => 'Invalid signature'], 401);
    }
    
    // Parse the verified payload
    $data = json_decode($payload, true);
    
    // Process the webhook based on type
    switch ($data['type']) {
        case 'succeeded':
            // Payment succeeded - fulfill the order
            $this->fulfillOrder($data['order_id'], $data);
            break;
            
        case 'pending_review':
            // Payment flagged for fraud review - DO NOT ship yet
            $this->updateOrderStatus($data['order_id'], 'pending_review');
            break;
            
        case 'declined':
            // Payment declined by fraud prevention - customer refunded
            $this->handleDeclinedPayment($data['order_id']);
            break;
            
        case 'refunded':
            // Payment was refunded
            $this->handleRefund($data['order_id'], $data);
            break;
    }
    
    // Return 200 OK to acknowledge receipt
    return response()->json(['status' => 'success'], 200);
}

private function fulfillOrder($orderId, $webhookData) {
    // Your order fulfillment logic
    $order = Order::where('order_id', $orderId)->first();
    
    if ($order) {
        $order->status = 'completed';
        $order->payment_provider = $webhookData['provider'];
        $order->payment_amount = $webhookData['amount'];
        $order->session_id = $webhookData['metadata']['integration_session_id'];
        $order->save();
        
        // Send confirmation email, provision services, etc.
    }
}

const crypto = require('crypto');
const express = require('express');

function verifyWebhookSignature(payload, receivedSignature, webhookToken) {
    // Compute the expected signature
    const computedSignature = crypto
        .createHmac('sha256', webhookToken)
        .update(payload)
        .digest('hex');
    
    // Use timingSafeEqual to prevent timing attacks
    return crypto.timingSafeEqual(
        Buffer.from(computedSignature),
        Buffer.from(receivedSignature)
    );
}

const app = express();

// Important: Use express.raw() to get the raw body for signature verification
app.post('/api/webhook', express.raw({ type: 'application/json' }), (req, res) => {
    // Get the raw payload as string
    const payload = req.body.toString('utf8');
    
    // Get the signature from headers
    const receivedSignature = req.headers['signature'];
    
    // Your webhook token from environment variable
    const webhookToken = process.env.PAYVIOX_WEBHOOK_TOKEN;
    
    // Verify the signature
    if (!verifyWebhookSignature(payload, receivedSignature, webhookToken)) {
        return res.status(401).json({ error: 'Invalid signature' });
    }
    
    // Parse the verified payload
    const data = JSON.parse(payload);
    
    // Process the webhook based on type
    switch (data.type) {
        case 'succeeded':
            fulfillOrder(data.order_id, data);
            break;
            
        case 'pending_review':
            // Payment flagged for fraud review - DO NOT ship yet
            updateOrderStatus(data.order_id, 'pending_review');
            break;
            
        case 'declined':
            // Payment declined by fraud prevention - customer refunded
            handleDeclinedPayment(data.order_id);
            break;
            
        case 'refunded':
            handleRefund(data.order_id, data);
            break;
    }
    
    // Return 200 OK to acknowledge receipt
    res.json({ status: 'success' });
});

async function fulfillOrder(orderId, webhookData) {
    // Your order fulfillment logic
    const order = await Order.findOne({ order_id: orderId });
    
    if (order) {
        order.status = 'completed';
        order.payment_provider = webhookData.provider;
        order.payment_amount = webhookData.amount;
        order.session_id = webhookData.metadata.integration_session_id;
        await order.save();
        
        // Send confirmation email, provision services, etc.
    }
}

app.listen(3000, () => {
    console.log('Webhook server listening on port 3000');
});

import hmac
import hashlib
import json
from flask import Flask, request, jsonify

app = Flask(__name__)

def verify_webhook_signature(payload, received_signature, webhook_token):
    """Verify the webhook signature"""
    # Compute the expected signature
    computed_signature = hmac.new(
        webhook_token.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    # Use compare_digest to prevent timing attacks
    return hmac.compare_digest(computed_signature, received_signature)

@app.route('/api/webhook', methods=['POST'])
def handle_webhook():
    # Get the raw payload
    payload = request.get_data(as_text=True)
    
    # Get the signature from headers
    received_signature = request.headers.get('Signature')
    
    # Your webhook token from environment variable
    webhook_token = os.environ.get('PAYVIOX_WEBHOOK_TOKEN')
    
    # Verify the signature
    if not verify_webhook_signature(payload, received_signature, webhook_token):
        return jsonify({'error': 'Invalid signature'}), 401
    
    # Parse the verified payload
    data = json.loads(payload)
    
    # Process the webhook based on type
    if data['type'] == 'succeeded':
        fulfill_order(data['order_id'], data)
    elif data['type'] == 'pending_review':
        # Payment flagged for fraud review - DO NOT ship yet
        update_order_status(data['order_id'], 'pending_review')
    elif data['type'] == 'declined':
        # Payment declined by fraud prevention - customer refunded
        handle_declined_payment(data['order_id'])
    elif data['type'] == 'refunded':
        handle_refund(data['order_id'], data)
    
    # Return 200 OK to acknowledge receipt
    return jsonify({'status': 'success'}), 200

def fulfill_order(order_id, webhook_data):
    """Handle successful payment"""
    # Your order fulfillment logic
    order = Order.query.filter_by(order_id=order_id).first()
    
    if order:
        order.status = 'completed'
        order.payment_provider = webhook_data['provider']
        order.payment_amount = webhook_data['amount']
        order.session_id = webhook_data['metadata']['integration_session_id']
        db.session.commit()
        
        # Send confirmation email, provision services, etc.

if __name__ == '__main__':
    app.run(port=3000)

require 'sinatra'
require 'json'
require 'openssl'

def verify_webhook_signature(payload, received_signature, webhook_token)
  # Compute the expected signature
  computed_signature = OpenSSL::HMAC.hexdigest(
    OpenSSL::Digest.new('sha256'),
    webhook_token,
    payload
  )
  
  # Use secure_compare to prevent timing attacks
  Rack::Utils.secure_compare(computed_signature, received_signature)
end

post '/api/webhook' do
  # Get the raw payload
  request.body.rewind
  payload = request.body.read
  
  # Get the signature from headers
  received_signature = request.env['HTTP_SIGNATURE']
  
  # Your webhook token from environment variable
  webhook_token = ENV['PAYVIOX_WEBHOOK_TOKEN']
  
  # Verify the signature
  unless verify_webhook_signature(payload, received_signature, webhook_token)
    halt 401, { error: 'Invalid signature' }.to_json
  end
  
  # Parse the verified payload
  data = JSON.parse(payload)
  
  # Process the webhook based on type
  case data['type']
  when 'succeeded'
    fulfill_order(data['order_id'], data)
  when 'pending_review'
    # Payment flagged for fraud review - DO NOT ship yet
    update_order_status(data['order_id'], 'pending_review')
  when 'declined'
    # Payment declined by fraud prevention - customer refunded
    handle_declined_payment(data['order_id'])
  when 'refunded'
    handle_refund(data['order_id'], data)
  end
  
  # Return 200 OK to acknowledge receipt
  content_type :json
  { status: 'success' }.to_json
end

def fulfill_order(order_id, webhook_data)
  # Your order fulfillment logic
  order = Order.find_by(order_id: order_id)
  
  if order
    order.status = 'completed'
    order.payment_provider = webhook_data['provider']
    order.payment_amount = webhook_data['amount']
    order.session_id = webhook_data['metadata']['integration_session_id']
    order.save
    
    # Send confirmation email, provision services, etc.
  end
end

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "io"
    "log"
    "net/http"
    "os"
)

type WebhookPayload struct {
    Amount        int                    `json:"amount"`
    Currency      string                 `json:"currency"`
    Metadata      map[string]interface{} `json:"metadata"`
    Type          string                 `json:"type"`
    Provider      string                 `json:"provider"`
    OrderID       string                 `json:"order_id"`
    Items         []Item                 `json:"items"`
    PaymentMethod string                 `json:"payment_method"`
}

type Item struct {
    Name     string `json:"name"`
    Quantity int    `json:"quantity"`
    Price    int    `json:"price"`
}

func verifyWebhookSignature(payload string, receivedSignature string, webhookToken string) bool {
    // Compute the expected signature
    mac := hmac.New(sha256.New, []byte(webhookToken))
    mac.Write([]byte(payload))
    computedSignature := hex.EncodeToString(mac.Sum(nil))
    
    // Use hmac.Equal to prevent timing attacks
    return hmac.Equal([]byte(computedSignature), []byte(receivedSignature))
}

func handleWebhook(w http.ResponseWriter, r *http.Request) {
    // Get the raw payload
    body, err := io.ReadAll(r.Body)
    if err != nil {
        http.Error(w, "Error reading request body", http.StatusBadRequest)
        return
    }
    payload := string(body)
    
    // Get the signature from headers
    receivedSignature := r.Header.Get("Signature")
    
    // Your webhook token from environment variable
    webhookToken := os.Getenv("PAYVIOX_WEBHOOK_TOKEN")
    
    // Verify the signature
    if !verifyWebhookSignature(payload, receivedSignature, webhookToken) {
        http.Error(w, `{"error": "Invalid signature"}`, http.StatusUnauthorized)
        return
    }
    
    // Parse the verified payload
    var data WebhookPayload
    if err := json.Unmarshal(body, &data); err != nil {
        http.Error(w, "Error parsing JSON", http.StatusBadRequest)
        return
    }
    
    // Process the webhook based on type
    switch data.Type {
    case "succeeded":
        fulfillOrder(data.OrderID, data)
    case "pending_review":
        // Payment flagged for fraud review - DO NOT ship yet
        updateOrderStatus(data.OrderID, "pending_review")
    case "declined":
        // Payment declined by fraud prevention - customer refunded
        handleDeclinedPayment(data.OrderID)
    case "refunded":
        handleRefund(data.OrderID, data)
    }
    
    // Return 200 OK to acknowledge receipt
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(map[string]string{"status": "success"})
}

func fulfillOrder(orderID string, webhookData WebhookPayload) {
    // Your order fulfillment logic
    log.Printf("Fulfilling order %s", orderID)
    // Update database, send emails, provision services, etc.
}

func main() {
    http.HandleFunc("/api/webhook", handleWebhook)
    log.Println("Webhook server listening on port 3000")
    log.Fatal(http.ListenAndServe(":3000", nil))
}

Retry Logic

Payviox implements an automatic retry mechanism for failed webhook deliveries:

First Attempt

Instant delivery (0 seconds)

Second Attempt

30 seconds after first failure

Third Attempt

5 minutes after second failure

Fourth Attempt

30 minutes after third failure

After 4 failed attempts, the webhook will be marked as failed. You can manually retry failed webhooks from the Payviox Dashboard.

Success Criteria

A webhook is considered successfully delivered when your endpoint:

Returns HTTP status code 200
Responds within 30 seconds

Troubleshooting

Common Issues

Signature Verification Failing

Possible causes:

Using the wrong webhook token
Parsing/modifying the request body before verification
Incorrect HMAC algorithm (must be SHA256)

Solution: Always verify against the raw request body, before any parsing or modifications.

Webhooks Not Being Received

Possible causes:

Incorrect webhook URL in dashboard
Firewall blocking Payviox IP addresses
Server not responding within 30 seconds

Solution: Check your webhook URL configuration and server logs.

Duplicate Webhook Processing

Possible causes:

Not implementing idempotency checks
Slow response times causing retries

Solution: Implement idempotency using session_id and order_id, and respond quickly with 200 OK.

Webhook Timeout

Possible causes:

Processing taking too long before responding
Database locks or slow queries

Solution: Return 200 OK immediately and process webhooks asynchronously in a queue.

Security Checklist

Need Help?

If you’re having trouble with webhook integration:

Check the Webhook Logs in your dashboard
Review your server logs for errors
Contact support@payviox.com for assistance

Include your webhook attempt IDs from the dashboard when contacting support for faster resolution.

​Overview

​Webhook Configuration

​Setting Up Your Webhook URL

​Available Events

​Webhook Payload Structure

​Payload Fields

​Event Types

​succeeded - Payment Successful

✅ Payment Successful

​pending_review - Fraud Review Required

⚠️ Pending Review

​declined - Fraud Declined

❌ Declined (Fraud)

​refunded - Payment Refunded

↩️ Refunded

​expired - Session Expired

⏰ Expired

​incomplete - Crypto Payment Underpaid

⚠️ Incomplete

​Webhook Headers

​Signature Verification

​Verification Algorithm

​Implementation Examples

​Retry Logic

​Success Criteria

​Troubleshooting

​Common Issues

​Security Checklist

​Need Help?

Overview

Webhook Configuration

Setting Up Your Webhook URL

Available Events

Webhook Payload Structure

Payload Fields

Event Types

`succeeded` - Payment Successful

`pending_review` - Fraud Review Required

`declined` - Fraud Declined

`refunded` - Payment Refunded

`expired` - Session Expired

`incomplete` - Crypto Payment Underpaid

Webhook Headers

Signature Verification

Verification Algorithm

Implementation Examples

Retry Logic

Success Criteria

Troubleshooting

Common Issues

Security Checklist

Need Help?