Balance Inquiry ​

1. Balance inquiry service introduction ​

Checus balance inquiry service provides real-time balance inquiry and day-end balance inquiry:

• Real-time balance inquiry: Query the customer ledger balance in real time based on the merchant’s request time, account type, and currency.
• Day-end balance inquiry: Returns balance information for the specified date and time zone.

2. Real-time balance inquiry ​

1. API parameters API parameters

API name: Real-time balance inquiry /currentBalanceQuery

Request Parameters

Parameter	Type	Required	Max length	Description	Example
version	String	M	8	API version. Current value: 1.2	1.2
requestTime	String	M	32	Request time, conforms to RFC 3339, format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX	2022-01-22T10:00:00.500+08:00
keyVersion	String	M	8	Key version. Current value: 1	1
merchantNo	String	M	15	Merchant number, unique identifier generated when the merchant signs a contract with Checus	10229810189301
appId	String	M	64	Merchant application ID, a unique identifier assigned by Checus	46153e2b787241ae8b01857bb087d1bd
+data	object	M	32	Request payload
「plainSign	boolean	O		Whether to display accounts with zero balance — true: display; false: do not display (default), directly filter out the account	false
「accountType	List	O		Account type: -ACQUIRING acquiring account -DISBURSEMENT disbursement account (formerly AVAILABLE) -FREEZE frozen account -SETTLE unsettled account -REVERSE security deposit account. When account type is not specified, return all accounts with non-zero balance	AVAILABLE
「accountCurrency	List	O	32	3-letter currency code, conforms to ISO 4217. When currency is not specified, return all accounts with non-zero balance	USD

Response Parameters

Parameter	Type	Required	Max length	Description	Example
code	String	M	32	API response code, 'APPLY_SUCCESS' indicates success	APPLY_SUCCESS
msg	String	M	256	Response message, 'Success.'	Success
+data	object	C		Response payload
「inquiryTime	String	M	64	Inquiry time, conforms to RFC 3339, 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)	Amount	A9998.00
-currency	String	O	3	3-letter currency code, conforms to ISO 4217	USD
「errorCode	String	C	32	Error code when the inquiry fails
「errorMsg	String	C	256	Error description when the inquiry fails

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"
    ]
  }
}

Response 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 inquiry ​

1. API parameters API parameters

API name: Day-end balance inquiry /dayEndBalanceQuery

Request Parameters

Parameter	Type	Required	Max length	Description	Example
version	String	M	8	API version. Current value: 1.2	1.2
requestTime	String	M	32	Request time, conforms to RFC 3339, format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX	2022-01-22T10:00:00.500+08:00
keyVersion	String	M	8	Key version. Current value: 1	1
merchantNo	String	M	15	Merchant number, unique identifier generated when the merchant signs a contract with Checus	10229810189301
appId	String	M	64	Merchant application ID, a unique identifier assigned by Checus	46153e2b787241ae8b01857bb087d1bd
+data	object	M	32	Request payload
「accountType	List	O		Account type: -ACQUIRING acquiring account -DISBURSEMENT disbursement account (formerly AVAILABLE) -FREEZE frozen account -SETTLE unsettled account -REVERSE security deposit account. When not specified, return all	AVAILABLE
「accountCurrency	String	O	32	3-letter currency code, conforms to ISO 4217. When not specified, return all	IDR
「inquiryDate	String	M	32	Supports querying the last 90 days	"2023-01-01"
「timezone	String	M	32	Time zone. Currently supports (UTC, CST)	CST

Response Parameters

Parameter	Type	Required	Max length	Description	Example
code	String	M	32	API response code, 'APPLY_SUCCESS' indicates success	APPLY_SUCCESS
msg	String	M	256	Response message, 'Success.'	Success
+data	object	C		Response payload
「timezone	String	M	32	Time zone	CST
「acctTime	String	M	63	Time corresponding to the balance, conforms to RFC 3339, format: yyyy-MM-dd’T’HH:mm:ss.SSSXXX	2022-01-22T10:00:00.500+08:00
+accountEndDayTimeTypes	List	M		Account type results, the account types queried
-accountType	String	M	32	Account type	AVAILABLE
-currency	String	M	3	3-letter currency code, conforms to ISO 4217. When not specified, return all currencies with balance greater than 0	IDR
-initalBalance	BigDecimal	M	(20,4)	Opening balance	43820.00
-endBalance	BigDecimal	M	(20,4)	Closing balance	1157812.00
-inflowAmount	BigDecimal	M	(20,4)	Amount of outflow during the period; amount inflow during the day	0.00
-outflowAmount	BigDecimal	M	(20,4)	Amount of inflow during the period; amount outflow during the day	1201632.00
「errorCode	String	C	32	Order failure error code
「errorMsg	String	C	256	Order failure error description

2. Sample code

Day-end 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"
  }
}

Day-end 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 types ​

Account type	Description
ACQUIRING acquiring balance account	Stores funds that have reached the settlement cycle through acquiring business
DISBURSEMENT disbursement balance account	Stores funds transferred in via top-up or settlement-to-top-up that can be used for disbursement (formerly AVAILABLE account)
FREEZE frozen account	Stores funds that are frozen due to disputes or risk control
SETTLE unsettled account	Stores funds that have not reached the settlement cycle and are not yet settled out
REVERSE security deposit account	Stores security deposit funds