Fetch All Beneficiaries for Cardholder
Retrieves all registered IMPS beneficiaries for a cardholder. Returns both active and inactive beneficiaries. Use this endpoint to:
- Display the list of saved beneficiaries in your fund transfer UI
- Check if a beneficiary is already registered before attempting to add a new one
- Show the cardholder their beneficiary management dashboard
Response Details
Each beneficiary in the list includes:
- Bank account details (masked account number, IFSC, account name)
- Beneficiary type (SELF/OTHER)
- Current status (ACTIVE/INACTIVE)
Authorization
bearerAuth tenantId JWT Bearer token from the Authentication API
In: header
Your unique tenant identifier assigned during onboarding
In: header
Path Parameters
Unique entity identifier for the cardholder whose beneficiaries you want to fetch. This ID is returned during card issuance or can be obtained from the Customer Fetch API.
Header Parameters
Your unique tenant identifier assigned during partner onboarding
Response Body
application/json
application/json
curl -X GET "https://sandbox-api.m2pprepaid.com/prepaid/customer/v1/imps/beneficiary/fetch/entity/798782647420001622070825" \ -H "X-TENANT-ID: ACME_CORP"Cardholder with both active and inactive beneficiaries
{
"result": [
{
"entityId": "798782647420001622070825",
"accountNumber": "912010036724556",
"ifscCode": "UTIB0001234",
"accountName": "Rajesh Kumar",
"beneType": "SELF",
"status": "ACTIVE"
},
{
"entityId": "798782647420001622070825",
"accountNumber": "10234567891234",
"ifscCode": "SBIN0001234",
"accountName": "Priya Sharma",
"beneType": "OTHER",
"status": "ACTIVE"
},
{
"entityId": "798782647420001622070825",
"accountNumber": "50100123456789",
"ifscCode": "HDFC0001234",
"accountName": "Rajesh Kumar",
"beneType": "SELF",
"status": "INACTIVE"
}
],
"pagination": null
}{
"type": "https://www.m2pfintech.com/problem/problem-with-message",
"title": "Customer does not exist",
"status": 409,
"detail": "Customer does not exist for id: 798782647420001622070825",
"message": "error.business",
"businessCode": "PPCUST_002"
}Validate OTP POST
Validates the OTP entered by the customer against the previously generated OTP. ### Flow 1. Call Generate OTP → get `traceNumber` 2. Customer enters OTP 3. Call this endpoint with `traceNumber` + OTP ### Validation Limits - Maximum **3 validation attempts** per OTP within 24 hours - After 3 failed attempts, a new OTP must be generated ### Response On success, returns a `messageHash` that may be required by subsequent operations as proof of OTP verification.
Register New Beneficiary POST
Registers a new bank account as an IMPS beneficiary for a cardholder. The beneficiary must be verified via OTP before it becomes active for fund transfers. ### How It Works 1. Collect the beneficiary's bank account details (account number, IFSC code, account name) 2. Call this API with the cardholder's entity ID and beneficiary details 3. An OTP is sent to the cardholder's registered mobile number 4. Submit the OTP using the `otpDetails` field to complete verification 5. Upon successful verification, the beneficiary status becomes `ACTIVE` ### Key Business Rules - Account number + IFSC code combination must be unique per cardholder - The IFSC code is validated against the RBI IFSC directory - Maximum 10 active beneficiaries allowed per cardholder (configurable per tenant) - Beneficiary name should match the bank account holder's name for compliance - Duplicate registrations (same account + IFSC for same cardholder) are rejected