Essentials

Webhook Configuration

Set up and handle real-time payment notifications from DVPay

Webhooks enable your application to receive real-time notifications about payment events. DVPay sends HTTP POST requests to your configured webhook endpoint whenever specific events occur.

Setup Your Webhook

Step 1: Create an Endpoint

Create a publicly accessible HTTPS endpoint in your application to receive webhook events.

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

type WebhookPayload struct {
    Event     string  `json:"event"`
    OrderID   string  `json:"order_id"`
    Amount    float64 `json:"amount"`
    Currency  string  `json:"currency"`
    Status    string  `json:"status"`
    Timestamp int64   `json:"timestamp"`
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    // Read the request body
    body, err := io.ReadAll(r.Body)
    if err != nil {
        http.Error(w, "Failed to read request body", http.StatusBadRequest)
        return
    }
    defer r.Body.Close()

    // Parse webhook payload
    var payload WebhookPayload
    if err := json.Unmarshal(body, &payload); err != nil {
        http.Error(w, "Invalid JSON", http.StatusBadRequest)
        return
    }

    // Process the webhook event
    switch payload.Event {
    case "payment.success":
        fmt.Printf("Payment successful: %s\n", payload.OrderID)
        // Update your database, send confirmation email, etc.
    case "payment.failed":
        fmt.Printf("Payment failed: %s\n", payload.OrderID)
        // Handle failed payment
    case "refund.completed":
        fmt.Printf("Refund completed: %s\n", payload.OrderID)
        // Update order status
    }

    // Respond with 200 OK
    w.WriteHeader(http.StatusOK)
    w.Write([]byte(`{"status":"received"}`))
}

func main() {
    http.HandleFunc("/webhooks/dvpay", webhookHandler)
    fmt.Println("Webhook server listening on :8080")
    http.ListenAndServe(":8080", nil)
}

Step 2: Configure in DVPay App

After creating your endpoint, register it in the DVPay merchant dashboard:

Open DVPay Mobile App

Navigate to your merchant dashboard in the DVPay mobile application.

Go to API Settings

Tap on SettingsAPI ConfigurationWebhook Settings

Enter Your Webhook URL

Input your publicly accessible HTTPS endpoint (e.g., https://yourdomain.com/webhooks/dvpay)

Webhook URLs must use HTTPS. HTTP endpoints will be rejected.

Select Event Types

Choose which events you want to receive:

  • payment.success - Payment completed successfully
  • payment.failed - Payment attempt failed
  • payment.pending - Payment is awaiting confirmation
  • refund.completed - Refund processed successfully
  • order.cancelled - Order was cancelled

Save Configuration

Click Save to activate your webhook endpoint.

Webhook Events

DVPay sends the following event types:

payment.success
string
Triggered when a payment is successfully completed. Update your order status and fulfill the order.
payment.failed
string
Triggered when a payment attempt fails. Notify the customer and provide alternative payment options.
payment.pending
string
Triggered when a payment is initiated but awaiting confirmation. Hold the order until final status.
refund.completed
string
Triggered when a refund is successfully processed. Update order status and notify the customer.
order.cancelled
string
Triggered when an order is cancelled before payment. Release any reserved inventory.

Payload Structure

All webhook events follow this JSON structure:

{
  "event": "payment.success",
  "order_id": "ord_abc123xyz",
  "amount": 100.00,
  "currency": "USD",
  "status": "completed",
  "payment_method": "khqr",
  "timestamp": 1696435200,
  "metadata": {
    "store_id": "store-123",
    "customer_phone": "+855123456789"
  }
}
event
string required
The event type (e.g., payment.success, payment.failed)
order_id
string required
Unique identifier for the order
amount
number required
Payment amount
currency
string required
Currency code (USD or KHR)
status
string required
Payment status (completed, failed, pending, refunded, cancelled)
payment_method
string
Payment method used (e.g., khqr, bank_transfer)
timestamp
number required
Unix timestamp when the event occurred
metadata
object
Additional contextual data about the transaction

Security Best Practices

Testing Webhooks

Local Development with ngrok

Expose your local server for webhook testing:

# Install ngrok
npm install -g ngrok

# Start your local server
node server.js

# Expose port 8080
ngrok http 8080

Use the generated ngrok URL (e.g., https://abc123.ngrok.io/webhooks/dvpay) in your webhook configuration.

Manual Testing

Test your webhook endpoint manually:

curl -X POST https://yourdomain.com/webhooks/dvpay \
  -H "Content-Type: application/json" \
  -d '{
    "event": "payment.success",
    "order_id": "test_order_123",
    "amount": 50.00,
    "currency": "USD",
    "status": "completed",
    "timestamp": 1696435200
  }'

Retry Logic

If your webhook endpoint returns an error or doesn't respond within 5 seconds, DVPay will retry:

  • 1st retry: After 1 minute
  • 2nd retry: After 10 minutes
  • 3rd retry: After 1 hour
  • Final retry: After 6 hours
After 4 failed attempts, the webhook will be marked as failed. You can view failed webhooks in your merchant dashboard.

Troubleshooting

Next Steps

Error Handling

Learn how to handle API errors and webhook failures

Security Best Practices

Secure your API integration and webhook endpoints