m2pfintech
API LibraryWallet Management

Wallet Load

Loads funds into the wallet associated with a kit. This API is used to add money to NCMC (National Common Mobility Card) wallets. The wallet balance will be updated after a successful load. The response includes both the current wallet balance and the staged wallet balance which represents the pending amount.

POST
/wallet/load

Authorization

tenantAuth
tenant<token>

The DCMS tenant name for multi-tenant isolation. Every API call must include this header to identify the client organization.

In: header

Header Parameters

tenant*string

The DCMS client or tenant name for multi-tenant isolation.

Request Body

application/json

kitNo*string

Unique kit number identifying the card whose wallet is being loaded.

entityId*string

Customer entity identifier who owns the wallet.

walletType*string

Type of wallet to load funds into. Currently supports NCMC wallet type.

Value in"NCMC"
txnId*string

Unique transaction identifier for this load operation. Used for idempotency and tracking.

amount*string

Amount to load into the wallet in decimal format.

Response Body

application/json

application/json

curl -X POST "https://api.dcms.example.com/v1/wallet/load" \  -H "tenant: ACME_BANK" \  -H "Content-Type: application/json" \  -d '{    "kitNo": "4240210463",    "entityId": "875826",    "walletType": "NCMC",    "txnId": "123456789021",    "amount": "200.00"  }'
{
  "result": {
    "entityId": "875826",
    "kitNo": "4240210463",
    "stagedWalletBalance": "200.00",
    "txnId": "123456789021",
    "walletBalance": "100.00",
    "walletType": "NCMC"
  },
  "exception": null,
  "pagination": null
}
{
  "result": null,
  "exception": {
    "errorCode": "TX0057",
    "shortMessage": "balance greater than Maximum Balance",
    "detailMessage": "The load amount would cause the wallet balance to exceed the maximum allowed balance",
    "httpStatus": "BAD_REQUEST",
    "fieldError": [
      "Wallet balance limit exceeded"
    ],
    "languageCode": "en"
  },
  "pagination": null
}

Fetch Wallet Linked Services POST

Retrieves the list of services linked to the wallet for a given kit and wallet type. Services represent transit or payment networks that are enabled on the NCMC wallet such as metro systems, bus networks, or other mobility services.

Error Reference

Complete error code reference — API errors by service, transaction decline codes, and status codes.