Get Balance

Retrieves the current combined balance for the authenticated merchant.

This endpoint returns:

walletBalance - the effective available wallet balance
settlementBalance - the total eligible transactions awaiting settlement

Endpoint

GET /api/v1/balance

Authentication

This endpoint requires HMAC Integration Authentication.

Query Parameters

This endpoint does not accept any query parameters.

Example Request

import crypto from 'crypto';

const API_KEY = process.env.PAYMENT_API_KEY!;
const API_SECRET = process.env.PAYMENT_API_SECRET!;

async function getBalance() {
  const method = 'GET';
  const path = '/api/v1/balance';
  const body = '';
  const timestamp = Date.now().toString();

  const message = `${timestamp}.${body}`;
  const signature = crypto
    .createHmac('sha256', API_SECRET)
    .update(message)
    .digest('hex');

  const response = await fetch(`https://api.example.com${path}`, {
    method,
    headers: {
      'X-API-Key': API_KEY,
      'X-Timestamp': timestamp,
      'X-Signature': `sha256=${signature}`,
    },
  });

  const result = await response.json();

  if (result.success) {
    console.log('Wallet balance:', result.data.walletBalance);
    console.log('Settlement balance:', result.data.settlementBalance);
    return result.data;
  } else {
    console.error('Error:', result.error);
    throw new Error(result.error.message);
  }
}

const balance = await getBalance();

Response

Success Response (200 OK)

{
  "success": true,
  "data": {
    "walletBalance": 12500.5,
    "settlementBalance": 3200,
    "currency": "THB",
    "status": "active"
  }
}

Error Response (401 Unauthorized)

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Merchant context not available"
  }
}

Response Fields

Field	Type	Description
`walletBalance`	number	Effective available wallet balance for the merchant
`settlementBalance`	number	Total eligible transaction amount awaiting settlement
`currency`	string	Wallet currency code
`status`	string	Wallet status, such as `active`, `frozen`, or `closed`

Notes

walletBalance is the effective available balance, not just the raw stored wallet amount.
settlementBalance is calculated from eligible transactions across all integrations for the merchant.
The endpoint does not require a request body.

On this page