m2pfintech
API LibraryIssuance

Issue Add-on Card

Issues a new add-on (supplementary) card linked to an existing primary card account. Add-on cards share the same account and balance as the parent card.

Use Cases

  • Corporate employee card with supplementary card for spouse
  • Parent card with add-on for family member
  • Replacement card with different embossing

Prerequisites

  • Parent card must be ACTIVE
  • Add-on card feature must be enabled for the hierarchy
  • Must not exceed configured add-on card limit

Server

Use the corporate server URLs for this endpoint.

POST
/v1/addon-card/issue-add-on-card

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

applicationNumber*string

Required. Unique application number

Length1 <= length
firstName*string

Required. First name of add-on card holder

Length1 <= length
middleName?string
lastName*string

Required. Last name of add-on card holder

Length1 <= length
nameOnCard*string

Required. Name to emboss on card (uppercase)

Length1 <= length
mobileNumber?
cardType?string
Value in"Physical" | "Virtual"
parentKit*string

Required. Kit number of the parent (primary) card

Length1 <= length
entity*string

Required. Entity ID of the primary account

Length1 <= length
nonPersoChildKit?string

Kit number for Non-Perso add-on card

gender?string
Value in"Male" | "Female" | "Others"
promoCodeId?string

Promotional code

email?string

Email address for the add-on card holder

Formatemail
cardDeliveryType?string

How the card should be delivered (e.g. HOME, BRANCH)

address?

Delivery address for physical card

hierarchyId?string

Hierarchy/corporate identifier

cardActionRule?

Card action rule configuration

embossLine4?string

Fourth embossing line on the physical card

feeSummary?

Issuance fee and tax breakdown. All values must be obtained from the issuance fee summary API and echoed back — do not compute these fields independently.

Deprecated Fields (do not use for new integrations)

  • fees → use feeDetails.LOAD_FEE or feeDetails.REGISTRATION_FEE
  • issuanceFee → use feeDetails.REGISTRATION_FEE.feeAmount
  • issuanceTax → use feeDetails.REGISTRATION_FEE.taxAmount

Response Body

application/json

application/json

application/json

curl -X POST "https://sandbox-api.m2pprepaid.com/prepaid/middleware/v1/addon-card/issue-add-on-card" \  -H "X-TENANT-ID: ACME_CORP" \  -H "Content-Type: application/json" \  -d '{    "applicationNumber": "APP12345678",    "firstName": "John",    "middleName": "William",    "lastName": "Doe",    "nameOnCard": "JOHN W DOE",    "mobileNumber": {      "value": "9000000009",      "countryCode": 91    },    "cardType": "Physical",    "parentKit": "790000041",    "entity": "767410504790000041070825",    "nonPersoChildKit": "790000042",    "gender": "Male",    "promoCode": "SUMMER25"  }'
{
  "result": {
    "applicationNumber": "APP12345678",
    "firstName": "John",
    "lastName": "Doe",
    "nameOnCard": "JOHN W DOE",
    "cardType": "Physical",
    "parentKit": "790000041",
    "entity": "767410504790000041070825",
    "nonPersoChildKit": "790000042",
    "feeSummary": {
      "feeWaiver": "ALLOWED",
      "value": 0,
      "fees": 0,
      "tax": 0,
      "total": 0,
      "feeDetails": {
        "Add on Card Fee": {
          "feeType": "Add on Card Fee",
          "feeAmount": 100,
          "taxAmount": 18
        }
      }
    }
  },
  "pagination": null
}
{
  "errors": [
    {
      "field": "applicationNumber",
      "message": "must not be blank"
    },
    {
      "field": "firstName",
      "message": "must not be blank"
    },
    {
      "field": "parentKit",
      "message": "must not be blank"
    }
  ]
}

{
  "type": "https://www.m2pfintech.com/problem/problem-with-message",
  "title": "Add-on card feature not enabled for hierarchy",
  "status": 409,
  "detail": "Add-on card feature not enabled for hierarchy",
  "message": "error.business",
  "businessCode": "PP_CORP_178"
}

Approve/Reject Forex Issuance POST

Approves or rejects a pending forex card issuance request. Works identically to the wallet issuance state transition endpoint.

Approve/Reject Issuance in Bulk POST

In a bulk corporate issuance, selectively rejects specific beneficiaries by their mobile numbers. All other beneficiaries in the application are automatically approved. ### Use Case - Bulk corporate issuance with 100 beneficiaries - Compliance team identifies 5 that should be rejected - Call this endpoint with those 5 mobile numbers - The other 95 are auto-approved