Program Service

Overview

The Program Service is constructed using iFix specifications and serves as an extensive platform aimed at simplifying program creation, sanction management, fund allocation, and disbursement execution. It equips organizations with essential tools to effectively oversee available funds and guarantee transparent and accountable distribution to designated beneficiaries.

Functional Overview

Funds Summary

1. IFMS adapter manages funds summary based on the head of accounts and SSU codes. It creates sanctions for each head of accounts and SSU details based on ULB tenant ID.

2. There are three types of transactions that can be received from the JIT VA API -

   • Initial Allotment - A new sanction will be created only if AllotmentTxnType is Initial Allotment.

   • Additional allotment - For this type of transaction it will update the amount of existing sanction.

   • Allotment withdrawal - It deducts the transaction amount from the sanction for this type of transaction.

Payment Instructions

• When a bill is approved this service creates payment using the expense service.

• There are consumers who keep listening to the payment create Kafka topic and generate payment instructions (PI) using payment and bill details and post the PI to the IFMS system using JIT API.

• A new PI will be generated when enough funds are available for any head of accounts for that tenantId.

• Before posting the PI there were multiple enrichments like bank account details, org and individual details, etc.

• After creating the PI it deducts the available balance from the funds summary.

• If a PI is created for any payment then the user can not generate a PI again till the PI fails.

• It keeps a log of each status call of PI and saves it in the DB

Program Service takes care of Program, Sanction, Allocation and Disbursement using the standardized exchange interface.

iFIX API Specification

API spec YAML is here. Click below to view it in Swagger Editor.

Swagger Editor

Implemented API Specifications

Base Path: /program-service/

API Contract Link

API spec YAML is here. Click below to view it in Swagger Editor.

Swagger Editor

APIs

Create programs

Enables exchange of program related messages

POST/program-service/v1/program/_create

Body

application/json

signatureMsgSignature (string)

Signature of {header}+{message} body verified using sender's signing public key

header*all of

message*ProgramDetails (all of)

Response

401403500default

HTTP layer error details

Body

application/json

errorsany

Request

JavaScriptCurl

const response = await fetch('/program-service/v1/program/_create', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "header": {
        "message_id": "123",
        "message_ts": 1708428280,
        "sender_id": "program@https://spp.example.org",
        "receiver_id": "program@https://pymts.example.org"
      },
      "message": {
        "location_code": "pb.jalandhar,dwss",
        "name": "Community Development Initiative",
        "description": "Empowering local communities through sustainable development projects.",
        "start_date": 1672531200
      }
    }),
});
const data = await response.json();

Response

{}

Update created programs

Enables exchange of program related messages

POST/program-service/v1/program/_update

Body

application/json

signatureMsgSignature (string)

Signature of {header}+{message} body verified using sender's signing public key

header*all of

message*ProgramDetails (all of)

Response

401403500default

HTTP layer error details

Body

application/json

errorsany

Request

JavaScriptCurl

const response = await fetch('/program-service/v1/program/_update', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "header": {
        "message_id": "123",
        "message_ts": 1708428280,
        "sender_id": "program@https://spp.example.org",
        "receiver_id": "program@https://pymts.example.org"
      },
      "message": {
        "location_code": "pb.jalandhar,dwss",
        "name": "Community Development Initiative",
        "description": "Empowering local communities through sustainable development projects.",
        "start_date": 1672531200
      }
    }),
});
const data = await response.json();

Response

{}

Search programs by query

Enables search of program

POST/program-service/v1/program/_search

Body

application/json

signatureMsgSignature (string)

Signature of {header}+{message} body verified using sender's signing public key

header*all of

message*all of

Response

401403500default

HTTP layer error details

Body

application/json

errorsany

Request

JavaScriptCurl

const response = await fetch('/program-service/v1/program/_search', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "header": {
        "message_id": "123",
        "message_ts": 1708428280,
        "sender_id": "program@https://spp.example.org",
        "receiver_id": "program@https://pymts.example.org"
      },
      "message": {
        "location_code": "pg.citya"
      }
    }),
});
const data = await response.json();

Response

{}

Update program after create response

Enables exchange of program related messages

POST/program-service/v1/on-program/_create

Body

application/json

signatureMsgSignature (string)

Signature of {header}+{message} body verified using sender's signing public key

header*all of

message*all of

Response

401403500default

HTTP layer error details

Body

application/json

errorsany

Request

JavaScriptCurl

const response = await fetch('/program-service/v1/on-program/_create', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "header": {
        "message_id": "123",
        "message_ts": 1708428280,
        "sender_id": "program@https://spp.example.org",
        "receiver_id": "program@https://pymts.example.org"
      },
      "message": {
        "location_code": "pb.jalandhar,dwss",
        "name": "Community Development Initiative",
        "description": "Empowering local communities through sustainable development projects.",
        "start_date": 1672531200
      }
    }),
});
const data = await response.json();

Response

{}

Update program after update response

Enables exchange of program related messages

POST/program-service/v1/on-program/_update

Body

application/json

signatureMsgSignature (string)

Signature of {header}+{message} body verified using sender's signing public key

header*all of

message*all of

Response

401403500default

HTTP layer error details

Body

application/json

errorsany

Request

JavaScriptCurl

const response = await fetch('/program-service/v1/on-program/_update', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "header": {
        "message_id": "123",
        "message_ts": 1708428280,
        "sender_id": "program@https://spp.example.org",
        "receiver_id": "program@https://pymts.example.org"
      },
      "message": {
        "location_code": "pb.jalandhar,dwss",
        "name": "Community Development Initiative",
        "description": "Empowering local communities through sustainable development projects.",
        "start_date": 1672531200
      }
    }),
});
const data = await response.json();

Response

{}

Create sanctions in program service

Enables creation of sanctions if not created in the system.

POST/program-service/v1/on-sanction/_create

Body

application/json

signatureMsgSignature (string)

Signature of {header}+{message} body verified using sender's signing public key

header*all of

message*SanctionDetails (all of)

Response

401403500default

HTTP layer error details

Body

application/json

errorsany

Request

JavaScriptCurl

const response = await fetch('/program-service/v1/on-sanction/_create', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "header": {
        "message_id": "123",
        "message_ts": 1708428280,
        "sender_id": "program@https://spp.example.org",
        "receiver_id": "program@https://pymts.example.org"
      },
      "message": {
        "location_code": "pb.jalandhar,dwss",
        "program_code": "PORG/2023-24/PG.CITYA/00001"
      }
    }),
});
const data = await response.json();

Response

{}

Update created sanciton details

Enables to udpate sanction details like status, remaining fields will be immutable

POST/program-service/v1/on-sanction/_update

Body

application/json

signatureMsgSignature (string)

Signature of {header}+{message} body verified using sender's signing public key

header*all of

message*SanctionDetails (all of)

Response

401403500default

HTTP layer error details

Body

application/json

errorsany

Request

JavaScriptCurl

const response = await fetch('/program-service/v1/on-sanction/_update', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "header": {
        "message_id": "123",
        "message_ts": 1708428280,
        "sender_id": "program@https://spp.example.org",
        "receiver_id": "program@https://pymts.example.org"
      },
      "message": {
        "location_code": "pb.jalandhar,dwss",
        "program_code": "PORG/2023-24/PG.CITYA/00001"
      }
    }),
});
const data = await response.json();

Response

{}

Search Sanction details

Search sanciton by query and return the response

POST/program-service/v1/sanction/_search

Body

application/json

signatureMsgSignature (string)

Signature of {header}+{message} body verified using sender's signing public key

header*all of

message*all of

Response

401403500default

HTTP layer error details

Body

application/json

errorsany

Request

JavaScriptCurl

const response = await fetch('/program-service/v1/sanction/_search', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "header": {
        "message_id": "123",
        "message_ts": 1708428280,
        "sender_id": "program@https://spp.example.org",
        "receiver_id": "program@https://pymts.example.org"
      },
      "message": {
        "location_code": "text"
      }
    }),
});
const data = await response.json();

Response

{}

Callback after allocation/_create

Update created allocation if exists or create new

POST/program-service/v1/on-allocation/_create

Body

application/json

signatureMsgSignature (string)

Signature of {header}+{message} body verified using sender's signing public key

header*all of

message*AllocationDetails (all of)

Response

401403500default

HTTP layer error details

Body

application/json

errorsany

Request

JavaScriptCurl

const response = await fetch('/program-service/v1/on-allocation/_create', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "header": {
        "message_id": "123",
        "message_ts": 1708428280,
        "sender_id": "program@https://spp.example.org",
        "receiver_id": "program@https://pymts.example.org"
      },
      "message": {
        "location_code": "pb.jalandhar,dwss",
        "sanction_id": "251c51eb-e970-4e01-a99a-70136c47a934",
        "program_code": "PORG/2023-24/PG.CITYA/00001",
        "net_amount": 0,
        "gross_amount": 0
      }
    }),
});
const data = await response.json();

Response

{}

Request to update allocation

Updated status of create disburse request.

POST/program-service/v1/on-allocation/_update

Body

application/json

signatureMsgSignature (string)

Signature of {header}+{message} body verified using sender's signing public key

header*all of

message*AllocationDetails (all of)

Response

401403500default

HTTP layer error details

Body

application/json

errorsany

Request

JavaScriptCurl

const response = await fetch('/program-service/v1/on-allocation/_update', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "header": {
        "message_id": "123",
        "message_ts": 1708428280,
        "sender_id": "program@https://spp.example.org",
        "receiver_id": "program@https://pymts.example.org"
      },
      "message": {
        "location_code": "pb.jalandhar,dwss",
        "sanction_id": "251c51eb-e970-4e01-a99a-70136c47a934",
        "program_code": "PORG/2023-24/PG.CITYA/00001",
        "net_amount": 0,
        "gross_amount": 0
      }
    }),
});
const data = await response.json();

Response

{}

Search allocation details

Search allocation by query and return the response

POST/program-service/v1/allocation/_search

Body

application/json

signatureMsgSignature (string)

Signature of {header}+{message} body verified using sender's signing public key

header*all of

message*all of

Response

401403500default

HTTP layer error details

Body

application/json

errorsany

Request

JavaScriptCurl

const response = await fetch('/program-service/v1/allocation/_search', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "header": {
        "message_id": "123",
        "message_ts": 1708428280,
        "sender_id": "program@https://spp.example.org",
        "receiver_id": "program@https://pymts.example.org"
      },
      "message": {
        "location_code": "text"
      }
    }),
});
const data = await response.json();

Response

{}

Initiate payment request

Create new disbursement request to initiate payment.

POST/program-service/v1/disburse/_create

Body

application/json

signatureMsgSignature (string)

Signature of {header}+{message} body verified using sender's signing public key

header*all of

message*all of

Response

401403500default

HTTP layer error details

Body

application/json

errorsany

Request

JavaScriptCurl

const response = await fetch('/program-service/v1/disburse/_create', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "header": {
        "message_id": "123",
        "message_ts": 1708428280,
        "sender_id": "program@https://spp.example.org",
        "receiver_id": "program@https://pymts.example.org"
      },
      "message": {
        "target_id": "EP/0/2023-24/08/14/000267, 251c51eb-e970-4e01-a99a-70136c47a934",
        "location_code": "pb.jalandhar,dwss",
        "program_code": "PORG/2023-24/PG.CITYA/00001",
        "individual": {
          "name": "text",
          "phone": "text",
          "address": "text"
        },
        "account_code": "1234567890@SBIN0003491",
        "net_amount": 1000,
        "gross_amount": 1000
      }
    }),
});
const data = await response.json();

Response

{}

Search created disbursements

Return disbursements based on query

POST/program-service/v1/disburse/_search

Body

application/json

header*all of

message*all of

Response

401403500default

HTTP layer error details

Body

application/json

errorsany

Request

JavaScriptCurl

const response = await fetch('/program-service/v1/disburse/_search', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "header": {
        "message_id": "123",
        "message_ts": 1708428280,
        "sender_id": "program@https://spp.example.org",
        "receiver_id": "program@https://pymts.example.org"
      },
      "message": {
        "location_code": "text"
      }
    }),
});
const data = await response.json();

Response

{}

Updated status of create disburse request

Updated status of create disburse request

POST/program-service/v1/on-disburse/_create

Body

application/json

signatureMsgSignature (string)

Signature of {header}+{message} body verified using sender's signing public key

header*all of

message*all of

Response

401403500default

HTTP layer error details

Body

application/json

errorsany

Request

JavaScriptCurl

const response = await fetch('/program-service/v1/on-disburse/_create', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "header": {
        "message_id": "123",
        "message_ts": 1708428280,
        "sender_id": "program@https://spp.example.org",
        "receiver_id": "program@https://pymts.example.org"
      },
      "message": {
        "target_id": "EP/0/2023-24/08/14/000267, 251c51eb-e970-4e01-a99a-70136c47a934",
        "location_code": "pb.jalandhar,dwss",
        "program_code": "PORG/2023-24/PG.CITYA/00001",
        "individual": {
          "name": "text",
          "phone": "text",
          "address": "text"
        },
        "account_code": "1234567890@SBIN0003491",
        "net_amount": 1000,
        "gross_amount": 1000
      }
    }),
});
const data = await response.json();

Response

{}

Updated status of create disburse request

Enables exchange of disburse related messages

POST/program-service/v1/on-disburse/_update

Body

application/json

signatureMsgSignature (string)

Signature of {header}+{message} body verified using sender's signing public key

header*all of

message*all of

Response

401403500default

HTTP layer error details

Body

application/json

errorsany

Request

JavaScriptCurl

const response = await fetch('/program-service/v1/on-disburse/_update', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "header": {
        "message_id": "123",
        "message_ts": 1708428280,
        "sender_id": "program@https://spp.example.org",
        "receiver_id": "program@https://pymts.example.org"
      },
      "message": {
        "target_id": "EP/0/2023-24/08/14/000267, 251c51eb-e970-4e01-a99a-70136c47a934",
        "location_code": "pb.jalandhar,dwss",
        "program_code": "PORG/2023-24/PG.CITYA/00001",
        "individual": {
          "name": "text",
          "phone": "text",
          "address": "text"
        },
        "account_code": "1234567890@SBIN0003491",
        "net_amount": 1000,
        "gross_amount": 1000
      }
    }),
});
const data = await response.json();

Response

{}

Data Model

DB Schema

Web Sequence Diagrams

Create Program

Postman Collections

TBD