Collection

Records the payment in the system

post

This API generates a transaction number and persists the payment details. The payment information is then pushed to queue for further processing.

Body

Payment Request with Request Info.

Responses

201

Payment created sucessfully.

application/json

400

Invalid input.

post

HTTPcURLJavaScriptPython

POST /payments/_create HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 1824

{
  "requestInfo": {
    "apiId": "text",
    "ver": "text",
    "ts": 1,
    "action": "text",
    "did": "text",
    "key": "text",
    "msgId": "text",
    "requesterId": "text",
    "authToken": "text"
  },
  "Payment": {
    "tenantId": "text",
    "id": "text",
    "totalDue": 1,
    "totalAmountPaid": 1,
    "transactionNumber": "text",
    "transactionDate": 1,
    "paymentMode": "CASH",
    "instrumentDate": 1,
    "instrumentNumber": "text",
    "instrumentStatus": "APPROVED",
    "ifscCode": "text",
    "additionalDetails": {},
    "paymentDetails": [
      {
        "id": "text",
        "tenantId": "text",
        "totalDue": 1,
        "totalAmountPaid": 1,
        "manualReceiptNumber": "text",
        "receiptNumber": "text",
        "receiptType": "text",
        "receiptDate": 1,
        "businessService": "text",
        "billId": "text",
        "bill": {
          "paidBy": "text",
          "mobileNumber": "text",
          "payerName": "text",
          "payerAddress": "text",
          "payerEmail": "text",
          "payerId": "text",
          "status": "ACTIVE",
          "reasonForCancellation": "text",
          "isCancelled": true,
          "additionalDetails": {},
          "collectionModesNotAllowed": [
            "text"
          ],
          "partPaymentAllowed": true,
          "isAdvanceAllowed": true,
          "minimumAmountToBePaid": 1,
          "businessService": "text",
          "totalAmount": 1,
          "consumerCode": "text",
          "billNumber": "text",
          "billDate": 1,
          "billDetails": [
            {
              "id": "text",
              "tenantId": "text",
              "demandId": "text",
              "billId": "text",
              "amount": 1,
              "amountPaid": 1,
              "fromPeriod": 1,
              "toPeriod": 1,
              "receiptDate": "2025-05-15",
              "receiptType": [
                "ADHOC"
              ],
              "channel": "text",
              "voucherHeader": null,
              "boundary": [
                "text"
              ],
              "manualReceiptNumber": "text",
              "manualReceiptDate": 1,
              "collectionType": "text",
              "billDescription": "text",
              "expiryDate": 1,
              "displayMessage": "text",
              "cancellationRemarks": "text",
              "billAccountDetails": [
                {
                  "id": "text",
                  "tenantId": "text",
                  "billDetailId": "text",
                  "demandDetailId": "text",
                  "order": 1,
                  "amount": 1,
                  "adjustedAmount": 1,
                  "taxHeadCode": "text",
                  "additionalDetails": {},
                  "purpose": "ARREAR"
                }
              ]
            }
          ]
        },
        "additionalDetails": 1
      }
    ],
    "paidBy": "text",
    "mobileNumber": "text",
    "payerName": "text",
    "payerAddress": "text",
    "payerEmail": "text",
    "payerId": "text",
    "paymentStatus": "NEW"
  }
}

{
  "responseInfo": {
    "apiId": "text",
    "ver": "text",
    "ts": 1,
    "resMsgId": "text",
    "msgId": "text",
    "status": "SUCCESSFUL"
  },
  "Payment": {
    "tenantId": "text",
    "id": "text",
    "totalDue": 1,
    "totalAmountPaid": 1,
    "transactionNumber": "text",
    "transactionDate": 1,
    "paymentMode": "CASH",
    "instrumentDate": 1,
    "instrumentNumber": "text",
    "instrumentStatus": "APPROVED",
    "ifscCode": "text",
    "additionalDetails": {},
    "paymentDetails": [
      {
        "id": "text",
        "tenantId": "text",
        "totalDue": 1,
        "totalAmountPaid": 1,
        "manualReceiptNumber": "text",
        "receiptNumber": "text",
        "receiptType": "text",
        "receiptDate": 1,
        "businessService": "text",
        "billId": "text",
        "bill": {
          "paidBy": "text",
          "mobileNumber": "text",
          "payerName": "text",
          "payerAddress": "text",
          "payerEmail": "text",
          "payerId": "text",
          "status": "ACTIVE",
          "reasonForCancellation": "text",
          "isCancelled": true,
          "additionalDetails": {},
          "collectionModesNotAllowed": [
            "text"
          ],
          "partPaymentAllowed": true,
          "isAdvanceAllowed": true,
          "minimumAmountToBePaid": 1,
          "businessService": "text",
          "totalAmount": 1,
          "consumerCode": "text",
          "billNumber": "text",
          "billDate": 1,
          "billDetails": [
            {
              "id": "text",
              "tenantId": "text",
              "demandId": "text",
              "billId": "text",
              "amount": 1,
              "amountPaid": 1,
              "fromPeriod": 1,
              "toPeriod": 1,
              "receiptDate": "2025-05-15",
              "receiptType": [
                "ADHOC"
              ],
              "channel": "text",
              "voucherHeader": null,
              "boundary": [
                "text"
              ],
              "manualReceiptNumber": "text",
              "manualReceiptDate": 1,
              "collectionType": "text",
              "billDescription": "text",
              "expiryDate": 1,
              "displayMessage": "text",
              "cancellationRemarks": "text",
              "billAccountDetails": [
                {
                  "id": "text",
                  "tenantId": "text",
                  "billDetailId": "text",
                  "demandDetailId": "text",
                  "order": 1,
                  "amount": 1,
                  "adjustedAmount": 1,
                  "taxHeadCode": "text",
                  "additionalDetails": {},
                  "purpose": "ARREAR",
                  "auditDetails": {
                    "createdBy": "text",
                    "lastModifiedBy": "text",
                    "createdTime": 1,
                    "lastModifiedTime": 1
                  }
                }
              ]
            }
          ]
        },
        "additionalDetails": 1,
        "auditDetails": {
          "createdBy": "text",
          "lastModifiedBy": "text",
          "createdTime": 1,
          "lastModifiedTime": 1
        }
      }
    ],
    "paidBy": "text",
    "mobileNumber": "text",
    "payerName": "text",
    "payerAddress": "text",
    "payerEmail": "text",
    "payerId": "text",
    "paymentStatus": "NEW",
    "auditDetails": {
      "createdBy": "text",
      "lastModifiedBy": "text",
      "createdTime": 1,
      "lastModifiedTime": 1
    }
  }
}

Performs workflow actions on the payment

post

The API can perform the following operations:

1. Cancellation of receipts in open state.
2. Remittance of instruments such as Cash, Cheque, DD .
3. Dishonoring of instruments such as Cheque, DD.

Body

Payment Workflow Request with Request Info.

Responses

201

Payment status updated sucessfully.

application/json

400

Invalid input.

post

HTTPcURLJavaScriptPython

POST /payments/_workflow HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 254

{
  "requestInfo": {
    "apiId": "text",
    "ver": "text",
    "ts": 1,
    "action": "text",
    "did": "text",
    "key": "text",
    "msgId": "text",
    "requesterId": "text",
    "authToken": "text"
  },
  "Payment": {
    "paymentId": "text",
    "action": "CANCEL",
    "tenantId": "text",
    "reason": "text",
    "additionalDetails": 1
  }
}

{
  "responseInfo": {
    "apiId": "text",
    "ver": "text",
    "ts": 1,
    "resMsgId": "text",
    "msgId": "text",
    "status": "SUCCESSFUL"
  },
  "Payment": {
    "tenantId": "text",
    "id": "text",
    "totalDue": 1,
    "totalAmountPaid": 1,
    "transactionNumber": "text",
    "transactionDate": 1,
    "paymentMode": "CASH",
    "instrumentDate": 1,
    "instrumentNumber": "text",
    "instrumentStatus": "APPROVED",
    "ifscCode": "text",
    "additionalDetails": {},
    "paymentDetails": [
      {
        "id": "text",
        "tenantId": "text",
        "totalDue": 1,
        "totalAmountPaid": 1,
        "manualReceiptNumber": "text",
        "receiptNumber": "text",
        "receiptType": "text",
        "receiptDate": 1,
        "businessService": "text",
        "billId": "text",
        "bill": {
          "paidBy": "text",
          "mobileNumber": "text",
          "payerName": "text",
          "payerAddress": "text",
          "payerEmail": "text",
          "payerId": "text",
          "status": "ACTIVE",
          "reasonForCancellation": "text",
          "isCancelled": true,
          "additionalDetails": {},
          "collectionModesNotAllowed": [
            "text"
          ],
          "partPaymentAllowed": true,
          "isAdvanceAllowed": true,
          "minimumAmountToBePaid": 1,
          "businessService": "text",
          "totalAmount": 1,
          "consumerCode": "text",
          "billNumber": "text",
          "billDate": 1,
          "billDetails": [
            {
              "id": "text",
              "tenantId": "text",
              "demandId": "text",
              "billId": "text",
              "amount": 1,
              "amountPaid": 1,
              "fromPeriod": 1,
              "toPeriod": 1,
              "receiptDate": "2025-05-15",
              "receiptType": [
                "ADHOC"
              ],
              "channel": "text",
              "voucherHeader": null,
              "boundary": [
                "text"
              ],
              "manualReceiptNumber": "text",
              "manualReceiptDate": 1,
              "collectionType": "text",
              "billDescription": "text",
              "expiryDate": 1,
              "displayMessage": "text",
              "cancellationRemarks": "text",
              "billAccountDetails": [
                {
                  "id": "text",
                  "tenantId": "text",
                  "billDetailId": "text",
                  "demandDetailId": "text",
                  "order": 1,
                  "amount": 1,
                  "adjustedAmount": 1,
                  "taxHeadCode": "text",
                  "additionalDetails": {},
                  "purpose": "ARREAR",
                  "auditDetails": {
                    "createdBy": "text",
                    "lastModifiedBy": "text",
                    "createdTime": 1,
                    "lastModifiedTime": 1
                  }
                }
              ]
            }
          ]
        },
        "additionalDetails": 1,
        "auditDetails": {
          "createdBy": "text",
          "lastModifiedBy": "text",
          "createdTime": 1,
          "lastModifiedTime": 1
        }
      }
    ],
    "paidBy": "text",
    "mobileNumber": "text",
    "payerName": "text",
    "payerAddress": "text",
    "payerEmail": "text",
    "payerId": "text",
    "paymentStatus": "NEW",
    "auditDetails": {
      "createdBy": "text",
      "lastModifiedBy": "text",
      "createdTime": 1,
      "lastModifiedTime": 1
    }
  }
}

Validates the PaymentRequest

post

The API runs the following set of validations on the payment request.

1. Bill is present and is in valid state
2. Amount paid is positive integer
3. Zero amount payment is allowed only if bill amount is zero
4. Payment mode is allowed
5. Partial Payment is allowed based on the businessService
6. Advance payment is allowed based on the businessService

Body

Payment Request with Request Info.

Responses

201

Payment info validated sucessfully.

application/json

400

Invalid input.

post

HTTPcURLJavaScriptPython

POST /payments/_validate HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 1824

{
  "requestInfo": {
    "apiId": "text",
    "ver": "text",
    "ts": 1,
    "action": "text",
    "did": "text",
    "key": "text",
    "msgId": "text",
    "requesterId": "text",
    "authToken": "text"
  },
  "Payment": {
    "tenantId": "text",
    "id": "text",
    "totalDue": 1,
    "totalAmountPaid": 1,
    "transactionNumber": "text",
    "transactionDate": 1,
    "paymentMode": "CASH",
    "instrumentDate": 1,
    "instrumentNumber": "text",
    "instrumentStatus": "APPROVED",
    "ifscCode": "text",
    "additionalDetails": {},
    "paymentDetails": [
      {
        "id": "text",
        "tenantId": "text",
        "totalDue": 1,
        "totalAmountPaid": 1,
        "manualReceiptNumber": "text",
        "receiptNumber": "text",
        "receiptType": "text",
        "receiptDate": 1,
        "businessService": "text",
        "billId": "text",
        "bill": {
          "paidBy": "text",
          "mobileNumber": "text",
          "payerName": "text",
          "payerAddress": "text",
          "payerEmail": "text",
          "payerId": "text",
          "status": "ACTIVE",
          "reasonForCancellation": "text",
          "isCancelled": true,
          "additionalDetails": {},
          "collectionModesNotAllowed": [
            "text"
          ],
          "partPaymentAllowed": true,
          "isAdvanceAllowed": true,
          "minimumAmountToBePaid": 1,
          "businessService": "text",
          "totalAmount": 1,
          "consumerCode": "text",
          "billNumber": "text",
          "billDate": 1,
          "billDetails": [
            {
              "id": "text",
              "tenantId": "text",
              "demandId": "text",
              "billId": "text",
              "amount": 1,
              "amountPaid": 1,
              "fromPeriod": 1,
              "toPeriod": 1,
              "receiptDate": "2025-05-15",
              "receiptType": [
                "ADHOC"
              ],
              "channel": "text",
              "voucherHeader": null,
              "boundary": [
                "text"
              ],
              "manualReceiptNumber": "text",
              "manualReceiptDate": 1,
              "collectionType": "text",
              "billDescription": "text",
              "expiryDate": 1,
              "displayMessage": "text",
              "cancellationRemarks": "text",
              "billAccountDetails": [
                {
                  "id": "text",
                  "tenantId": "text",
                  "billDetailId": "text",
                  "demandDetailId": "text",
                  "order": 1,
                  "amount": 1,
                  "adjustedAmount": 1,
                  "taxHeadCode": "text",
                  "additionalDetails": {},
                  "purpose": "ARREAR"
                }
              ]
            }
          ]
        },
        "additionalDetails": 1
      }
    ],
    "paidBy": "text",
    "mobileNumber": "text",
    "payerName": "text",
    "payerAddress": "text",
    "payerEmail": "text",
    "payerId": "text",
    "paymentStatus": "NEW"
  }
}

{
  "responseInfo": {
    "apiId": "text",
    "ver": "text",
    "ts": 1,
    "resMsgId": "text",
    "msgId": "text",
    "status": "SUCCESSFUL"
  },
  "Payment": {
    "tenantId": "text",
    "id": "text",
    "totalDue": 1,
    "totalAmountPaid": 1,
    "transactionNumber": "text",
    "transactionDate": 1,
    "paymentMode": "CASH",
    "instrumentDate": 1,
    "instrumentNumber": "text",
    "instrumentStatus": "APPROVED",
    "ifscCode": "text",
    "additionalDetails": {},
    "paymentDetails": [
      {
        "id": "text",
        "tenantId": "text",
        "totalDue": 1,
        "totalAmountPaid": 1,
        "manualReceiptNumber": "text",
        "receiptNumber": "text",
        "receiptType": "text",
        "receiptDate": 1,
        "businessService": "text",
        "billId": "text",
        "bill": {
          "paidBy": "text",
          "mobileNumber": "text",
          "payerName": "text",
          "payerAddress": "text",
          "payerEmail": "text",
          "payerId": "text",
          "status": "ACTIVE",
          "reasonForCancellation": "text",
          "isCancelled": true,
          "additionalDetails": {},
          "collectionModesNotAllowed": [
            "text"
          ],
          "partPaymentAllowed": true,
          "isAdvanceAllowed": true,
          "minimumAmountToBePaid": 1,
          "businessService": "text",
          "totalAmount": 1,
          "consumerCode": "text",
          "billNumber": "text",
          "billDate": 1,
          "billDetails": [
            {
              "id": "text",
              "tenantId": "text",
              "demandId": "text",
              "billId": "text",
              "amount": 1,
              "amountPaid": 1,
              "fromPeriod": 1,
              "toPeriod": 1,
              "receiptDate": "2025-05-15",
              "receiptType": [
                "ADHOC"
              ],
              "channel": "text",
              "voucherHeader": null,
              "boundary": [
                "text"
              ],
              "manualReceiptNumber": "text",
              "manualReceiptDate": 1,
              "collectionType": "text",
              "billDescription": "text",
              "expiryDate": 1,
              "displayMessage": "text",
              "cancellationRemarks": "text",
              "billAccountDetails": [
                {
                  "id": "text",
                  "tenantId": "text",
                  "billDetailId": "text",
                  "demandDetailId": "text",
                  "order": 1,
                  "amount": 1,
                  "adjustedAmount": 1,
                  "taxHeadCode": "text",
                  "additionalDetails": {},
                  "purpose": "ARREAR",
                  "auditDetails": {
                    "createdBy": "text",
                    "lastModifiedBy": "text",
                    "createdTime": 1,
                    "lastModifiedTime": 1
                  }
                }
              ]
            }
          ]
        },
        "additionalDetails": 1,
        "auditDetails": {
          "createdBy": "text",
          "lastModifiedBy": "text",
          "createdTime": 1,
          "lastModifiedTime": 1
        }
      }
    ],
    "paidBy": "text",
    "mobileNumber": "text",
    "payerName": "text",
    "payerAddress": "text",
    "payerEmail": "text",
    "payerId": "text",
    "paymentStatus": "NEW",
    "auditDetails": {
      "createdBy": "text",
      "lastModifiedBy": "text",
      "createdTime": 1,
      "lastModifiedTime": 1
    }
  }
}

Searches the Payment based on search criteria

post

API to search payments based on search parameters like consumerCode, mobileNumber, transactionNumber etc.

body

requestInfoanyOptional

Parameter to carry Request metadata in the request body

Query parameters

tenantIdanyRequired

Unique id for a tenant.

pageSizeanyOptional

Number of records returned.

pageNumberanyOptional

Page number

sortanyOptional

Receipt results will be sorted by receiptnumber ascending by default.

idsstring[]Optional

Payment Ids.

consumerCodesstring[]Optional

Consumer Code .

receiptNumbersstring[]Optional

List of receipt numbers.

fromDateinteger · int64Optional

Transaction date, here search will happen as Transaction date is greater or equal to given fromDate.

toDateinteger · int64Optional

Transaction date, here search will happen as Transaction date is lesser or equal to given toDate.

statusstring[]Optional

Search based on the status of the Payment.

instrumentStatusstring[]Optional

Search based on the status of the instrument.

paymentModesstring[]Optional

Search based on the Payment type such as cash, cheque, dd etc.

payerIdsstring[]Optional

The ids of the payer

transactionNumberstring · max: 64Optional

Unique tansaction number for multiple receipts created in one transaction.

mobileNumberstring · max: 64Optional

Unique tansaction number for multiple receipts created in one transaction.

billIdsstring[]Optional

List of bill ids to search receipts.Business details code is mandatory for searching with this criteria.

Responses

200

Successful response

application/json

400

Invalid input.

application/json

post

HTTPcURLJavaScriptPython

POST /payments/_search?tenantId=null HTTP/1.1
Host: 
Accept: */*

[
  {
    "responseInfo": {
      "apiId": "text",
      "ver": "text",
      "ts": 1,
      "resMsgId": "text",
      "msgId": "text",
      "status": "SUCCESSFUL"
    },
    "Payment": {
      "tenantId": "text",
      "id": "text",
      "totalDue": 1,
      "totalAmountPaid": 1,
      "transactionNumber": "text",
      "transactionDate": 1,
      "paymentMode": "CASH",
      "instrumentDate": 1,
      "instrumentNumber": "text",
      "instrumentStatus": "APPROVED",
      "ifscCode": "text",
      "additionalDetails": {},
      "paymentDetails": [
        {
          "id": "text",
          "tenantId": "text",
          "totalDue": 1,
          "totalAmountPaid": 1,
          "manualReceiptNumber": "text",
          "receiptNumber": "text",
          "receiptType": "text",
          "receiptDate": 1,
          "businessService": "text",
          "billId": "text",
          "bill": {
            "paidBy": "text",
            "mobileNumber": "text",
            "payerName": "text",
            "payerAddress": "text",
            "payerEmail": "text",
            "payerId": "text",
            "status": "ACTIVE",
            "reasonForCancellation": "text",
            "isCancelled": true,
            "additionalDetails": {},
            "collectionModesNotAllowed": [
              "text"
            ],
            "partPaymentAllowed": true,
            "isAdvanceAllowed": true,
            "minimumAmountToBePaid": 1,
            "businessService": "text",
            "totalAmount": 1,
            "consumerCode": "text",
            "billNumber": "text",
            "billDate": 1,
            "billDetails": [
              {
                "id": "text",
                "tenantId": "text",
                "demandId": "text",
                "billId": "text",
                "amount": 1,
                "amountPaid": 1,
                "fromPeriod": 1,
                "toPeriod": 1,
                "receiptDate": "2025-05-15",
                "receiptType": [
                  "ADHOC"
                ],
                "channel": "text",
                "voucherHeader": null,
                "boundary": [
                  "text"
                ],
                "manualReceiptNumber": "text",
                "manualReceiptDate": 1,
                "collectionType": "text",
                "billDescription": "text",
                "expiryDate": 1,
                "displayMessage": "text",
                "cancellationRemarks": "text",
                "billAccountDetails": [
                  {
                    "id": "text",
                    "tenantId": "text",
                    "billDetailId": "text",
                    "demandDetailId": "text",
                    "order": 1,
                    "amount": 1,
                    "adjustedAmount": 1,
                    "taxHeadCode": "text",
                    "additionalDetails": {},
                    "purpose": "ARREAR",
                    "auditDetails": {
                      "createdBy": "text",
                      "lastModifiedBy": "text",
                      "createdTime": 1,
                      "lastModifiedTime": 1
                    }
                  }
                ]
              }
            ]
          },
          "additionalDetails": 1,
          "auditDetails": {
            "createdBy": "text",
            "lastModifiedBy": "text",
            "createdTime": 1,
            "lastModifiedTime": 1
          }
        }
      ],
      "paidBy": "text",
      "mobileNumber": "text",
      "payerName": "text",
      "payerAddress": "text",
      "payerEmail": "text",
      "payerId": "text",
      "paymentStatus": "NEW",
      "auditDetails": {
        "createdBy": "text",
        "lastModifiedBy": "text",
        "createdTime": 1,
        "lastModifiedTime": 1
      }
    }
  }
]