API INQUIRY BALANCE

Request

The Balance Inquiry API enables merchants to retrieve real-time account balance information for their Smilepayz accounts. This API provides detailed balance information for different account types including pay-in and pay-out accounts.

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-05: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 Used to specify which balance types to query

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.
See Account Transfer Guide

Example Body – Balance Inquiry Request:

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

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

Response

HTTP Response

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-05:00

Body Parameters

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 Localized based on request language
accountNo	O	String	Merchant account identifier for balance inquiry Format: Alphanumeric string Same as the accountNo provided in the request Used for account identification and verification
name	O	String	Account holder name or account description Format: UTF-8 encoded string Displayed name for the account Used for account identification and display purposes
balanceTypes	O	Array	Requested balance type specifications Format: Array of predefined balance type codes Examples: ["BALANCE"], ["AVAILABLE"] Indicates which balance types were queried
accountInfos	M	Object	Detailed balance information container Contains comprehensive balance details for the specified account See Balance Account Model
balanceType	M	String	Type of balance being reported Format: Predefined balance type codes Examples: BALANCE, AVAILABLE Indicates the specific balance category
amount	M	Object	Total account balance amount Contains currency and value information See Money Model
currency	M	String	ISO 4217 currency code specification Fixed value: PEN (Peruvian Sol) Determines the currency unit for balance amounts
value	M	String	Balance amount as string value Format: String representation of numeric value Example: "250000" represents PEN 250000 Used for precise balance representation
availableBalance	M	Object	Available balance for transactions Contains currency and value information May differ from total balance due to holds or restrictions See Money Model
currency	M	String	ISO 4217 currency code specification Fixed value: PEN (Peruvian Sol) Determines the currency unit for available balance
value	M	String	Available balance amount as string value Format: String representation of numeric value Example: "250000" represents PEN 250000 Used for precise available balance representation
additionalInfo	O	Object	Additional account information and metadata Format: JSON object Contains supplementary account details when available Used for extended account information

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

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