Skip to content

The balance inquiry service

1.Disbursement Introduction

The PayerMax Balance Enquiry Service provides merchants with real-time balance enquiry and end-of-day balance enquiry:

  • Real-time balance query: Query real-time customer account balances based on merchants' request time, account type, and currency
  • End-of-day balance query: returns the balance information under the specified date and time zone

2.Real-time balance query

API

1.1.Api parameters

Interface name:Current Balance Query /currentBalanceQuery

Request Parameters

parametertypeWhether it is requiredMaximum lengthdescriptionExample values
versionStringM8Interface version. The current value is: 1. 21.2
requestTimeStringM32Request time, according to RFC3339 specification, format: yyyy-mm-dd'T'HH:mm:ss. SSSXXX2022-01-22T10:00:00.500+08:00
keyVersionStringM8Key version. The current value is: 11
merchantNoStringM15Merchant ID, a unique identifier generated when a merchant signs a contract with a PayerMax business10229810189301
appIdStringM64Merchant Application ID, a unique identifier assigned by PayerMax to a merchant application46153e2b787241ae8b01857bb087d1bd
+dataobjectM32Request data body
「plainSignbooleanOWhether to display accounts with a balance of 0 -true: display -false: does not display (default), filters the account directly false
「accountTypeListOAccount Type: -ACQUIRING Acquiring Account -DISBURSEMENT Disbursement Account (formerly AVAILABLE) -FREEZE Freeze Accounts -SETTLE Accounts to be Settled -REVERSE Margin Account When no account type is specified, all accounts that are not 0 are returned AVAILABLE
「accountCurrencyListO323-digit currency code in accordance with ISO 4217 When no currency is specified, all accounts that are not 0 are returned USD

Response Parameters

parametertypeWhether it is requiredMaximum lengthdescriptionExample values
codeStringM32Interface response code, 'APPLY_SUCCESS' represents successAPPLY_SUCCESS
msgStringM256Response description, 'Success.'Success
+dataobjectcReturns the data body
「inquiryTimeStringM64Query time, in accordance with RFC3339 specification, format: yyyy-mm-dd'T'HH:mm:ss. SSSXXX2022-01-22T10:00:00.500+08:00
+AccountRealTimeTypeListM64
-accountTypeStringO32Account TypeAVAILABLE
-balanceSBigDecimalO(20,2)Gold amount in unitsA9998.00
-currencyStringO33-digit currency code in accordance with ISO 4217USD
「errorCodeStringC32Query failed error code
「errorMsgStringC256The description of the query failed error code

2.Sample code

Merchant request parameters

json
{
  "version": "1.2",
  "keyVersion": "1",
  "requestTime": "2022-01-12T20:31:20.000+0800",
  "appId": "41c4f31f487a42b7996979e775c3d7bc",
  "merchantNo": "010113855475499",
  "data": {
    "plainSign": true,
    "accountCurrency": [
      "EGP"
    ],
    "accountType": [
      "AVAILABLE",
      "FREEZE",
      "SETTLE",
      "REVERSE"
    ]
  }
}

Return parameters

json
{
  "msg": "",
  "code": "APPLY_SUCCESS",
  "data": {
    "accountRealTimeTypes": [
      {
        "balance": 18277.20,
        "accountType": "SETTLE",
        "currency": "EGP"
      }
    ],
    "inquiryTime": "2023-02-23T07:47:05.940Z"
  }
}

3.Day end balance query

API

1.Api parameters

Interface name:Day End Balance Query /dayEndBalanceQuery

Request Parameters

1.Interface parameterstypeWhether it is requiredMaximum lengthdescriptionExample values
versionStringM8Interface version. The current value is:1.21.2
requestTimeStringM32Request time, according to RFC3339 specification, format: yyyy-mm-dd'T'HH:mm:ss. SSSXXX2022-01-22T10:00:00.500+08:00
keyVersionStringM8Key version. The current value is: 11
merchantNoStringM15Merchant ID, a unique identifier generated when a merchant signs a contract with a PayerMax business10229810189301
appIdStringM64Merchant Application ID, a unique identifier assigned by PayerMax to a merchant application46153e2b787241ae8b01857bb087d1bd
+dataobjectM32Request data body
「accountTypeListOAccount Type: -ACQUIRING Acquiring Account -DISBURSEMENT Disbursement Account (formerly AVAILABLE) -FREEZE Freeze Accounts -SETTLE Accounts to be Settled -REVERSE Margin Account When no account type is specified, returns All AVAILABLE
「accountCurrencyStringO323-digit currency code in accordance with ISO 4217 When no currency is specified, returns All IDR
「inquiryDateStringM32Support query for nearly 90 days "2023-01-01"
「timezoneStringM32Time zone is currently only supported (UTC, CST). CST

Response Parameters

parametertypeWhether it is requiredMaximum lengthdescriptionExample values
codeStringM32The interface response code, 'APPLY_SUCCESS' indicates that the interface call was successfulAPPLY_SUCCESS
msgStringM256Response description, 'Success.','Success.'Success
+dataobjectcRequest data body
「timezoneStringM32time zoneCST
「acctTimeStringM63The time of the corresponding balance conforms to RFC3339 specification, format: yyyy-mm-dd'T'HH:mm:ss. SSSXXX 2022-01-22T10:00:00.500+08:00
+accountEndDayTimeTypesListMAccount Type result, the type of account queried
-accountTypeStringM32Account TypeAVAILABLE
--currencyStringM333-digit currency code in accordance with ISO 4217 When no currency is specified, all currencies with balances greater than 0 are returned IDR
-initalBalanceBigDecimalM(20,4)Opening balance 43820.00
-endBalanceBigDecimalM(20,4)Closing balance 1157812.00
-inflowAmountBigDecimalM(20,4)Period outflow amount The amount of inflow during the day 0.00
-outflowAmountBigDecimalM(20,4)Period inflow amount The amount of outflow during the day 1201632.00
「errorCodeStringc32Order failure error code
「errorMsgStringc256Description of the order failure error code

2.2.Sample code

End of day balance inquiry request

json
{
  "version": "1.2",
  "keyVersion": "1",
  "requestTime": "2022-01-12T20:31:20.000+0800",
  "appId": "41c4f31f487a42b7996979e775c3d7bc",
  "merchantNo": "010113855475499",
  "data": {
    "accountCurrency": "TRY",
    "accountType": [
      "AVAILABLE"
    ],
    "inquiryDate": "2023-02-20",
    "timezone": "utc"
  }
}

End-of-day balance inquiry response

json
{
  "msg": "",
  "code": "APPLY_SUCCESS",
  "data": {
    "acctTime": "2023-02-22",
    "timezone": "GMT+0:00",
    "accountEndDayTimeTypes": [
      {
        "accountType": "AVAILABLE",
        "currency": "TRY",
        "inflowAmount": 0.00,
        "initalBalance": 0.00,
        "endBalance": 0.00,
        "outflowAmount": 0.00
      }
    ]
  }
}

4.account type

account typeComments
ACQUIRINGAn account that stores funds that have passed the acquiring business and have reached the settlement cycle
DISBURSEMENTAn account that stores funds transferred through recharge or settlement transfer and can be used for disbursement (original AVAILABLE account with available balance)
FREEZEAccount for depositing funds frozen due to disputes or risk control
SETTLEAn account for depositing funds that have not reached the settlement cycle and have not been settled
REVERSEdeposit account

Released under the MIT License.