m2pfintech
API LibraryCard

Update Card Transaction Preferences

Configures transaction preferences for a prepaid card. Allows enabling/disabling specific transaction channels and setting daily limits for both domestic and international usage.

Preference Types

Each of the following can be independently configured:

  • ATM — Cash withdrawal from ATMs
  • E-com — Online/e-commerce purchases
  • POS — Point-of-sale merchant purchases
  • ContactLess — NFC tap-and-pay transactions
  • Cash-PoS — Cash withdrawal at POS terminals
  • Tokenization — Digital wallet tokens (Apple Pay, Google Pay, Samsung Pay)
  • Recurring Transactions — Standing instructions, subscriptions, auto-debits

Limit Configuration

For each preference type, you can set:

  • enabled — Toggle on/off
  • maxTransaction — Maximum number of transactions per day
  • maxTransactionAmountPerDay — Maximum total amount per day
  • perTransactionLimit — Maximum amount per single transaction
  • upperLimitMaxTransaction / upperLimitMaxTransactionAmountPerDay — Product-level upper bounds (read-only reference)

Important Notes

  • Card must be in ACTIVE status to update preferences
  • Only send the preferences you want to change — others remain unchanged
  • upperLimit* fields are read-only max bounds set at product level
  • Setting a value higher than the upper limit will be rejected
POST
/v1/cards/support/update/preferences

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 identification and preference overrides

mobile?

Cardholder's mobile number

entityId?string

Entity identifier

kit?string

Card kit number

userOverridden*

Preference overrides to apply

otpDetails?object
rule?

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/support/update/preferences" \  -H "X-TENANT-ID: ACME_CORP" \  -H "Content-Type: application/json" \  -d '{    "mobile": {      "value": "9609388730",      "countryCode": 91    },    "kit": "320000001",    "entityId": "476843769320000001160925",    "userOverridden": {      "international": {        "values": [          {            "type": "ATM",            "enabled": true,            "maxTransaction": "10",            "maxTransactionAmountPerDay": "10000",            "perTransactionLimit": "5000"          },          {            "type": "E-com",            "enabled": true,            "maxTransaction": "10",            "maxTransactionAmountPerDay": "10000",            "perTransactionLimit": "5000"          },          {            "type": "POS",            "enabled": true,            "maxTransaction": "10",            "maxTransactionAmountPerDay": "10000",            "perTransactionLimit": "5000"          },          {            "type": "ContactLess",            "enabled": true,            "maxTransaction": "10",            "maxTransactionAmountPerDay": "10000",            "perTransactionLimit": "5000"          },          {            "type": "Tokenization",            "enabled": true,            "maxTransaction": "10",            "maxTransactionAmountPerDay": "10000",            "perTransactionLimit": "5000"          },          {            "type": "Cash-PoS",            "enabled": true,            "maxTransaction": "10",            "maxTransactionAmountPerDay": "10000",            "perTransactionLimit": "5000"          },          {            "type": "Recurring Transactions",            "enabled": true,            "maxTransaction": "10",            "maxTransactionAmountPerDay": "10000",            "perTransactionLimit": "5000"          }        ]      }    }  }'
{
  "result": {
    "message": "Preferences updated 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": "Operation not allowed for card with LOCKED status.",
  "status": 409,
  "detail": "Operation not allowed for card with LOCKED status.",
  "message": "error.business",
  "businessCode": "PPCUST_036"
}

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.

Update Card Status (Lock / Unlock / Block) POST

Changes the status of a prepaid card. This is the primary API for card lifecycle management. ### Supported Operations | Target Status | Action | Reversible? | Use Case | |--------------|--------|-------------|----------| | `LOCKED` | Temporarily freeze card | ✅ Yes (unlock) | Suspected fraud, temporary travel hold | | `UNLOCKED` | Restore from locked state | N/A | Customer confirmation that card is safe | | `BLOCKED` | Permanently disable card | ❌ No | Lost/stolen card, confirmed fraud | ### 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 | Scenario | Send `reasonCode`? | Why | |---------|---------------------|-----| | `LOCKED` | ✅ Recommended | Needed for fraud/risk investigation and support traceability | | `BLOCKED` | ✅ Strongly recommended | Permanent impact operation; reason should always be auditable | | `UNLOCKED` | ⚠️ Optional | Useful when unlock is policy-driven or investigation outcome based | #### 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`.