Security & Best Practices

Follow these best practices to ensure your payment integration is secure and reliable.

Essential Security Practices

Always verify webhooks

Verify the signature on every webhook to ensure it’s from Payviox and hasn’t been tampered with.

Use HTTPS

Always use HTTPS for your webhook endpoint to ensure data is encrypted in transit.

Handle idempotency

Be prepared to receive the same webhook multiple times. Use order_id and session_id to prevent duplicate processing.

Respond quickly

Return 200 OK within 30 seconds. Process webhooks asynchronously if needed.

Webhook Security

Critical: Never process webhooks without verifying the signature. This protects against malicious actors sending fake payment notifications.

Signature Verification

Always verify webhook signatures using HMAC SHA256:

// PHP example
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_SIGNATURE'];
$webhookToken = 'your_webhook_token';

$computed = hash_hmac('sha256', $payload, $webhookToken);

if (!hash_equals($computed, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

Use Timing-Safe Comparison

Always use timing-safe comparison functions:

PHP: hash_equals()
Node.js: crypto.timingSafeEqual()
Python: hmac.compare_digest()

This prevents timing attacks.

Idempotency Handling

Webhooks may be delivered more than once. Implement idempotency checks:

// Check if already processed
$sessionId = $data['metadata']['integration_session_id'];
$orderId = $data['order_id'];

$existingPayment = Payment::where('session_id', $sessionId)
                          ->where('order_id', $orderId)
                          ->first();

if ($existingPayment && $existingPayment->status === 'completed') {
    // Already processed - skip
    return response()->json(['status' => 'already_processed'], 200);
}

// Process the payment
// ...

Asynchronous Processing

For optimal performance, process webhooks asynchronously:

// Laravel example with queued job
public function handleWebhook(Request $request) {
    // Verify signature...
    
    // Dispatch to queue
    ProcessWebhook::dispatch($data);
    
    // Immediately return 200 OK
    return response()->json(['status' => 'queued'], 200);
}

Responding quickly prevents webhook timeout and retry attempts.

API Token Security

Use environment variables

Never hardcode API tokens in your code:

// ✅ Good
const payviox = new Payviox(process.env.PAYVIOX_API_TOKEN);

// ❌ Bad
const payviox = new Payviox('pk_live_xxxxxxxxxxxxx');

Separate test and production tokens

Use different tokens for different environments:

const PAYVIOX_TOKEN = process.env.NODE_ENV === 'production'
  ? process.env.PAYVIOX_LIVE_TOKEN
  : process.env.PAYVIOX_TEST_TOKEN;

Rotate tokens regularly

Change your API tokens periodically and immediately if compromised.

Never expose your secret key client-side

Your secret key (sk_) must stay on your server — never in frontend code, a mobile bundle, or a public repository.Your public key (pk_) is different: it is designed to be used from the browser and is what the JavaScript SDK expects. Shipping it in your client-side bundle is expected and safe.

Error Handling

Implement proper error handling in your integration:

async function initiatePayment() {
  try {
    await payviox.createSession({
      amount: 1000,
      currency: 'USD',
      // ... other params
    }, {
      redirect: true
    });
  } catch (error) {
    // Log error for debugging
    console.error('Payment error:', error);
    
    // Show user-friendly message
    if (error.status === 401) {
      alert('Configuration error. Please contact support.');
    } else if (error.status === 400) {
      alert('Invalid payment details. Please check and try again.');
    } else {
      alert('Payment failed. Please try again later.');
    }
  }
}

Logging and Monitoring

Log all webhooks

Keep detailed logs of all webhook events with timestamps for debugging and audit trails.

Monitor success rates

Track payment success and failure rates to identify issues early.

Set up alerts

Configure alerts for high failure rates or webhook delivery issues.

Review dashboard regularly

Check your Payviox dashboard for payment trends and anomalies.

Testing Checklist

Production Checklist

Common Issues and Solutions

Webhook not receiving notifications

Possible causes:

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

Solution:

Verify webhook URL in dashboard
Check server logs for errors
Ensure endpoint returns 200 OK quickly

Signature verification failing

Possible causes:

Using wrong webhook token
Modifying request body before verification
Incorrect HMAC algorithm

Solution:

Verify webhook token from dashboard
Always verify against raw request body
Use HMAC SHA256 algorithm

Duplicate order processing

Possible causes:

Not implementing idempotency checks
Slow response times causing retries

Solution:

Implement idempotency using session_id and order_id
Return 200 OK immediately
Process asynchronously if needed

Payment session creation fails

Possible causes:

Invalid API token
Missing required fields
Invalid payment method ID

Solution:

Verify API token is correct
Check all required fields are provided
Ensure payment method exists and is active

Need Help?

Documentation

Browse our complete documentation

Support

Email us at support@payviox.com

Dashboard

dash.payviox.com