m2pfintech
API LibraryBeneficiary

Register New Beneficiary

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
POST
/v1/imps/beneficiary

Authorization

bearerAuth tenantId
AuthorizationBearer <token>

JWT Bearer token from the Authentication API

In: header

X-TENANT-ID<token>

Your unique tenant identifier assigned during onboarding

In: header

Header Parameters

X-TENANT-ID*string

Your unique tenant identifier assigned during partner onboarding

Request Body

application/json

Beneficiary details including bank account information and OTP for verification

entityId*string

Required. Unique entity identifier of the cardholder (payer) who is registering this beneficiary. Obtained from the issuance response or Customer Fetch API.

Length1 <= length
accountNumber*string

Required. Bank account number of the beneficiary. This is the account that will receive IMPS fund transfers. Must be a valid Indian bank account number.

Length1 <= length
ifscCode*string

Required. Indian Financial System Code (IFSC) of the beneficiary's bank branch. Format: 4 letters (bank code) + 0 + 6 characters (branch code). Example: UTIB0001234 (Axis Bank, Branch 1234). The IFSC is validated against the RBI directory.

Match^[A-Z]{4}0[A-Z0-9]{6}$
Length11 <= length <= 11
accountName?string

Name of the bank account holder. This should match the name registered with the bank for the given account number. Used for display purposes and compliance checks.

beneType?string

Categorization of the beneficiary relationship:

  • SELF: Cardholder's own bank account (e.g., savings account)
  • OTHER: Third-party bank account (e.g., family member, vendor)
Value in"SELF" | "OTHER"
status?string

Initial status of the beneficiary (defaults to ACTIVE after OTP verification)

Value in"ACTIVE" | "INACTIVE"
otpDetails?

OTP verification details. First call the Generate OTP API to get a traceId, then include the traceId and the OTP entered by the cardholder.

bankName?string
email?string
id?string
mobileNo?string

Response Body

application/json

application/json

application/json

curl -X POST "https://sandbox-api.m2pprepaid.com/prepaid/customer/v1/imps/beneficiary" \  -H "X-TENANT-ID: ACME_CORP" \  -H "Content-Type: application/json" \  -d '{    "entityId": "798782647420001622070825",    "accountNumber": "912010036724556",    "ifscCode": "UTIB0001234",    "accountName": "Rajesh Kumar",    "beneType": "SELF",    "otpDetails": {      "traceId": "OTP_TRACE_abc123def456",      "otp": "582947"    }  }'
{
  "result": {
    "entityId": "798782647420001622070825",
    "accountNumber": "912010036724556",
    "ifscCode": "UTIB0001234",
    "accountName": "Rajesh Kumar",
    "beneType": "SELF",
    "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 id: 798782647420001622070825",
  "message": "error.business",
  "businessCode": "PPCUST_002"
}

Fetch All Beneficiaries for Cardholder GET

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)

Update Beneficiary Status POST

Activates or deactivates an existing IMPS beneficiary. Use this endpoint to: - **Deactivate** a beneficiary that is no longer needed (status: `INACTIVE`) - **Reactivate** a previously deactivated beneficiary (status: `ACTIVE`) ### Key Business Rules - Only `ACTIVE` and `INACTIVE` status transitions are allowed - Deactivating a beneficiary does not delete it — it can be reactivated later - Fund transfers to `INACTIVE` beneficiaries will be rejected - Status changes are immediate and do not require OTP verification