m2pfintech
API LibraryIssuance

Issue Forex Card

Creates a new forex card issuance with multi-currency wallet allocations, customer details, travel information, and supporting documents.

Key Features

  • Multi-currency wallets (USD, EUR, GBP, SGD, etc.)
  • Automatic TCS calculation based on LRS limits
  • Support for primary + backup cards
  • Comprehensive fee breakdown (issuance fee, forex margin, GST, TCS)
  • Document upload (passport, visa, air ticket, A2 form, purpose proof)

Required Fields

  • applicationNumber: Unique per issuance
  • customer: Full customer profile with travel details
  • product: Valid forex product
  • plasticCode: Card design/BIN configuration
  • walletAmount: Currency allocation with conversion rates
  • issuer: Hierarchy details

Issuance Modes

ModeDescription
OnlineSelf-service digital channel
BranchBranch-initiated with teller ID
Partner APIPartner integration

Documents (Query Parameters)

Upload supporting documents as binary files via query parameters:

  • passport, visa, airTicket, applicationForm
  • purposeProof, educationalLoanLetter, a2Form
  • feeWaiverApproval, relationshipProof, discountProof

Server

Use the corporate server URLs for this endpoint.

POST
/v1/forex/issuance/

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

Query Parameters

passport?unknown

Passport document (binary)

visa?unknown

Visa document (binary)

airTicket?unknown

Air ticket document (binary)

a2Form?unknown

A2 form document (binary)

purposeProof?unknown

Purpose proof document (binary)

applicationForm?unknown

Application form document (binary)

feeWaiverApproval?unknown

Fee waiver approval document (binary)

Header Parameters

X-TENANT-ID*string

Your unique tenant identifier

Request Body

application/json

applicationNumber*string

Required. Unique application number

Length1 <= length
noOfCardsRequested?integer

Number of cards requested (including backup)

issuanceType?string
Value in"Single" | "Bulk" | "DIY"
product*

Product configuration

plasticCode*

Required. Card design configuration

customer*

Customer details for card issuance

walletAmount*

Required. Currency allocations for the forex card

Items1 <= items
cards?

Card details (primary + backup)

funding?

Funding source for card load. Mirrors FundingSourceDto from pp-corporate service.

declarations?

Regulatory declarations for forex issuance

summary?

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
issuer*

Issuer hierarchy details

mode?string

Issuance channel

Value in"Online" | "Branch" | "Call Center" | "Partner API"
branchCode?string

Branch code (for branch channel)

tellerId?string

Teller ID (for branch channel)

isBranch?boolean
Defaultfalse
promoCode?string

Promotional code for special offers

feeWaiverApprovalReason?string

Reason for fee waiver (if applicable)

resetLimit?boolean

Reset existing limits before applying new ones

Defaultfalse
vkycFlag?string

Video KYC completion (Y/N)

Value in"Y" | "N"
retailExtTxnId?string

External transaction ID for retail transactions

loanDetails?

Loan details if applicable; mandatory if purpose of travel is EDUCATIONAL_LOAN_LETTER

loadDescription?object

Additional load description metadata

additionalInformation?unknown

Flexible field for client-specific additional data

miscellaneous?

Additional miscellaneous fields (ethnicCode, panStatus, authStatus, etc.)

additionalInfo?object
id?string
ncsReferenceNumber?string
noOfCards?integer
Formatint32
rrn?string

Response Body

application/json

application/json

application/json

curl -X POST "https://sandbox-api.m2pprepaid.com/prepaid/middleware/v1/forex/issuance/" \  -H "X-TENANT-ID: ACME_CORP" \  -H "Content-Type: application/json" \  -d '{    "applicationNumber": "73334",    "noOfCardsRequested": 1,    "issuanceType": "Single",    "isBranch": true,    "branchCode": "90009",    "tellerId": "909090",    "product": {      "name": "FXPRD002",      "productId": "tlJYez726h",      "productType": "Forex"    },    "plasticCode": {      "code": "8000000008",      "description": "FXPC001"    },    "customer": {      "firstName": "Sidney",      "middleName": "King",      "lastName": "Sheldon",      "fatherName": "DAD",      "motherName": "LO",      "dob": "05/08/1987",      "gender": "Male",      "email": "forex@gmail.com",      "pan": "WSQPC9334U",      "customerId": "87001810807",      "customerType": "ETB",      "occupation": "SELF_EMPLOYED",      "annualIncome": "10000",      "politicallyExposed": false,      "existingForex": false,      "mobile": {        "value": "7000101134",        "countryCode": 91      },      "address": {        "address1": "Address01",        "city": "KOLAR",        "state": "KARNATAKA",        "pin": "800001",        "country": "India"      },      "account": {        "accountNo": "89997087809",        "branch": "00437",        "bank": "563",        "cif": "87001810807",        "branchCode": "90009"      },      "kyc": {        "kycType": "Full KYC",        "kycId": "819876776746",        "kycIdType": "Aadhar card/letter same address"      },      "trips": [        {          "country": {            "name": "Argentina",            "countryCodeIso": 32,            "threeDigitCountryCode": "ARG",            "twoDigitCountryCode": "AR",            "codeIsd": 54          },          "startDate": "30/09/2025",          "endDate": "22/09/2026",          "purposeOfTravel": {            "code": "S0301",            "purpose": "BUSINESS"          },          "type": "NEW",          "passports": [            {              "passportNumber": "V7894309",              "passportFileNumber": "PFN849901212031",              "issuedPlace": "Chennai",              "issuedDate": "18/09/2016",              "expiryDate": "11/09/2033"            }          ]        }      ]    },    "walletAmount": [      {        "amount": 800,        "conversionRate": 84.98,        "netAmount": 67984,        "totalAmount": 67984,        "wallet": {          "wallet": {            "walletName": "USD",            "walletType": "USD",            "walletBaseCurrency": {              "name": "U.S. Dollars",              "currencyCodeISO": "USD",              "currencyCodeNumeric": 840            }          }        }      }    ],    "funding": {      "fundingMode": "SAVINGS_ACCOUNT/PG",      "referenceField": "8765679fhj976554",      "paymentInstrumentType": "NB",      "channelId": "PG",      "cif": "87001810807",      "accountNo": "94823829039402",      "sourceOfFund": "SELF"    },    "declarations": {      "fatca": true,      "itr": true,      "tc": true,      "lrs": true,      "nilIssuance": false    },    "summary": {      "feeWaiver": "NOTALLOWED",      "value": 67984,      "fees": 3399.2,      "gst": 734.23,      "tcs": 0,      "tax": 734.23,      "total": 72117.43,      "lrs": 2    },    "issuer": {      "hierarchyId": "90009",      "issuerTenant": "qappregsep"    },    "cards": [      {        "embosseType": "Non-Perso",        "backupCard": false,        "cardType": "Physical",        "cardDeliveryType": "Deliver To Bank",        "kit": "690000177",        "email": "forex@gmail.com",        "mobile": {          "value": "8800108900",          "countryCode": 91        },        "plasticCode": {          "code": "8000000008",          "description": "FXPC001"        },        "cardDeliveryAddress": {          "address1": "Address01",          "city": "KOLAR",          "state": "KARNATAKA",          "pin": "800001",          "country": "India"        }      },      {        "embosseType": "Non-Perso",        "backupCard": true,        "cardType": "Physical",        "cardDeliveryType": "Deliver To Bank",        "kit": "690000186",        "email": "forex@gmail.com",        "mobile": {          "value": "8800108900",          "countryCode": 91        }      }    ]  }'
{
  "result": {
    "currentStatus": "APPROVED",
    "applicationNumber": "73334",
    "issuanceType": "Single",
    "customer": {
      "firstName": "Sidney",
      "lastName": "Sheldon",
      "pan": "WSQPC9334U",
      "customerId": "87001810807"
    },
    "cards": [
      {
        "kit": "690000177",
        "cardNumber": "411811XXXXXX1828",
        "expDate": "2027-10-31",
        "backupCard": false
      },
      {
        "kit": "690000186",
        "cardNumber": "411811XXXXXX1141",
        "expDate": "2027-10-31",
        "backupCard": true
      }
    ],
    "summary": {
      "feeWaiver": "NOTALLOWED",
      "value": 67984,
      "fees": 3399.2,
      "tcs": 0,
      "tax": 734.23,
      "gst": 734.23,
      "total": 72117.43,
      "baseConvertedAmount": 800
    },
    "noOfCards": 1,
    "noOfCardsRequested": 1,
    "issuer": {
      "hierarchyId": "90009",
      "issuerTenant": "qappregsep",
      "typeOfSOR": "M2P",
      "typeOfFRM": "M2P"
    }
  },
  "pagination": null
}
{
  "type": "https://www.m2pfintech.com/problem/constraint-violation",
  "title": "Method argument not valid",
  "status": 400,
  "message": "error.validation",
  "fieldErrors": [
    {
      "field": "customer.pan",
      "message": "PAN is not valid"
    },
    {
      "field": "customer.mobile",
      "message": "Invalid contact"
    },
    {
      "field": "issuer.hierarchyId",
      "message": "must not be empty"
    },
    {
      "field": "applicationNumber",
      "message": "must not be empty"
    }
  ]
}

{
  "type": "https://www.m2pfintech.com/problem/problem-with-message",
  "title": "Branch Issuance already exist for application number: 73334",
  "status": 409,
  "detail": "Branch Issuance already exist for application number: 73334",
  "message": "error.business",
  "businessCode": "PP_CORP_004"
}

Issue Prepaid Single/Bulk Card POST

Creates a corporate card issuance for one or more beneficiaries under a single `applicationNumber`. The **same endpoint** handles both `Single` and `Bulk` issuances — the difference is the `issuanceType` field and the number of objects in the `beneficiaries` array. ### Single vs Bulk | | `Single` | `Bulk` | |---|---|---| | `issuanceType` | `"Single"` | `"Bulk"` | | `beneficiaries` array | 1 item | 2 – N items | | Immediate response | Full card details | `CREATED` status only | | Per-beneficiary reject | Not applicable | `reject-beneficiaries` endpoint | | Bulk CSV upload | Not applicable | `file/upload/beneficiary/bulk-upload/{appNo}` | ### Bulk Issuance Flow ``` POST /v1/corporate-issuances/ (issuanceType: Bulk, N beneficiaries) ↓ status = CREATED POST /v1/corporate-issuances/state-transition (MAKER → PENDING_APPROVAL / checker → APPROVED) ↓ status = APPROVED → cards provisioned async GET /v1/corporate-issuances/fetch-by-status/SUCCESS (poll for completion) ``` For very large batches (hundreds of records), use the **CSV bulk upload** endpoint `POST /v1/corporate-issuances/file/upload/beneficiary/bulk-upload/{applicationNumber}` instead of embedding all beneficiaries in JSON. ### Key Features - Single or bulk beneficiary issuance - Physical (Perso/Non-Perso) or Virtual cards - Maker-checker workflow support - Auto-generated customer IDs and entity IDs - KYC document upload (proofOfIdentity, proofOfAddress) - Initial card load with fee breakdown ### NTB vs ETB - `ntbApplication: true` → New customer, full profile creation - `ntbApplication: false` → Existing customer with prior accounts ### Documents Upload identity and address proofs as multipart files via query parameters. ### Server Use the **corporate** server URLs for this endpoint.

Issue Wallet/Prepaid Card POST

Creates a new card/wallet issuance for **GPR** or **Wallet** product types. This is the primary issuance endpoint for individual customer onboarding. ### Flow 1. Submit issuance request with customer details + product info 2. System validates KYC, hierarchy, and product eligibility 3. If auto-approval is configured → card is created immediately 4. If maker-checker is enabled → request goes to `PENDING_APPROVAL` 5. On success → customer profile + card/wallet are created ### GPR Issuance - Requires: `applicationNumber`, customer details, product, issuer - Card types: Physical (Perso/Non-Perso) or Virtual - Initial load amount optional ### Wallet Issuance - Requires: `applicationNumber`, customer details (with entityId for existing), product, issuer - No physical card — wallet-only account - Purchaser details supported (corporate buying for employee) ### De-dupe Handling If a customer with the same mobile/PAN already has an account for this product, the system returns a `409` with de-dupe error. ### Server Use the **middleware** server URLs for this endpoint.