Wallet Management APIs

The Wallet Management API is designed to manage tenant wallets, handle balance requests between parent and child tenants, process transactions, and generate financial reports. This API enables businesses to maintain wallet balances, request funds, approve/reject requests, and access detailed transaction history and ledger reports.

API Documentation

Base URL

# Production
https://apis.prayog.io/gateway/wallet/api

# Sandbox
https://sandbox-apis.prayog.io/gateway/wallet/api

Available Endpoints

Health Check
Get Wallet Balance
Request Balance
Get My Balance Requests
Get Child Balance Requests
Approve Balance Request
Reject Balance Request
Create Transaction
Get Transactions
Generate Invoice
List Invoices
Get Ledger Reports
Get Profit Loss Reports
Get Date Range Reports
Get Tax Reports
Get Ledger Summary

API Endpoints

1. Health Check

Checks if the service is running and healthy.

Endpoint: GET /ping

Response

{
  "message": "Wallet controller is working!"
}

2. Get Wallet Balance

Retrieve the current balance for the specified tenant.

Endpoint: GET /balance

Request Headers:

{
  "X-Tenant-Id": "tenant-123",
  "authorization": "Bearer token-123",
  "api-key": "1234567890" // Optional if authorization is provided
}

Response

{
  "success": true,
  "data": {
    "balance": 50000,
    "tenantId": "tenant-123",
    "lastUpdated": "2024-03-20T10:30:00.000Z"
  }
}

3. Request Balance

Create a new balance request from a child tenant to a parent tenant.

Endpoint: POST /balance-request

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "tenant-123",
  "X-User-Id": "user-456",
  "authorization": "Bearer token-123"
}

Request Body Parameters

Parameter	Required	Type	Description
amount	Yes	number	Amount to request (min: 1)
walletCustomerId	Yes	string	Wallet Customer ID
remarks	No	string	Additional remarks for the request

Request Body Example

{
  "amount": 1000,
  "walletCustomerId": "customer-123",
  "remarks": "Business expansion needs"
}

Response

{
  "success": true,
  "data": {
    "id": "req-789",
    "parentTenantId": "parent-tenant-001",
    "subTenantId": "tenant-123",
    "walletCustomerId": "customer-123",
    "requestedAmount": "1000",
    "status": "PENDING",
    "remarks": "Business expansion needs",
    "createdAt": "2024-03-20T10:30:00.000Z",
    "updatedAt": "2024-03-20T10:30:00.000Z"
  },
  "message": "Balance request created successfully",
  "timestamp": "2024-03-20T10:30:00.000Z"
}

4. Get My Balance Requests

Retrieve all balance requests submitted by the calling tenant to their parent tenant.

Endpoint: GET /my-balance-requests

Request Headers:

{
  "X-Tenant-Id": "tenant-123",
  "authorization": "Bearer token-123"
}

Query Parameters

Parameter	Type	Required	Description
page	number	No	Page number (default: 1)
limit	number	No	Items per page (default: 10)
status	string	No	Filter by request status (PENDING, APPROVED, REJECTED)
walletCustomerId	string	No	Filter by wallet customer ID
minAmount	number	No	Filter by minimum requested amount
maxAmount	number	No	Filter by maximum requested amount
createdAtFrom	string	No	Filter by creation date from (ISO)
createdAtTo	string	No	Filter by creation date to (ISO)
remarksSearch	string	No	Search in remarks field

Response

{
  "success": true,
  "message": "Successfully retrieved my balance requests",
  "data": [
    {
      "id": "req-789",
      "parentTenantId": "parent-tenant-001",
      "subTenantId": "tenant-123",
      "walletCustomerId": "customer-123",
      "requestedAmount": "1000",
      "status": "PENDING",
      "remarks": "Business expansion needs",
      "createdAt": "2024-03-20T10:30:00.000Z",
      "updatedAt": "2024-03-20T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  },
  "timestamp": "2024-03-20T10:30:00.000Z"
}

5. Get Child Balance Requests

Retrieve all balance requests submitted by child tenants to the calling parent tenant.

Endpoint: GET /child-balance-requests

Request Headers:

{
  "X-Tenant-Id": "parent-tenant-123",
  "authorization": "Bearer token-123"
}

Query Parameters

Same as “Get My Balance Requests”, plus:

Parameter	Type	Required	Description
subTenantId	string	No	Filter by sub tenant ID
tenantName	string	No	Filter by tenant name

Response

{
  "success": true,
  "message": "Successfully retrieved child balance requests",
  "data": [
    {
      "id": "req-789",
      "parentTenantId": "parent-tenant-123",
      "subTenantId": "child-tenant-456",
      "tenantName": "Child Corp",
      "walletCustomerId": "customer-456",
      "requestedAmount": "2000",
      "status": "PENDING",
      "createdAt": "2024-03-20T11:00:00.000Z",
      "updatedAt": "2024-03-20T11:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  },
  "timestamp": "2024-03-20T11:00:00.000Z"
}

6. Approve Balance Request

Approve a balance request from a child tenant. Only parent tenants can perform this action.

Endpoint: PUT /balance-requests/:requestId/approve

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "parent-tenant-123",
  "X-User-Id": "user-123",
  "authorization": "Bearer token-123"
}

Request Body Parameters

Parameter	Required	Type	Description
approvedAmount	No	number	Amount to approve (for partial approval)
approvalRemarks	No	string	Remarks for approval

Request Body Example

{
  "approvedAmount": 1000,
  "approvalRemarks": "Approved after verification"
}

Response

{
  "success": true,
  "data": {
    "id": "req-789",
    "status": "APPROVED",
    "approvedAmount": "1000",
    "approvalRemarks": "Approved after verification",
    "approvedBy": "poi-123-user",
    "approvedAt": "2024-03-20T12:00:00.000Z",
    "updatedAt": "2024-03-20T12:00:00.000Z"
  },
  "message": "Balance request full approved successfully",
  "timestamp": "2024-03-20T12:00:00.000Z"
}

7. Reject Balance Request

Reject a balance request from a child tenant. Only parent tenants can perform this action.

Endpoint: PUT /balance-requests/:requestId/reject

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "parent-tenant-123",
  "X-User-Id": "user-123",
  "authorization": "Bearer token-123"
}

Request Body Parameters

Parameter	Required	Type	Description
remarks	No	string	Reason for rejection

Request Body Example

{
  "remarks": "Insufficient documentation provided"
}

Response

{
  "success": true,
  "data": {
    "id": "req-789",
    "status": "REJECTED",
    "rejectionReason": "Insufficient documentation provided",
    "rejectedBy": "user-123",
    "rejectedAt": "2024-03-20T12:00:00.000Z",
    "updatedAt": "2024-03-20T12:00:00.000Z"
  },
  "message": "Balance request rejected successfully",
  "timestamp": "2024-03-20T12:00:00.000Z"
}

8. Create Transaction

Create a new transaction. Requires either Authorization header OR X-Api-Key header.

Endpoint: POST /create-transaction

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "tenant-123",
  "authorization": "Bearer token-123", // Optional if X-Api-Key is provided
  "X-Api-Key": "1234567890" // Optional if authorization is provided
}

Request Body Parameters

Parameter	Required	Type	Description
customerId	Yes	string	Customer ID
entityType	Yes	string	Entity type (e.g., ‘order’)
referenceId	Yes	string	Reference ID (e.g., Order ID)
currency	Yes	string	Currency code (e.g., ‘INR’)
charges	Yes	array	Array of charge objects
metadata	No	array	Array of metadata objects

Charge Object Structure

Parameter	Required	Type	Description
head	Yes	string	Charge head (e.g., ‘GST’)
amount	Yes	number	Charge amount
hsnOrSac	Yes	string	HSN or SAC code
isBillable	Yes	boolean	Is the charge billable
absorbedBy	Yes	string	Who absorbs the charge (e.g., ‘merchant’)
transactionType	Yes	string	Transaction type (‘debit’/‘credit’)
chargedAt	No	string	Date string
metadata	No	array	Charge metadata
breakup	No	array	Charge breakup

Request Body Example

{
  "customerId": "cust_1234567890",
  "entityType": "order",
  "referenceId": "REF123456",
  "currency": "INR",
  "charges": [
    {
      "head": "GST",
      "amount": 10050,
      "hsnOrSac": "998314",
      "isBillable": true,
      "absorbedBy": "merchant",
      "transactionType": "debit",
      "metadata": [
        { "key": "tax_rate", "value": "18%" }
      ]
    }
  ],
  "metadata": [
    { "key": "source", "value": "web" }
  ]
}

Response

{
  "success": true,
  "data": {
    "transactionId": "txn_987654321",
    "status": "SUCCESS"
  },
  "message": "Transaction created successfully",
  "timestamp": "2024-03-20T12:00:00.000Z"
}

9. Get Transactions

Retrieve transactions with optional filtering and sorting.

Endpoint: POST /transactions/filter

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "tenant-123",
  "authorization": "Bearer token-123"
}

Request Body Parameters (Filters)

Parameter	Type	Description
page	number	Page number (default: 1)
limit	number	Items per page (default: 10, max: 100)
transactionFilters	object	Filter by IDs, entity types, references, date range
chargeFilters	object	Filter by charge details, amounts, date range
sorting	object	Sort by field and order
includeOptions	object	Include related data (charges, metadata)

Request Body Example

{
  "page": 1,
  "limit": 10,
  "transactionFilters": {
    "customerIds": ["cust_1234567890"],
    "transactionDateRange": {
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-01-31T23:59:59Z"
    }
  },
  "sorting": {
    "sortBy": "createdAt",
    "sortOrder": "DESC"
  },
  "includeOptions": {
    "includeCharges": true
  }
}

10. Generate Invoice

Generate an invoice using the external invoice service.

Endpoint: POST /generate-invoice

Request Headers:

{
  "Content-Type": "application/json",
  "X-Tenant-Id": "tenant-123",
  "authorization": "Bearer token-123"
}

Request Body Parameters

Parameter	Required	Type	Description
templateName	Yes	string	Template name (e.g., ‘B2BInvoice’)
productId	Yes	string	Product ID
buyerCustomerId	Yes	string	Buyer Customer ID
sellerCustomerId	Yes	string	Seller Customer ID
startDate	Yes	string	Start date (YYYY-MM-DD)
endDate	Yes	string	End date (YYYY-MM-DD)

Request Body Example

{
  "templateName": "B2BInvoice",
  "productId": "SMLPYOG",
  "buyerCustomerId": "SMLPYOG000000000675615",
  "sellerCustomerId": "SMLPYOG000000000675615",
  "startDate": "2025-10-01",
  "endDate": "2025-10-13"
}

11. List Invoices

Fetch invoices from external invoice service with filters.

Endpoint: GET /invoices

Query Parameters

Parameter	Required	Description
startDate	Yes	Start date (YYYY-MM-DD)
endDate	Yes	End date (YYYY-MM-DD)
limit	No	Max items per page
page	No	Page number
productId	Yes	Product code
customerId	No	Customer ID
templateName	No	Template name
search_in_custom_vars	No	Search text

12. Get Ledger Reports

Fetch ledger reports by head.

Endpoint: GET /ledgers/reports/heads

Query Parameters

Parameter	Required	Description
customerId	Yes	Customer ID
fromDate	No	From date (ISO)
toDate	No	To date (ISO)
currency	No	Currency code
heads	No	Comma-separated head names

13. Get Profit Loss Reports

Fetch profit-loss reports.

Endpoint: GET /ledgers/reports/profit-loss

Query Parameters

Parameter	Required	Description
customerId	Yes	Customer ID
fromDate	Yes	From date (ISO)
toDate	Yes	To date (ISO)
includeBreakdown	No	Include breakdown (boolean)

14. Get Date Range Reports

Fetch date-range reports for a customer.

Endpoint: GET /ledgers/customers/:customerId/reports/date-range

Query Parameters

Parameter	Required	Description
fromDate	Yes	From date (ISO)
toDate	Yes	To date (ISO)
currency	Yes	Currency code

15. Get Tax Reports

Fetch tax reports for a customer.

Endpoint: GET /ledgers/customers/:customerId/reports/tax

Query Parameters

Parameter	Required	Description
fromDate	Yes	From date (ISO)
toDate	Yes	To date (ISO)
currency	Yes	Currency code

16. Get Ledger Summary

Fetch ledger summary for a customer.

Endpoint: GET /ledgers/customers/:customerId/summary

Query Parameters

Parameter	Required	Description
fromDate	Yes	From date (ISO)
toDate	Yes	To date (ISO)
currency	Yes	Currency code

Error Codes

Error Code	Title	Description
400	Bad Request	The request payload is invalid or missing required fields.
401	Unauthorized	Authentication token or API key is missing or invalid.
500	Internal Server Error	An unexpected error occurred on the server.

Data Models

Balance Request

id: Unique request ID
parentTenantId: Parent tenant ID
subTenantId: Sub tenant ID
walletCustomerId: Wallet customer ID
requestedAmount: Amount requested
approvedAmount: Amount approved
status: Request status (PENDING, APPROVED, REJECTED)
remarks: Request remarks
approvalRemarks: Approval remarks
rejectionReason: Rejection reason
approvedBy: User ID who approved the request
rejectedBy: User ID who rejected the request
createdAt: Creation timestamp
updatedAt: Last update timestamp

Transaction

customerId: Customer ID
entityType: Entity type (e.g., ‘order’)
referenceId: Reference ID
currency: Currency code
charges: Array of Charge objects
metadata: Array of Metadata objects

Charge

head: Charge head (e.g., ‘GST’)
amount: Charge amount
hsnOrSac: HSN or SAC code
isBillable: Boolean indicating if charge is billable
absorbedBy: Who absorbs the charge
transactionType: ‘debit’ or ‘credit’
chargedAt: Timestamp
metadata: Array of Metadata objects
breakup: Array of ChargeBreakup objects

Invoice Generation Request

templateName: Name of the invoice template
productId: Product identifier
buyerCustomerId: Customer ID of the buyer
sellerCustomerId: Customer ID of the seller
startDate: Reporting period start date
endDate: Reporting period end date

Ledger Report Query

customerId: Target customer ID
fromDate: Start date for report
toDate: End date for report
currency: Currency for values
heads: Specific ledger heads to filter (optional)