Set Card PIN (First Time)
Sets the PIN for a card for the first time, or resets it. This is the secure version that requires RSA-encrypted PIN in the request body.
PIN Encryption
The newPin field must be RSA-encrypted using the public key provided during onboarding.
Example encrypted value: u3uPnpCuaht7B3WsfY6SjXVqG0/laW7Kq5zlSR0zpZ0BY3Ge+JJNJpvfe4NVqSqN
OTP Verification
This endpoint requires OTP verification. You must:
- Call Generate OTP API first
- Get the
traceNumberfrom the OTP response - Include both the OTP and traceNumber in this request
When to Use
- First-time PIN setup after card issuance
- PIN reset (forgotten PIN) — customer verifies via OTP
Authorization
bearerAuth tenantId JWT Bearer token from the Authentication API
In: header
Your unique tenant identifier assigned during onboarding
In: header
Header Parameters
Your unique tenant identifier
Request Body
application/json
Card details with encrypted new PIN and OTP verification
Phone number with country code
Card kit number
Entity identifier
Card expiry date in MM/YY format
One-time password received via SMS
RSA-encrypted new PIN. Use the public key provided during onboarding to encrypt the 4-digit PIN. The encrypted value will be a long base64-encoded string.
OTP verification details — obtain traceNumber from Generate OTP API
Security validation rules for card operations. The required fields depend on the product configuration. Common fields used for validation:
Response Body
application/json
application/json
application/json
curl -X POST "https://sandbox-api.m2pprepaid.com/prepaid/customer/v1/cards/v2/set-pin" \ -H "X-TENANT-ID: ACME_CORP" \ -H "Content-Type: application/json" \ -d '{ "mobile": { "value": "9600389470", "countryCode": 91 }, "entityId": "621643170420004195030925", "kit": "20004195", "expiryDate": "10/27", "otp": "123456", "newPin": "u3uPnpCuaht7B3WsfY6SjXVqG0/laW7Kq5zlSR0zpZ0BY3Ge+JJNJpvfe4NVqSqN", "otpDetails": { "traceNumber": "ff2e25ea-03eb-475d-a88b-31e1fc08ee8f", "mobileNumber": "9600389470", "otp": "123456" }, "rule": { "expiryDate": "10/27", "otp": "123456", "traceNumber": "ff2e25ea-03eb-475d-a88b-31e1fc08ee8f" } }'{
"result": {
"message": "Card pin change 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": "Kit does not exists for id :20001114195",
"status": 409,
"detail": "Kit does not exists for id :20001114195",
"message": "error.business",
"businessCode": "PPCUST_002"
}Replace or Upgrade a Card POST
Initiates a card replacement request. Used when a card is lost, stolen, damaged, or when upgrading to a different product tier. ### Replacement Types | Type | Description | |------|-------------| | **Replace** | Same product — new card with new kit number, old card blocked | | **Upgrade** | Different product — new product with enhanced features/limits | ### Embossing - `isPerso: true` — Personalized (embossed) card with cardholder's name - `isPerso: false` — Non-personalized (instant) card ### Important Rules - Old card is automatically blocked when replacement is processed - Balance and wallets are transferred to the new card - For **upgrades**, provide `targetProductId` for the new product - Card type (Physical/Virtual) cannot change during replacement - `hierarchyType` must match the customer's hierarchy (Corporate/Branch) - Do **not** use `Card Closure` as the prior block reason if replacement is intended. Closure reason is treated as terminal and can make replacement ineligible.
Track Card Delivery Status POST
Retrieves the current delivery status and tracking details for a physical card. Provide the kit number to get real-time delivery information including courier details, expected delivery date, and current status. ### How It Works 1. After card issuance, the physical card enters the fulfillment pipeline 2. Use this API with the kit number to check delivery progress 3. The response includes delivery method (home delivery or branch pickup), current status, and courier/tracking information when available ### Response Includes - **Delivery Mode**: Home Delivery (HD) or Branch Pickup (BP) - **Current Status**: Where the card is in the delivery pipeline - **Courier Details**: AWB number, courier name (for home delivery) - **Branch Details**: Branch name, address (for branch pickup) - **Timestamps**: When the card was dispatched, expected delivery date - **Recipient Details**: Name and contact of the person who received the card ### Tip Poll this API periodically (e.g., every 6 hours) to update the delivery status in your app, or use webhooks for real-time delivery notifications.