ICMA Devdocs

Introduction

The State Biller Notification API is a secure interface designed to facilitate the seamless transmission of bills and assessments from government-appointed consultants to the state’s centralized repository. This API ensures proper documentation, validation, and retrieval of assessment records while generating unique payment codes for seamless payment processing.
Key Functionalities:

Bill and Assessment Submission:
Consultants submit bills and assessments to the repository via the API using predefined rates and parameters.
Payment Code Generation:
Upon successful submission, the system generates a unique Payment Code, which is returned to the consultant for further processing.
Assessment Retrieval:
Authorized entities can retrieve submitted bills and assessments using secure API requests.
Payment Verification:
The API allows banks and payment gateways to validate and confirm payment codes before processing transactions.
Security & Compliance:
All requests are encrypted and authenticated to prevent unauthorized access.

This API enhances transparency, streamlines bill and assessment processing, and ensures secure integration between consultants, the state government, and payment institutions.
NOTE: Base URL will be provided by ICMA.

Endpoint

Method: POST
URL: BaseUrl/PDMS/api/v1/RevenueDataManagement/get-invoiceNo

Sample Request body for Single Item(JSON)

POST 
Host: staging 
Content-Type: application/json 
Authorization: Bearer (your access token)
{
  "transactionId": "1090001234",
  "payerId": "4020100206",
  "payerName": "ICMA PROFESSIONAL SERVICES",
  "payerEmail": "icma@email.com",
  "telephone": "08033012345",
  "address": "36. YEMI OLADIRAN STREET OLD BODIJA IBADAN",	
  "totalAmount": 500,
  "arrears": 0,
  "narration": "Generate invoice to process payment",
  "revenueCode": "900",
  "location": "ibadan",
  "invoiceYear": "2023",
  "platformCode": "Self",
  "raisedBy": "self",
  "raisedOn": "2025-03-20T08:19:57.253Z",
  "approvedBy": "self",
  "approvedOn": "2025-03-20T08:19:57.253Z",
  "updatePreviousInvoice": false,
  "itemCount": 1,
  "invoiceDetails": [
    {
      "revenueCode": "BMR458",
      "itemAmount": 300,
      "itemArrears": 0,
      "narration": "Renewal of Vehicle Certificate"
    },

  ]
}'

Sample Success Response for Single Item(200 OK)


{
  "succeeded": true,
  "message": "Transaction Successful For Transaction Id: 1094501884",
  "statusCode": null,
  "errors": null,
  "data": {
    "transactionId": "1094501884",
    "totalAmount": 500,
    "invoiceNo": "OYPDMS231QQ5AF",
    "invoiceDetailsResponse": [
      {
        "revenueCode": "4040065B",
        "itemAmount": 500,
        "itemInvoiceNo": "OYPDMS231QQ5AF1"
      }
    ]
  }
}

Sample Request body for Multiple Items(JSON)

POST 
Host: staging 
Content-Type: application/json 
Authorization: Bearer (your access token)
{
  "transactionId": "1090001234",
  "payerId": "4020100206",
  "payerName": "ICMA PROFESSIONAL SERVICES",
  "payerEmail": "icma@email.com",
  "telephone": "08033012345",
  "address": "36. YEMI OLADIRAN STREET OLD BODIJA IBADAN",	
  "totalAmount": 500,
  "arrears": 0,
  "narration": "Generate invoice to process payment",
  "revenueCode": "900",
  "location": "ibadan",
  "invoiceYear": "2023",
  "platformCode": "Self",
  "raisedBy": "self",
  "raisedOn": "2025-03-20T08:19:57.253Z",
  "approvedBy": "self",
  "approvedOn": "2025-03-20T08:19:57.253Z",
  "updatePreviousInvoice": false,
  "itemCount": 2,
  "invoiceDetails": [
    {
      "revenueCode": "BMR458",
      "itemAmount": 300,
      "itemArrears": 0,
      "narration": "Renewal of Vehicle Certificate"
    },
{
      "revenueCode": "4040064",
      "itemAmount": 200,
      "itemArrears": 0,
      "narration": "For Sales of Boarded Vehicles"
    }

  ]
}'

Sample Success Response for Multiple Items(200 OK)


{
  "succeeded": true,
  "message": "Transaction Successful For Transaction Id: 1090001234",
  "statusCode": null,
  "errors": null,
  "data": {
    "transactionId": "1090001234",
    "totalAmount": 500,
    "invoiceNo": "OYPDMS239EE132",
    "invoiceDetailsResponse": [
      {
        "revenueCode": "BMR458",
        "itemAmount": 300,
        "itemInvoiceNo": "OYPDMS239EE1321"
      },
      {
        "revenueCode": "4040064",
        "itemAmount": 200,
        "itemInvoiceNo": "OYPDMS239EE1322"
      }
    ]
  }
}

400 Bad Request

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "additionalProp1": "string",
  "additionalProp2": "string",
  "additionalProp3": "string"
}

401 Unauthorized

{
  "Succeeded": false,
  "Message": "You are not Authorized",
  "StatusCode": null,
  "Errors": [],
  "Data": null

}