m2pfintech
API LibraryCard

Perform Card Action (Unified API)

A unified API to perform various card actions. This is the maker step in the maker-checker workflow — the request is created and may require approval before execution.

Supported Actions (requestStatus)

ActionDescription
ACTIVEActivate a newly issued card
LOCKEDTemporarily lock a card
UNLOCKEDUnlock a previously locked card
BLOCKEDPermanently block a card
REPLACEDReplace a damaged/lost card
UPDATE_PREFERENCEUpdate card transaction preferences

Maker-Checker Flow

  1. Create Request (this API): Creates a card action request with currentStatus: CREATED
  2. Approve/Reject (State Transition API): Authorized user approves or rejects the request
  3. Execution: Approved requests are automatically processed

When to Use

Use this API when your organization requires approval workflows for card operations. For direct card operations without approval, use the simpler Card Status Update API.

reasonCode in Maker-Checker

  • Provide reasonCode + reasonMsg for actions with card-usage impact: LOCKED, UNLOCKED, BLOCKED, REPLACED.
  • For UPDATE_PREFERENCE, use policy-centric codes like LIMIT_TUNING, RISK_POLICY_UPDATE, CUSTOMER_REQUEST.
  • requestStatus drives execution; reasonCode is for audit/reporting and operational context.
POST
/v2/cardActions/json

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

Request Body

application/json

Card action request

mobile*

Phone number with country code

requestStatus*string

The card action to perform

Value in"ACTIVE" | "LOCKED" | "UNLOCKED" | "BLOCKED" | "REPLACED" | "UPDATE_PREFERENCE"
entityId*string

Entity identifier

kit?string

Kit number (for lock/unlock/activate/update-preference actions)

oldKitNo?string

Old kit number (required for replacement actions)

newKitNo?string

New kit number (for replacement actions)

reasonCode?string

Reason code for the maker-checker action context.

Best practice:

  • Use controlled, short values (for example: LOCK_IT, CUSTOMER_REQUEST, RISK_ALERT, DAMAGED_CARD)
  • Pair with reasonMsg for analyst readability
  • Do not use as a substitute for requestStatus
reasonMsg?string

Human-readable reason message

isPerso?boolean

Personalized card flag (for replacements)

userOverridden?

Preference overrides (for UPDATE_PREFERENCE actions)

addonCardReplacement?boolean
addressCategory?string
Value in"permanent_address" | "communication_address"
backupCardReplacement?boolean
branchReceived?boolean
cardReplacementFees?object
cardType?string
Value in"Physical" | "Virtual"
embossingCheck?boolean
fundingSourceDto?

Funding source details for card operations that involve fees

hierarchyId?string
hierarchyType?string
Value in"Corporate" | "Branch" | "Sub_Corporate" | "Bank"
otpDetails?object
requestLetterPPF?object
rule?

Security validation rules for card operations. The required fields depend on the product configuration. Common fields used for validation:

skipDocumentNeedsCheck?boolean

Response Body

application/json

application/json

application/json

curl -X POST "https://sandbox-api.m2pprepaid.com/prepaid/customer/v2/cardActions/json" \  -H "X-TENANT-ID: ACME_CORP" \  -H "Content-Type: application/json" \  -d '{    "kit": "1250000992",    "mobile": {      "value": "9847819810",      "countryCode": 91    },    "requestStatus": "ACTIVE",    "entityId": "909911641250000992250126",    "reasonCode": "Activation",    "reasonMsg": "Customer requested card activation"  }'

{
  "result": {
    "currentStatus": "CREATED",
    "id": "69763be492294fa90d79d4cd",
    "mobile": {
      "value": "9847819810",
      "countryCode": 91
    },
    "requestStatus": "ACTIVE",
    "entityId": "909911641250000992250126",
    "createdBy": "SYSTEM",
    "createdDate": "2026-01-25T15:51:00.060Z"
  },
  "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 exist for EntityId: or kit:  85391061920006070231225",
  "status": 409,
  "detail": "Customer does not exist for EntityId: or kit:  85391061920006070231225",
  "message": "error.business",
  "businessCode": "PP_CORP_038"
}

Activate Card (With Validation Rules) POST

Activates a customer's card using comprehensive validation rules including card details, customer personal information, and optional OTP/PIN verification. ### Validation Fields (in `rule` object) | Field | Required | Description | |-------|----------|-------------| | `cardLastSix` | ✅ | Last 6 digits of card number | | `expiryDate` | ✅ | Card expiry (MM/YY) | | `cvv` | ✅ | Card CVV | | `customerFirstName` | ✅ | Must match registered name | | `customerLastName` | ✅ | Must match registered name | | `customerDob` | ✅ | Must match DOB (DD/MM/YYYY) | | `govtId` | ✅ | PAN number | | `otp` | Optional | OTP if OTP-based activation | | `traceNumber` | Optional | From Generate OTP (required with OTP) | | `pin` | Optional | PIN if PIN-based activation | | `email` | Optional | Customer email | | `kitNumber` | Optional | Kit number for additional validation | ### When to Use (vs Basic Activate) Use this endpoint when your product requires comprehensive identity verification before card activation (e.g., high-value cards, full KYC products).

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