Update Card Status (Lock / Unlock / Block)

Changes the status of a prepaid card. This is the primary API for card lifecycle management.

Supported Operations

Important Rules

• A card must be ACTIVE to be locked or blocked
• A card must be LOCKED to be unlocked
• BLOCKED cards cannot be recovered — a card replacement must be initiated
• If the card is already in the requested status, the API returns a success message like "Card was already LOCKED" without error

Reason Codes

Partners should provide meaningful reasonCode and reasonMsg for audit trail purposes. Common reason codes: 01 (Customer request), 02 (Suspected fraud), 03 (Lost), 04 (Stolen)

reasonCode: When to Use vs Not Use

Correct Usage

• Keep reasonCode short and stable (machine-readable), e.g. CUST_REQ, FRAUD_SUSPECTED, LOST_CARD, STOLEN_CARD.
• Put human-readable context in reasonMsg.
• Reuse a controlled reason catalog across channels and environments.

Avoid

• Do not use reasonCode to imply operation type (operation is controlled by status).
• Do not send paragraph text in reasonCode.
• Do not rely on reasonCode for status transition logic.

Special Restriction: Card Closure

• Treat Card Closure as a terminal closure intent, not as a regular block reason.
• If Card Closure is used explicitly as reasonCode, the card may be treated as closure/terminal in downstream business handling.
• In such cases, card replacement eligibility can be impacted (replacement may be blocked by policy).
• For replaceable scenarios (lost/stolen/damaged), use non-closure reason codes such as LOST_CARD, STOLEN_CARD, DAMAGED_CARD.

curl -X POST "https://sandbox-api.m2pprepaid.com/prepaid/customer/v1/cards/update/status" \  -H "X-TENANT-ID: ACME_CORP" \  -H "Content-Type: application/json" \  -d '{    "mobile": {      "value": "9609388730",      "countryCode": 91    },    "status": "LOCKED",    "entityId": "476843769320000001160925",    "kit": "320000001",    "reasonCode": "01",    "reasonMsg": "Customer requested card lock due to security concerns"  }'

{
  "result": {
    "message": "Card was LOCKED successfully"
  },
  "pagination": null
}

{
  "type": "https://www.m2pfintech.com/problem/constraint-violation",
  "title": "Method argument not valid",
  "status": 400,
  "message": "error.validation",
  "fieldErrors": [
    {
      "field": "mobile",
      "message": "Invalid contact",
      "objectName": "changeCardPin"
    }
  ]
}

{
  "type": "https://www.m2pfintech.com/problem/problem-with-message",
  "title": "Customer does not exists for id :9609388731",
  "status": 409,
  "detail": "Customer does not exists for id :9609388731",
  "message": "error.business",
  "businessCode": "PPCUST_002"
}