Versioning

September 15, 2025 - v1.1.0

Enhanced authentication security and webhook notification support

Feature Release

Enhanced security features and webhook notifications

Overview

This release introduces webhook support for real-time event notifications and enhanced authentication security features. No breaking changes from v1.0.0.

New Features

1. Webhook Notification System

AdditionImpact: Medium

What's New

Real-time webhook notifications for payment events:

Supported Events:

order.created - New order created
order.completed - Payment received and confirmed
order.failed - Payment failed
order.cancelled - Order cancelled by merchant
refund.processed - Refund completed
payout.completed - Payout successfully transferred

Webhook Payload Format:

{
  "event": "order.completed",
  "timestamp": "2025-09-15T14:30:00Z",
  "data": {
    "order_id": "ord_abc123xyz",
    "amount": 100.00,
    "currency": "USD",
    "status": "completed"
  }
}

Impact of Feature

Eliminates the need for constant polling
Real-time payment status updates
Reduces API call volume
Enables instant customer notifications
Supports automated workflow triggers

Breaking Changes

None - This is an optional feature. Existing integrations continue to work.

Implementation Reference

→ Documentation coming soon at /api-reference/webhooks

2. HMAC Signature Verification

AdditionImpact: High

What's New

Optional HMAC-SHA256 signature verification for webhook security:

New Webhook Header:

X-DVPay-Signature: HMAC signature of request body

Verification Algorithm:

HMAC-SHA256(webhook_secret, request_body)

Impact of Feature

Prevents webhook spoofing attacks
Ensures webhook authenticity
Protects against man-in-the-middle attacks
Industry-standard security practice

What Might Cause Breaking Changes

If you enable signature verification, you must verify all incoming webhooks
Unverified webhooks should be rejected
Requires webhook secret management in your application

Migration Steps:

Retrieve webhook secret from the merchant dashboard
Store webhook secret securely (environment variable)
Implement HMAC verification in the webhook handler
Enable signature verification in dashboard settings

Implementation Reference

→ Documentation coming soon at /api-reference/webhooks#security

3. IP Whitelist Configuration

AdditionImpact: Medium

What's New

Configure IP whitelist for enhanced API security:

Features:

Add up to 10 IP addresses or CIDR ranges
Requests from non-whitelisted IPs are rejected
Configure via the merchant dashboard
Separate whitelists for API calls and webhooks

Impact of Feature

Additional layer of security
Prevents unauthorized API access
Protects against stolen API keys
Compliance with security requirements

What Might Cause Breaking Changes

Once enabled, requests from non-whitelisted IPs will be rejected with 403 Forbidden
Must add all server IPs before enabling
Dynamic IPs are not recommended

Implementation Reference

→ Configure in the merchant dashboard under Security Settings

Modifications

1. Enhanced Error Response Format

ModificationImpact: Low

What's New

Improved error response format with additional context:

Previous Format:

{
  "error": "Invalid request"
}

New Format:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid request",
    "field": "amount",
    "details": "Amount must be greater than 0"
  }
}

Impact of Modification

More actionable error messages
Easier debugging for developers
Field-level error identification
Consistent error codes across all endpoints

What Might Cause Breaking Changes

Error response structure changed from string to object
If you parse error as a string, update to error.message
Error checking logic may need updates

Migration Example:

Before:

if (response.error) {
  console.log(response.error);
}

After:

if (response.error) {
  console.log(response.error.message);
  console.log('Field:', response.error.field);
  console.log('Code:', response.error.code);
}