Api References

Authentication

Authenticate with the DVPay API using API keys.

DVPay API uses different authentication methods depending on the operation:

Standard Endpoints (Simple Authentication)

For most operations, only the X-Api-Key header is required:

Endpoints:

Create Order (POST /api/v1/payment-gateway/order/create)
Generate QR Code (POST /api/v1/payment-gateway/payment/generate-qr)
Transaction Detail (POST /api/v1/payment-gateway/payment/transaction-detail)
Cancel Order (POST /api/v1/payment-gateway/order/cancel)
Balance Inquiry (POST /api/v1/payment-gateway/balance-inquiry)

Required Header:

X-Api-Key: Your API key

Financial Endpoints (Signature-Based Authentication)

For sensitive financial operations (refunds and payouts), signature-based authentication is required using HMAC-SHA256:

Endpoints:

Refund Order (POST /api/v1/payment-gateway/order/refund)
Payout (POST /api/v1/payment-gateway/order/payout)

Required Headers:

X-Api-Key: Your API key
X-Timestamp: Unix timestamp in seconds
X-Signature: HMAC-SHA256 signature
X-Idempotent-Key: Unique identifier (UUID) to prevent duplicate transactions

Signature Generation

Formula:

message = rawPayload + timestamp
signature = HMAC-SHA256(message, api_secret)

Where:

rawPayload = JSON request body as a string
timestamp = Unix timestamp in seconds (same as X-Timestamp header)
api_secret = Your API secret from DVPay mobile app

Getting Your API Secret: DVPay mobile app → Settings → API Configuration → Show API Secret

Code Examples

Standard Authentication (Create Order, Generate QR, etc.)

package main

import (
    "fmt"
    "net/http"
)

func createStandardRequest(url string) (*http.Request, error) {
    req, err := http.NewRequest("POST", url, nil)
    if err != nil {
        return nil, err
    }

    req.Header.Set("X-Api-Key", "your-api-key")
    req.Header.Set("Content-Type", "application/json")

    return req, nil
}

const axios = require('axios');

const createStandardHeaders = () => ({
  'X-Api-Key': 'your-api-key',
  'Content-Type': 'application/json'
});

// Usage
const response = await axios.post(url, data, {
  headers: createStandardHeaders()
});

Signature-Based Authentication (Refunds and Payouts)

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "net/http"
    "strconv"
    "time"
)

func generateSignature(secret, timestamp, rawPayload string) string {
    message := rawPayload + timestamp
    h := hmac.New(sha256.New, []byte(secret))
    h.Write([]byte(message))
    return hex.EncodeToString(h.Sum(nil))
}

func createSignedRequest(url, rawPayload, apiKey, apiSecret, idempotentKey string) (*http.Request, error) {
    timestamp := strconv.FormatInt(time.Now().Unix(), 10)
    signature := generateSignature(apiSecret, timestamp, rawPayload)

    req, err := http.NewRequest("POST", url, nil)
    if err != nil {
        return nil, err
    }

    req.Header.Set("X-Api-Key", apiKey)
    req.Header.Set("X-Timestamp", timestamp)
    req.Header.Set("X-Signature", signature)
    req.Header.Set("X-Idempotent-Key", idempotentKey)
    req.Header.Set("Content-Type", "application/json")

    return req, nil
}

const crypto = require('crypto');
const { v4: uuidv4 } = require('uuid');

function generateSignature(secret, timestamp, rawPayload) {
    const hmac = crypto.createHmac('sha256', secret);
    const message = rawPayload + timestamp.toString();
    hmac.update(message);
    return hmac.digest('hex');
}

const createSignedHeaders = (rawPayload, apiKey, apiSecret) => {
    const timestamp = Math.floor(Date.now() / 1000);
    const signature = generateSignature(apiSecret, timestamp, rawPayload);
    const idempotentKey = uuidv4();

    return {
        'X-Api-Key': apiKey,
        'X-Timestamp': timestamp.toString(),
        'X-Signature': signature,
        'X-Idempotent-Key': idempotentKey,
        'Content-Type': 'application/json'
    };
};

// Usage
const payload = { orderId: 123, refundAmount: 10.5 };
const rawPayload = JSON.stringify(payload);
const headers = createSignedHeaders(rawPayload, 'your-api-key', 'your-api-secret');

const response = await axios.post(url, payload, { headers });

Security Notes

Keep your API key and secret secure and never commit them to version control
Use environment variables to store sensitive credentials
API Secret vs API Key: Your API secret is used for signature generation and is more sensitive than your API key. Never expose it in client-side code
Rotate your API keys and secrets periodically
Use HTTPS for all API requests
Implement proper error handling to avoid leaking sensitive information in logs

Migration from v1.3.0: Authentication has changed significantly in v1.4.0. Standard endpoints no longer require X-App-Id and X-Timestamp headers. Financial endpoints now require signature-based authentication. See v1.4.0 Release Notes for migration guide.

Edit this pageorReport an issue

Order Lifecycle

Understand payment order states and transitions in DVPay

Create Payment Order

Creates a new payment order with QR code generation.