API INQUIRY BALANCE

Request

The Balance Inquiry API enables merchants to retrieve real-time account balance information.

Request Path:

sandbox: https://sandbox-gateway.smilepayz.com/v2.0/inquiry-balance
production: https://gateway.smilepayz.com/v2.0/inquiry-balance

Header Parameters

Field	Required	Type	Description
Content-Type	M	String	HTTP content type specification Fixed value: application/json Required for proper request parsing
X-TIMESTAMP	M	String	ISO 8601 datetime format with timezone offset Format: yyyy-MM-ddTHH:mm:ss±HH:mm Example: 2020-12-17T10:55:00+07:00 Note: Must be current server time within ±5 minutes
X-SIGNATURE	M	String	Digital signature for request authentication. See Signature Generation
X-PARTNER-ID	M	String	Unique merchant identifier assigned by the platform Format: Alphanumeric string Used for merchant authentication and transaction routing Please enter merchantID

Body Parameters

Field	Required	Type	Description
accountNo	M	String(128)	Merchant account identifier for balance inquiry Format: Alphanumeric string Maximum length: 128 characters Used to identify the specific account for balance retrieval
balanceTypes	M	List(String)	Balance type specifications to retrieve Format: Array of predefined balance type codes Default: ["BALANCE"] Examples: BALANCE, AVAILABLE

Important Notes

1. Sandbox Environment: accountNo uses randomly generated string values for testing purposes
2. Production Environment: accountNo can be retrieved from the merchant backend system.
See How to Get Production Account Number
3. Pay-In Account: Used for collecting funds from all incoming payment transactions
4. Pay-Out Account: Used for processing disbursement and withdrawal transactions
5. Account Transfers: Balances can be transferred between different account types.
ดูคู่มือการโอนเงินบัญชี

Example Header – Balance Inquiry Request:

POST {Base URL}/v2.0/inquiry-balance HTTP/1.2

Content-type: application/json
X-TIMESTAMP: 2020-12-18T15:06:00+07:00
X-SIGNATURE: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5
X-PARTNER-ID: 20001

{
  "accountNo": "21020030202403071031",
  "balanceTypes": [
    "BALANCE"
  ]
}

Response

HTTP Request

Field	Required	Type	Description
Content-Type	M	String	HTTP response content type specification Fixed value: application/json Indicates JSON response format
X-TIMESTAMP	M	String	ISO 8601 datetime format with timezone offset Format: yyyy-MM-ddTHH:mm:ss±HH:mm Example: 2020-12-17T10:55:00+07:00

Response Body

Field	Required	Type	Description
code	M	String	API response status code indicating operation result Format: Two-digit string Success: "00", Error: Other codes Used for programmatic response handling
message	M	String	Human-readable response status description Format: UTF-8 encoded string Provides detailed information about the operation result
accountInfos	M	BalanceAccounts	Account balance information container Contains balance type, amount, and available balance details See BalanceAccounts Model
accountNo	O	String	Original account identifier for reference Format: Same as request accountNo Used for account verification and tracking
balanceTypes	O	List	Requested balance types that were processed Format: Array of balance type codes Contains the balance types that were successfully retrieved
name	O	String	Account holder name for display purposes Format: UTF-8 encoded string Shown in balance inquiry results
additionalInfo	O	JsonString	Additional account information and metadata Format: JSON object Contains supplementary account details when available

Example Body – Balance Inquiry Response:

Content-type: application/json 
X-TIMESTAMP: 2020-12-17T10:55:00+07:00

{
  "code": "00",
  "message": "Successful",
  "accountNo": "21020030202403071031",
  "name": "Sandbox Test",
  "balanceTypes": [
    "balance"
  ],
  "accountInfos": {
    "balanceType": "BALANCE",
    "amount": {
      "currency": "IDR",
      "value": "250000"
    },
    "availableBalance": {
      "currency": "IDR",
      "value": "250000"
    }
  }
}