m2pfintech
API LibraryCard

Validate Card PIN

Verifies whether the provided PIN is correct for the given card. This is a read-only check — it does not modify the PIN.

When to Use

  • Pre-validate PIN before a sensitive operation (e.g., viewing card details)
  • Implement "confirm PIN" flows in your mobile/web app
  • PIN-based authentication for in-app transactions

Important Notes

  • Returns { valid: true/false } — never reveals the actual PIN
  • Uses the same ChangeCardPinDto as Set/Update PIN but only reads oldPin
  • No OTP required for validation
POST
/v1/cards/v2/validate-pin

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 and PIN details for validation

mobile*

Phone number with country code

kit*string

Card kit number

entityId*string

Entity identifier

expiryDate?string

Card expiry date in MM/YY format

otp?string

One-time password received via SMS

newPin*string

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.

otpDetails?

OTP verification details — obtain traceNumber from Generate OTP API

rule?

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

oldPin?string

Response Body

application/json

application/json

application/json

curl -X POST "https://sandbox-api.m2pprepaid.com/prepaid/customer/v1/cards/v2/validate-pin" \  -H "X-TENANT-ID: ACME_CORP" \  -H "Content-Type: application/json" \  -d '{    "mobile": {      "value": "9688101121",      "countryCode": 91    },    "entityId": "904602151120003756290825",    "kit": "20003756",    "expiryDate": "07/27",    "oldPin": "1234"  }'

{
  "result": {
    "valid": true
  },
  "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 :9688191121",
  "status": 409,
  "detail": "Customer does not exists for id :9688191121",
  "message": "error.business",
  "businessCode": "PPCUST_002"
}

Update Card PIN (Change Existing PIN) POST

Changes the card PIN from an existing PIN to a new PIN. Requires the current PIN and OTP verification. ### Difference from Set PIN - **Set PIN (v2)**: For first-time PIN setup or reset. Uses RSA-encrypted PIN. - **Update PIN**: For changing an existing PIN. Uses plain-text PIN (4 digits). ### PIN Lock Protection After 3 consecutive failed OTP attempts, the PIN change operation is locked for **10 minutes**. This prevents brute-force attacks. ### Flow 1. Generate OTP → receive `traceNumber` 2. Call this API with `oldPin`, `newPin`, OTP, and `traceNumber`

View Card Details (Full Card Number + CVV) POST

Retrieves the full (unmasked) card number, CVV, and expiry date for a card. This is a **sensitive operation** that reveals complete card details. ### Security Requirements Depending on the product configuration, this API may require one or more of: - **OTP verification** — Generate and validate OTP before calling this API - **Card action rule** — Provide card expiry date for server-side validation - **PIN verification** — Verify PIN before revealing card details ### Service Codes The `serviceCode` field identifies the card type: - `226` — Forex card - `620` — GPR (General Purpose Reloadable) card - `000` — Default / auto-detect ### When to Use - "View Card Details" feature in mobile/web app - Tokenization flows that require full card number - Card-on-file registration for e-commerce ### ⚠️ PCI-DSS Compliance Partners must ensure that card details are displayed securely and never stored in logs or databases. Follow PCI-DSS guidelines for handling sensitive card data.