m2pfintech
API LibraryCard

Replace or Upgrade a Card

Initiates a card replacement request. Used when a card is lost, stolen, damaged, or when upgrading to a different product tier.

Replacement Types

TypeDescription
ReplaceSame product — new card with new kit number, old card blocked
UpgradeDifferent 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.
POST
/v1/issuance/card-replacement/

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

Replacement details with old and new card identifiers

mobile*

Phone number with country code

entityId*string

Entity identifier of the cardholder

hierarchyId?string

Branch/corporate hierarchy ID

hierarchyType?string

Type of organizational hierarchy

Value in"Corporate" | "Branch" | "Sub_Corporate" | "Bank"
oldKitNo*string

Kit number of the card being replaced

newKitNo?string

Kit number of the new replacement card (for same-product replacements)

targetProductId?string

Product ID for upgrades (when switching to a different product tier)

isPerso?boolean

Whether the replacement card should be personalized (embossed with cardholder name).

  • true — Personalized card (takes longer to produce)
  • false — Non-personalized / instant card
embossingCheck?boolean

Validate embossing compatibility before replacement

replaceType?string

Type of replacement:

  • Replace — Same product, new card
  • UPGRADE — Different (higher-tier) product
Value in"Replace" | "UPGRADE"
addressCategory?string

Which address to use for card delivery

Value in"permanent_address" | "communication_address"
cardType?string

Card form factor

Value in"Physical" | "Virtual"
fundingSourceDto?

Funding source for replacement fees (if applicable)

addonCardReplacement?boolean
backupCardReplacement?boolean
branchReceived?boolean
cardReplacementFees?object
offlineAccountId?string
preference?object
productId?string
rule?

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

wallets?

Response Body

application/json

application/json

curl -X POST "https://sandbox-api.m2pprepaid.com/prepaid/customer/v1/issuance/card-replacement/" \  -H "X-TENANT-ID: ACME_CORP" \  -H "Content-Type: application/json" \  -d '{    "mobile": {      "value": "9600105550",      "countryCode": 91    },    "entityId": "508437549690000122290925",    "hierarchyId": "90009",    "hierarchyType": "Branch",    "oldKitNo": "690000146",    "newKitNo": "690000147",    "isPerso": false  }'

{
  "result": {
    "kitNo": "690000147",
    "cardType": "PHYSICAL",
    "expDate": "2027-10-31",
    "networkType": "VISA"
  },
  "pagination": null
}

{
  "type": "https://www.m2pfintech.com/problem/problem-with-message",
  "title": "Customer does not exist for EntityId: 508437549690000122290925",
  "status": 409,
  "detail": "Customer does not exist for EntityId: 508437549690000122290925",
  "message": "error.business",
  "businessCode": "PP_CORP_038"
}

Check Card Balance POST

Retrieves the real-time balance for a specific card. For multi-currency cards (forex), returns the balance across all wallets/currencies. ### Key Differences from Wallet Balance API - This API works at the **card level** — returns balances for all wallets on the card - The Wallet Balance API works at the **wallet level** — returns balance for a specific wallet - Use this API for a card overview; use Wallet Balance for specific currency lookups ### Response Returns the available balance, held amounts, and wallet details for the specified card.

Set Card PIN (First Time) POST

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: 1. Call Generate OTP API first 2. Get the `traceNumber` from the OTP response 3. 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