Api References

Balance Inquiry

Retrieve merchant balance for both USD and KHR currencies.

Endpoint

POST https://merchant.dv.vai247.pro/api/v1/payment-gateway/balance-inquiry

Authentication

This endpoint uses standard authentication and requires only the X-Api-Key header.

Required Header:

  • X-Api-Key: Your API key

See Authentication for more details.

Description

The Balance Inquiry endpoint allows merchants to retrieve their current account balance for both USD and KHR currencies. This endpoint returns detailed balance information including total balance, frozen amount, and usable balance for each currency.

Code Examples

package main

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

type BalanceDetail struct {
    Balance float64 `json:"balance"`
    Freeze  float64 `json:"freeze"`
    Usable  float64 `json:"usable"`
}

type BalanceData struct {
    USD BalanceDetail `json:"usd"`
    KHR BalanceDetail `json:"khr"`
}

type BalanceResponse struct {
    StatusCode int         `json:"statusCode"`
    Message    string      `json:"message"`
    Data       BalanceData `json:"data"`
    TraceID    string      `json:"traceId"`
}

func getBalance(apiKey string) (*BalanceResponse, error) {
    url := "https://merchant.dv.vai247.pro/api/v1/payment-gateway/balance-inquiry"

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

    // Add authentication header
    req.Header.Set("X-Api-Key", apiKey)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        return nil, err
    }

    var result BalanceResponse
    if err := json.Unmarshal(body, &result); err != nil {
        return nil, err
    }

    return &result, nil
}

func main() {
    balance, err := getBalance("your-api-key")
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    fmt.Println("USD Balance:")
    fmt.Printf("  Total: $%.2f\n", balance.Data.USD.Balance)
    fmt.Printf("  Frozen: $%.2f\n", balance.Data.USD.Freeze)
    fmt.Printf("  Usable: $%.2f\n", balance.Data.USD.Usable)

    fmt.Println("\nKHR Balance:")
    fmt.Printf("  Total: ៛%.2f\n", balance.Data.KHR.Balance)
    fmt.Printf("  Frozen: ៛%.2f\n", balance.Data.KHR.Freeze)
    fmt.Printf("  Usable: ៛%.2f\n", balance.Data.KHR.Usable)
}

Response

Success Response (200)

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "usd": {
      "balance": 1250.75,
      "freeze": 100.00,
      "usable": 1150.75
    },
    "khr": {
      "balance": 5000000.00,
      "freeze": 250000.00,
      "usable": 4750000.00
    }
  },
  "traceId": "trace_abc123"
}

Response Fields

FieldTypeDescription
statusCodenumberHTTP status code (200 for success)
messagestringResponse message
dataobjectBalance data object
data.usdobjectUSD balance details
data.usd.balancenumberTotal USD balance
data.usd.freezenumberFrozen USD amount (pending transactions)
data.usd.usablenumberAvailable USD balance for use
data.khrobjectKHR balance details
data.khr.balancenumberTotal KHR balance
data.khr.freezenumberFrozen KHR amount (pending transactions)
data.khr.usablenumberAvailable KHR balance for use
traceIdstringRequest trace identifier for debugging

Error Responses

401 Unauthorized

Invalid API credentials provided.

{
  "statusCode": 401,
  "message": "Unauthorized - invalid API credentials",
  "error": "Unauthorized"
}

404 Not Found

Merchant account not found.

{
  "statusCode": 404,
  "message": "Not Found - merchant not found",
  "error": "Not Found"
}

500 Internal Server Error

Server-side error occurred while processing the request.

{
  "statusCode": 500,
  "message": "Internal Server Error",
  "error": "Internal Server Error"
}

Balance Components Explained

Total Balance

The total amount in your merchant account, including both available and frozen funds.

Frozen Amount

Funds temporarily held due to:

  • Pending transactions
  • Orders awaiting confirmation
  • Refunds being processed
  • Payouts in progress

Usable Balance

The amount available for immediate use. This is calculated as: Total Balance - Frozen Amount

Note: Only the usable balance can be withdrawn or used for payouts. Frozen amounts will automatically become usable once the associated transactions are completed or cancelled.

Use Cases

  • Pre-transaction Validation: Check available balance before processing large transactions
  • Account Monitoring: Track balance changes and frozen amounts
  • Financial Reporting: Generate balance reports for accounting purposes
  • Payout Planning: Verify sufficient funds before initiating payout operations
  • Reconciliation: Verify balance matches expected amounts from transactions

Best Practices

  1. Cache Balance Data: Consider caching balance information with a reasonable TTL (e.g., 30-60 seconds) to avoid excessive API calls
  2. Monitor Frozen Amounts: Regularly check frozen amounts to understand pending obligations
  3. Multi-currency Handling: Always check both USD and KHR balances if your business operates with both currencies
  4. Error Handling: Implement retry logic with exponential backoff for transient errors
  5. Security: Never expose balance information in client-side code or logs
Rate Limiting: While there are no specific rate limits documented for this endpoint, avoid excessive polling. Use webhooks for transaction updates instead of constantly checking balance.