Check Bulk Card Balance API

---

Request Method :: POST

Base URL: Will be shared later.

Endpoint: ppcard/cms/check_bulk_card_balance

Description: The Check Bulk Card Balance API allows clients to fetch the available balances of multiple card reference numbers in a single request. The API validates card ownership, retrieves balances, and provides detailed responses for each card. If a balance cannot be fetched, the API returns a reason. This ensures efficient, batch-level balance checking with clear success and failure handling.

Headers

---

Content-Type: application/JSON

header_secrets: These values must be generated each time while consuming the API (refer to the generation process mentioned in the note above).

client_id:  To be shared during integration by ISU Team

Request Body Parameters

Parameters	Parameter description with validations	Sample	Data type	Mandatory/Optional
cardReferenceNumbers	List of card reference numbers to check	Must contain at least one valid card reference number. Each element is a string. e.g. - 1500001027, 1500001028	Array	Mandatory

Sample Request Body

---

{ "cardReferenceNumbers": [ "1500001027", "1500001028", "1500001029", "1500001058", "1500001059", "1500001948" ] }

Response Body Parameters

Parameters	Description	Data type
statusCode	Status Code(0/1)	String
statusDesc	Status Description of Status	String
status	SUCCESS/FAILED	String
fetchedAt	Timestamp of when the balances were fetched	Date-Time
data	List of balance results for each card reference number	Array
cardReferenceNumber	The reference number of the card	String
balance	Available balance of the card	Decimal
reason	Explanation if balance cannot be fetched	String

Sample Response Body

---

SUCCESS:

{ "status": "SUCCESS", "statusCode" : 0, Provides reason of failure "statusDescription": "Balances fetched successfully", "fetchedAt": "2025-09-08T11:55:10+05:30", "data": [ { "cardReferenceNumber": "1500001027", "balance": 12050.75 }, { "cardReferenceNumber": "1500001028", "balance": 8420.00 }, { "balance": null, }, { String Mandatory "cardReferenceNumber": "1500001029", "reason": "Card reference number not found" "cardReferenceNumber": "1500001058", "balance": 5000.00 }, { "cardReferenceNumber": "1500001059", "balance": null, "reason": "Card does not belongs to the provided user." }, { } ] }

 

FAILED:

If card is not mapped to the customer.

{ "status": "FAILED", "statusCode" : 1, "statusDescription": "Error Fetching Balance from Wallet" }

 

Detailed Status Codes

Status	Response Type	Description
0	SUCCESS	Balances fetched successfully
1	FAILED	Error Fetching Balance from Wallet