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)
}
const axios = require('axios');
async function getBalance(apiKey) {
const url = 'https://merchant.dv.vai247.pro/api/v1/payment-gateway/balance-inquiry';
const headers = {
'X-Api-Key': apiKey,
'Content-Type': 'application/json'
};
try {
const response = await axios.post(url, {}, { headers });
return response.data;
} catch (error) {
console.error('Error fetching balance:', error.response?.data || error.message);
throw error;
}
}
// Usage
(async () => {
try {
const balance = await getBalance('your-api-key');
console.log('USD Balance:');
console.log(` Total: $${balance.data.usd.balance.toFixed(2)}`);
console.log(` Frozen: $${balance.data.usd.freeze.toFixed(2)}`);
console.log(` Usable: $${balance.data.usd.usable.toFixed(2)}`);
console.log('\nKHR Balance:');
console.log(` Total: ៛${balance.data.khr.balance.toFixed(2)}`);
console.log(` Frozen: ៛${balance.data.khr.freeze.toFixed(2)}`);
console.log(` Usable: ៛${balance.data.khr.usable.toFixed(2)}`);
} catch (error) {
console.error('Failed to fetch balance');
}
})();
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
| Field | Type | Description |
|---|---|---|
statusCode | number | HTTP status code (200 for success) |
message | string | Response message |
data | object | Balance data object |
data.usd | object | USD balance details |
data.usd.balance | number | Total USD balance |
data.usd.freeze | number | Frozen USD amount (pending transactions) |
data.usd.usable | number | Available USD balance for use |
data.khr | object | KHR balance details |
data.khr.balance | number | Total KHR balance |
data.khr.freeze | number | Frozen KHR amount (pending transactions) |
data.khr.usable | number | Available KHR balance for use |
traceId | string | Request 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
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
- Cache Balance Data: Consider caching balance information with a reasonable TTL (e.g., 30-60 seconds) to avoid excessive API calls
- Monitor Frozen Amounts: Regularly check frozen amounts to understand pending obligations
- Multi-currency Handling: Always check both USD and KHR balances if your business operates with both currencies
- Error Handling: Implement retry logic with exponential backoff for transient errors
- Security: Never expose balance information in client-side code or logs