m2pfintech
API LibraryBeneficiary

Update Beneficiary Status

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

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 identification and target status

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

curl -X POST "https://sandbox-api.m2pprepaid.com/prepaid/customer/v1/imps/beneficiary/status-update" \  -H "X-TENANT-ID: ACME_CORP" \  -H "Content-Type: application/json" \  -d '{    "entityId": "798782647420001622070825",    "accountNumber": "912010036724556",    "ifscCode": "UTIB0001234",    "status": "INACTIVE"  }'
{
  "result": {
    "entityId": "798782647420001622070825",
    "accountNumber": "912010036724556",
    "ifscCode": "UTIB0001234",
    "accountName": "Rajesh Kumar",
    "beneType": "SELF",
    "status": "INACTIVE"
  },
  "pagination": null
}
{
  "type": "https://www.m2pfintech.com/problem/problem-with-message",
  "title": "Beneficiary not found",
  "status": 409,
  "detail": "No beneficiary found with the given account number and IFSC for this entity",
  "message": "error.business",
  "businessCode": "PPCUST_021"
}

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

Activate Card (Basic) POST

Activates a customer's card using basic validation: card last 6 digits, CVV, and expiry date. This is the simpler activation flow — for more comprehensive validation, use the Activate Card with Rules endpoint. ### Prerequisites - Card must be in `ALLOCATED` status - Customer must have the physical card to provide CVV and last-6 digits ### Post-Activation - Card status changes from `ALLOCATED` → `ACTIVE` - Customer can immediately start transacting