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

parameter	type	Whether it is required	Maximum length	description	Example values
version	String	M	8	Interface version. The current value is: 1. 2	1.2
requestTime	String	M	32	Request time, according to RFC3339 specification, format: yyyy-mm-dd'T'HH:mm:ss. SSSXXX	2022-01-22T10:00:00.500+08:00
keyVersion	String	M	8	Key version. The current value is: 1	1
merchantNo	String	M	15	Merchant ID, a unique identifier generated when a merchant signs a contract with a PayerMax business	10229810189301
appId	String	M	64	Merchant Application ID, a unique identifier assigned by PayerMax to a merchant application	46153e2b787241ae8b01857bb087d1bd
+data	object	M	32	Request data body
「plainSign	boolean	O		Whether to display accounts with a balance of 0 -true: display -false: does not display (default), filters the account directly	false
「accountType	List	O		Account 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
「accountCurrency	List	O	32	3-digit currency code in accordance with ISO 4217 When no currency is specified, all accounts that are not 0 are returned	USD

Response Parameters

parameter	type	Whether it is required	Maximum length	description	Example values
code	String	M	32	Interface response code, 'APPLY_SUCCESS' represents success	APPLY_SUCCESS
msg	String	M	256	Response description, 'Success.'	Success
+data	object	c		Returns the data body
「inquiryTime	String	M	64	Query time, in accordance with RFC3339 specification, format: yyyy-mm-dd'T'HH:mm:ss. SSSXXX	2022-01-22T10:00:00.500+08:00
+AccountRealTimeType	List	M	64
-accountType	String	O	32	Account Type	AVAILABLE
-balance	SBigDecimal	O	(20,2)	Gold amount in units	A9998.00
-currency	String	O	3	3-digit currency code in accordance with ISO 4217	USD
「errorCode	String	C	32	Query failed error code
「errorMsg	String	C	256	The description of the query failed error code

2.Sample code

Merchant request parameters

{
  "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

{
  "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 parameters	type	Whether it is required	Maximum length	description	Example values
version	String	M	8	Interface version. The current value is：1.2	1.2
requestTime	String	M	32	Request time, according to RFC3339 specification, format: yyyy-mm-dd'T'HH:mm:ss. SSSXXX	2022-01-22T10:00:00.500+08:00
keyVersion	String	M	8	Key version. The current value is: 1	1
merchantNo	String	M	15	Merchant ID, a unique identifier generated when a merchant signs a contract with a PayerMax business	10229810189301
appId	String	M	64	Merchant Application ID, a unique identifier assigned by PayerMax to a merchant application	46153e2b787241ae8b01857bb087d1bd
+data	object	M	32	Request data body
「accountType	List	O		Account 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
「accountCurrency	String	O	32	3-digit currency code in accordance with ISO 4217 When no currency is specified, returns All	IDR
「inquiryDate	String	M	32	Support query for nearly 90 days	"2023-01-01"
「timezone	String	M	32	Time zone is currently only supported (UTC, CST).	CST

Response Parameters

parameter	type	Whether it is required	Maximum length	description	Example values
code	String	M	32	The interface response code, 'APPLY_SUCCESS' indicates that the interface call was successful	APPLY_SUCCESS
msg	String	M	256	Response description, 'Success.'，'Success.'	Success
+data	object	c		Request data body
「timezone	String	M	32	time zone	CST
「acctTime	String	M	63	The 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
+accountEndDayTimeTypes	List	M		Account Type result, the type of account queried
-accountType	String	M	32	Account Type	AVAILABLE
--currency	String	M	3	33-digit currency code in accordance with ISO 4217 When no currency is specified, all currencies with balances greater than 0 are returned	IDR
-initalBalance	BigDecimal	M	(20,4)	Opening balance	43820.00
-endBalance	BigDecimal	M	(20,4)	Closing balance	1157812.00
-inflowAmount	BigDecimal	M	(20,4)	Period outflow amount The amount of inflow during the day	0.00
-outflowAmount	BigDecimal	M	(20,4)	Period inflow amount The amount of outflow during the day	1201632.00
「errorCode	String	c	32	Order failure error code
「errorMsg	String	c	256	Description of the order failure error code

2.2.Sample code

End of day balance inquiry request

{
  "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

{
  "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 type	Comments
ACQUIRING	An account that stores funds that have passed the acquiring business and have reached the settlement cycle
DISBURSEMENT	An account that stores funds transferred through recharge or settlement transfer and can be used for disbursement (original AVAILABLE account with available balance)
FREEZE	Account for depositing funds frozen due to disputes or risk control
SETTLE	An account for depositing funds that have not reached the settlement cycle and have not been settled
REVERSE	deposit account