Balance

This page was rewritten against the live backend

The previous version documented /api/v1/vendor/wallet/balance and /api/v1/vendor/wallet/statement — neither exists. What follows is read directly from paymentSystem/src/modules/vendors/routes/vendor.balance.route.js.

Get Balance

GET /vendor/balance
Authorization: Bearer <token>

{
  "statusCode": "00",
  "message": "Vendor balance fetched successfully",
  "data": {
    "walletId": "w-uuid",
    "balance": 12500.75,
    "walletActive": true,
    "settlementAccount": {
      "id": "sa-uuid",
      "account_holder_name": "My Company Pvt Ltd",
      "account_type": "CURRENT",
      "bank_name": "HDFC Bank",
      "bank_account_no": "1234567890",
      "bank_ifsc_code": "HDFC0001234",
      "city": "Mumbai",
      "state": "Maharashtra"
    }
  }
}

balance/walletActive are 0/false if there's no wallet linked yet; settlementAccount is null if none is configured.

Add Funds

POST /vendor/balance/add
Authorization: Bearer <token>
Content-Type: application/json

{ "amount": 1000, "description": "Manual top-up" }

description is optional. amount must be a positive number.

{
  "statusCode": "00",
  "message": "Funds added successfully",
  "data": { "transactionId": "wtxn-uuid", "amountAdded": 1000, "newBalance": 13500.75 }
}

Withdraw Funds

POST /vendor/balance/withdraw
Authorization: Bearer <token>
Content-Type: application/json

{ "amount": 500, "description": "Settlement payout" }

Requires a settlement account to already be linked — 400 { "statusCode": "09" } if not.

{
  "statusCode": "00",
  "message": "Withdrawal initiated successfully",
  "data": {
    "transactionId": "wtxn-uuid",
    "amountDebited": 500,
    "newBalance": 13000.75,
    "settlementAccount": {
      "accountHolder": "My Company Pvt Ltd",
      "bankName": "HDFC Bank",
      "accountNo": "1234567890",
      "ifsc": "HDFC0001234"
    }
  }
}

Insufficient balance: 400 { "statusCode": "10", "message": "Insufficient balance", "data": { "requested": 500, "available": 300 } }.

Balance History

Paginated wallet ledger — every credit and debit.

GET /vendor/balance/history?page=1&limit=20&type=CREDIT&from=2026-07-01&to=2026-07-04&search=top-up
Authorization: Bearer <token>

Query param	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Results per page (default: 20)
`type`	string	`CREDIT` or `DEBIT`
`from`, `to`	string	Date range `YYYY-MM-DD`
`search`	string	Case-insensitive match on the ledger entry's description

{
  "statusCode": "00",
  "message": "Transfer history fetched",
  "data": [
    {
      "id": "ledger-uuid",
      "walletId": "w-uuid",
      "type": "CREDIT",
      "amount": 1000,
      "grossAmount": 1000,
      "netAmount": 1000,
      "chargeAmount": 0,
      "commissionAmount": 0,
      "description": "Manual top-up",
      "createdAt": "2026-07-04T10:30:00Z",
      "transaction": { "id": "wtxn-uuid", "type": "ADD_MONEY", "status": "SUCCESS", "utrNumber": null, "createdAt": "2026-07-04T10:30:00Z" }
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 142, "totalPages": 8 }
}

Cards

Read-only list of the vendor's own cards (issuance/management is a separate, aggregator-only API — see the note below).

GET /vendor/balance/cards
Authorization: Bearer <token>

{
  "statusCode": "00",
  "message": "Vendor cards fetched",
  "data": [
    {
      "id": "card-uuid",
      "cardHolderName": "My Company Pvt Ltd",
      "maskedPan": "400000XXXXXX0000",
      "last4": "0000",
      "expiryMonth": 12,
      "expiryYear": 2029,
      "type": "DEBIT",
      "network": "VISA",
      "status": "ACTIVE",
      "dailyLimit": 50000,
      "availableLimit": 50000,
      "perTxnLimit": 25000,
      "internationalTxn": false,
      "contactless": true,
      "kycVerified": true,
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ]
}

Card issuance is aggregator-only

Creating, updating, or deleting a card (POST/PUT/DELETE /vendor/:vendorId/cards[/…], vendor.cards.route.js) is gated checkRole("aggregator") — a vendor credential can only read its own card list above, not manage cards.