Check Card Balance
Retrieves the real-time balance for a specific card. For multi-currency cards (forex), returns the balance across all wallets/currencies.
Key Differences from Wallet Balance API
- This API works at the card level — returns balances for all wallets on the card
- The Wallet Balance API works at the wallet level — returns balance for a specific wallet
- Use this API for a card overview; use Wallet Balance for specific currency lookups
Response
Returns the available balance, held amounts, and wallet details for the specified card.
Authorization
bearerAuth tenantId JWT Bearer token from the Authentication API
In: header
Your unique tenant identifier assigned during onboarding
In: header
Header Parameters
Your unique tenant identifier
Request Body
application/json
Card identification for balance lookup
Cardholder's mobile number (optional, for additional validation)
Required. Unique entity identifier for the cardholder.
1 <= lengthKit number of the specific card. If not provided, returns balance for the primary card.
Response Body
application/json
application/json
application/json
curl -X POST "https://sandbox-api.m2pprepaid.com/prepaid/customer/v1/cards/support/fetch/balance" \ -H "X-TENANT-ID: ACME_CORP" \ -H "Content-Type: application/json" \ -d '{ "entityId": "798782647420001622070825" }'{
"result": {
"entityId": "798782647420001622070825",
"kitNo": "910000031",
"wallets": [
{
"accountId": "17556437212850072",
"currency": "INR",
"availableBalance": 15250.75,
"heldAmount": 0,
"totalBalance": 15250.75,
"status": "ACTIVE"
}
]
},
"pagination": null
}{
"type": "https://www.m2pfintech.com/problem/problem-with-message",
"title": "Bad Request",
"status": 400,
"detail": "entityId: must not be empty",
"message": "error.http.400"
}{
"type": "https://www.m2pfintech.com/problem/problem-with-message",
"title": "Customer does not exist",
"status": 409,
"detail": "Customer does not exist for entity: 798782647420001622070825",
"message": "error.business",
"businessCode": "PPCUST_002"
}Fetch All Cards for a Customer POST
Retrieves all prepaid cards associated with a customer. This returns a list of all cards (active, inactive, blocked, expired) linked to the customer's account. ### Response Includes (per card) - Card identifiers (kit number, masked card number) - Card product details (product name, type, network) - Card status (ACTIVE, LOCKED, BLOCKED, etc.) - Card expiry date - Associated wallet/account details - Card preferences (international transactions, contactless, etc.) ### When to Use - **Card Listing**: Display all cards for a customer in your app - **Card Selection**: Let the customer choose which card to perform operations on - **Multi-Card Dashboard**: Show card portfolio with status and balances
Replace or Upgrade a Card POST
Initiates a card replacement request. Used when a card is lost, stolen, damaged, or when upgrading to a different product tier. ### Replacement Types | Type | Description | |------|-------------| | **Replace** | Same product — new card with new kit number, old card blocked | | **Upgrade** | Different product — new product with enhanced features/limits | ### Embossing - `isPerso: true` — Personalized (embossed) card with cardholder's name - `isPerso: false` — Non-personalized (instant) card ### Important Rules - Old card is automatically blocked when replacement is processed - Balance and wallets are transferred to the new card - For **upgrades**, provide `targetProductId` for the new product - Card type (Physical/Virtual) cannot change during replacement - `hierarchyType` must match the customer's hierarchy (Corporate/Branch) - Do **not** use `Card Closure` as the prior block reason if replacement is intended. Closure reason is treated as terminal and can make replacement ineligible.