openapi: 3.0.0
info:
  title: Program Service
  description: >
    Program service

  version: 1.0.0
  contact:
    name: eGov Foundation
    email: contact@egovernments.org
  license:
    name: MIT License
    url: https://opensource.org/license/mit/
externalDocs:
  description: DIGIT Platform
  url: https://core.digit.org
servers:
- url: /program-service/v1
paths:
  # Program requests -----------------------------------------
  /program/_create:
    post:
      tags:
        - Program
      summary: Create programs
      description: Enables exchange of program related messages
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  $ref: '#/components/schemas/MsgSignature'
                header:
                  allOf:
                    - $ref: '#/components/schemas/MsgHeader'
                    - properties:
                        action:
                          enum:
                            - create
                message:
                  $ref: '#/components/schemas/ProgramDetails'
              required:
                - header
                - message
      responses:
        '401':
          $ref: '#/components/responses/HttpErrorResponse'
        '403':
          $ref: '#/components/responses/HttpErrorResponse'
        '500':
          $ref: '#/components/responses/HttpErrorResponse'
        default:
          $ref: '#/components/responses/Response'
      deprecated: false

  /program/_update:
    post:
      tags:
        - Program
      summary: Update created programs
      description: Enables exchange of program related messages
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  $ref: '#/components/schemas/MsgSignature'
                header:
                  allOf:
                    - $ref: '#/components/schemas/MsgHeader'
                    - properties:
                        action:
                          example: update
                message:
                  $ref: '#/components/schemas/ProgramDetails'
              required:
                - header
                - message
      responses:
        '401':
          $ref: '#/components/responses/HttpErrorResponse'
        '403':
          $ref: '#/components/responses/HttpErrorResponse'
        '500':
          $ref: '#/components/responses/HttpErrorResponse'
        default:
          $ref: '#/components/responses/Response'
      deprecated: false

  /program/_search:
    post:
      tags:
        - Program
      summary: Search programs by query
      description: Enables search of program
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  $ref: '#/components/schemas/MsgSignature'
                header:
                  allOf:
                    - $ref: '#/components/schemas/MsgHeader'
                    - properties:
                        action:
                          example: search
                message:
                  allOf:
                    - $ref: '#/components/schemas/ProgramSearch'
              required:
                - header
                - message
      responses:
        '401':
          $ref: '#/components/responses/HttpErrorResponse'
        '403':
          $ref: '#/components/responses/HttpErrorResponse'
        '500':
          $ref: '#/components/responses/HttpErrorResponse'
        default:
          $ref: '#/components/responses/ProgramSearchResponse'
      deprecated: false


  /on-program/_create:
    post:
      tags:
        - Program
      summary: Update program after create response
      description: Enables exchange of program related messages
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  $ref: '#/components/schemas/MsgSignature'
                header:
                  allOf:
                    - $ref: '#/components/schemas/MsgHeader'
                    - properties:
                        action:
                          example: create
                    # - $ref: '#/components/schemas/MsgCallbackHeader'
                message:
                  allOf:
                    - $ref: '#/components/schemas/Program'
                    - $ref: "#/components/schemas/ExchangeCode"
              required:
                - header
                - message
      responses:
        '401':
          $ref: '#/components/responses/HttpErrorResponse'
        '403':
          $ref: '#/components/responses/HttpErrorResponse'
        '500':
          $ref: '#/components/responses/HttpErrorResponse'
        default:
          $ref: '#/components/responses/Response'
      deprecated: false

  /on-program/_update:
    post:
      tags:
        - Program
      summary: Update program after update response
      description: Enables exchange of program related messages
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  $ref: '#/components/schemas/MsgSignature'
                header:
                  allOf:
                    - $ref: '#/components/schemas/MsgHeader'
                    - properties:
                        action:
                          example: update
                    # - $ref: '#/components/schemas/MsgCallbackHeader'
                message:
                  allOf:
                    - $ref: '#/components/schemas/Program'
                    - $ref: "#/components/schemas/ExchangeCode"
              required:
                - header
                - message
      responses:
        '401':
          $ref: '#/components/responses/HttpErrorResponse'
        '403':
          $ref: '#/components/responses/HttpErrorResponse'
        '500':
          $ref: '#/components/responses/HttpErrorResponse'
        default:
          $ref: '#/components/responses/Response'
      deprecated: false

  
  # Estimate requests -----------------------------------------
  /estimate/_create:
    post:
      tags:
        - Estimate
      summary: Create estimate
      description: Enables exchange of estimate related messages, and store them.
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  $ref: '#/components/schemas/MsgSignature'
                header:
                  allOf:
                    - $ref: '#/components/schemas/MsgHeader'
                    - properties:
                        action:
                          enum:
                            - create
                message:
                  $ref: '#/components/schemas/EstimateDetails'
              required:
                - header
                - message
      responses:
        '401':
          $ref: '#/components/responses/HttpErrorResponse'
        '403':
          $ref: '#/components/responses/HttpErrorResponse'
        '500':
          $ref: '#/components/responses/HttpErrorResponse'
        default:
          $ref: '#/components/responses/Response'
      deprecated: false

  /estimate/_update:
    post:
      tags:
        - Estimate
      summary: Update created estimate
      description: Enables to update the existing created estimate
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  $ref: '#/components/schemas/MsgSignature'
                header:
                  allOf:
                    - $ref: '#/components/schemas/MsgHeader'
                    - properties:
                        action:
                          example: update
                message:
                  $ref: '#/components/schemas/EstimateDetails'
              required:
                - header
                - message
      responses:
        '401':
          $ref: '#/components/responses/HttpErrorResponse'
        '403':
          $ref: '#/components/responses/HttpErrorResponse'
        '500':
          $ref: '#/components/responses/HttpErrorResponse'
        default:
          $ref: '#/components/responses/Response'
      deprecated: false

  /estimate/_search:
    post:
      tags:
        - Estimate
      summary: Search estimate by query
      description: Enables search of esimate and return each fields
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  $ref: '#/components/schemas/MsgSignature'
                header:
                  allOf:
                    - $ref: '#/components/schemas/MsgHeader'
                    - properties:
                        action:
                          example: search
                message:
                  allOf:
                    - $ref: '#/components/schemas/EstimateSearch'
              required:
                - header
                - message
      responses:
        '401':
          $ref: '#/components/responses/HttpErrorResponse'
        '403':
          $ref: '#/components/responses/HttpErrorResponse'
        '500':
          $ref: '#/components/responses/HttpErrorResponse'
        default:
          $ref: '#/components/responses/EstimateSearchResponse'
      deprecated: false


  /on-estimate/_create:
    post:
      tags:
        - Estimate
      summary: Update estimate after create
      description: User can update the estimate if already created using on-estimate.
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  $ref: '#/components/schemas/MsgSignature'
                header:
                  allOf:
                    - $ref: '#/components/schemas/MsgHeader'
                    - properties:
                        action:
                          example: create
                    # - $ref: '#/components/schemas/MsgCallbackHeader'
                message:
                  $ref: '#/components/schemas/EstimateDetails'
              required:
                - header
                - message
      responses:
        '401':
          $ref: '#/components/responses/HttpErrorResponse'
        '403':
          $ref: '#/components/responses/HttpErrorResponse'
        '500':
          $ref: '#/components/responses/HttpErrorResponse'
        default:
          $ref: '#/components/responses/Response'
      deprecated: false

  /on-estimate/_update:
    post:
      tags:
        - Estimate
      summary: Update estimate after update response
      description: User can update the estimate if already created using on-estimate.
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  $ref: '#/components/schemas/MsgSignature'
                header:
                  allOf:
                    - $ref: '#/components/schemas/MsgHeader'
                    - properties:
                        action:
                          example: update
                    # - $ref: '#/components/schemas/MsgCallbackHeader'
                message:
                  $ref: '#/components/schemas/EstimateDetails'
              required:
                - header
                - message
      responses:
        '401':
          $ref: '#/components/responses/HttpErrorResponse'
        '403':
          $ref: '#/components/responses/HttpErrorResponse'
        '500':
          $ref: '#/components/responses/HttpErrorResponse'
        default:
          $ref: '#/components/responses/Response'
      deprecated: false

  
  # Sanciton requests
  /sanction/_create:
    post:
      tags:
        - Sanction
      summary: Create sanctions in program service
      description: Enables exchange of program related messages
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  $ref: '#/components/schemas/MsgSignature'
                header:
                  allOf:
                    - $ref: '#/components/schemas/MsgHeader'
                    - properties:
                        action:
                          example: create
                message:
                  $ref: '#/components/schemas/SanctionDetails'
              required:
                - header
                - message
      responses:
        '401':
          $ref: '#/components/responses/HttpErrorResponse'
        '403':
          $ref: '#/components/responses/HttpErrorResponse'
        '500':
          $ref: '#/components/responses/HttpErrorResponse'
        default:
          $ref: '#/components/responses/Response'
      deprecated: false

  /sanction/_update:
    post:
      tags:
        - Sanction
      summary: Update sanction details
      description: Update the sanction details, sanction is immutable only status can be changed.
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  $ref: '#/components/schemas/MsgSignature'
                header:
                  allOf:
                    - $ref: '#/components/schemas/MsgHeader'
                    - properties:
                        action:
                          example: update
                    
                message:
                  $ref: '#/components/schemas/SanctionDetails'
              required:
                - header
                - message
      responses:
        '401':
          $ref: '#/components/responses/HttpErrorResponse'
        '403':
          $ref: '#/components/responses/HttpErrorResponse'
        '500':
          $ref: '#/components/responses/HttpErrorResponse'
        default:
          $ref: '#/components/responses/Response'
      deprecated: false

  
  /sanction/_search:
    post:
      tags:
        - Sanction
      summary: Search Sanction details
      description: Search sanciton by query and return the response 
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  $ref: '#/components/schemas/MsgSignature'
                header:
                  allOf:
                    - $ref: '#/components/schemas/MsgHeader'
                    - properties:
                        action:
                          example: search
                message:
                  allOf:
                    - $ref: '#/components/schemas/SanctionSearch'
              required:
                - header
                - message
      responses:
        '401':
          $ref: '#/components/responses/HttpErrorResponse'
        '403':
          $ref: '#/components/responses/HttpErrorResponse'
        '500':
          $ref: '#/components/responses/HttpErrorResponse'
        default:
          $ref: '#/components/responses/SanctionSearchResponse'
      deprecated: false

  

  /on-sanction/_create:
    post:
      tags:
        - Sanction
      summary: Create sanctions in program service
      description: Enables creation of sanctions if not created in the system.
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  $ref: '#/components/schemas/MsgSignature'
                header:
                  allOf:
                    - $ref: '#/components/schemas/MsgHeader'
                    - properties:
                        action:
                          example: create
                message:
                  $ref: '#/components/schemas/SanctionDetails'
              required:
                - header
                - message
      responses:
        '401':
          $ref: '#/components/responses/HttpErrorResponse'
        '403':
          $ref: '#/components/responses/HttpErrorResponse'
        '500':
          $ref: '#/components/responses/HttpErrorResponse'
        default:
          $ref: '#/components/responses/Response'
      deprecated: false

  /on-sanction/_update:
    post:
      tags:
        - Sanction
      summary: Update created sanciton details
      description: Enables to udpate sanction details like status, remaining fields will be immutable
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  $ref: '#/components/schemas/MsgSignature'
                header:
                  allOf:
                    - $ref: '#/components/schemas/MsgHeader'
                    - properties:
                        action:
                          example: update
                message:
                  $ref: '#/components/schemas/SanctionDetails'
              required:
                - header
                - message
      responses:
        '401':
          $ref: '#/components/responses/HttpErrorResponse'
        '403':
          $ref: '#/components/responses/HttpErrorResponse'
        '500':
          $ref: '#/components/responses/HttpErrorResponse'
        default:
          $ref: '#/components/responses/Response'
      deprecated: false

  
  # Allocation Requests-----------------------------------------
  /allocation/_create:
    post:
      tags:
        - Allocation
      summary: Request to create allocation 
      description: User can request to create an allocation.
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  $ref: '#/components/schemas/MsgSignature'
                header:
                  allOf:
                    - $ref: '#/components/schemas/MsgHeader'
                    # - $ref: '#/components/schemas/MsgCallbackHeader'
                    - properties:
                        action:
                          example: create
                message:
                  $ref: '#/components/schemas/AllocationDetails'
              required:
                - header
                - message
      responses:
        '401':
          $ref: '#/components/responses/HttpErrorResponse'
        '403':
          $ref: '#/components/responses/HttpErrorResponse'
        '500':
          $ref: '#/components/responses/HttpErrorResponse'
        default:
          $ref: '#/components/responses/Response'
      deprecated: false

  /allocation/_update:
    post:
      tags:
        - Allocation
      summary: Request to update allocation 
      description: User can request to update in existing create allocation.
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  $ref: '#/components/schemas/MsgSignature'
                header:
                  allOf:
                    - $ref: '#/components/schemas/MsgHeader'
                    - properties:
                        action:
                          example: update
                    
                message:
                  $ref: '#/components/schemas/AllocationDetails'
              required:
                - header
                - message
      responses:
        '401':
          $ref: '#/components/responses/HttpErrorResponse'
        '403':
          $ref: '#/components/responses/HttpErrorResponse'
        '500':
          $ref: '#/components/responses/HttpErrorResponse'
        default:
          $ref: '#/components/responses/Response'
      deprecated: false

  /allocation/_search:
    post:
      tags:
        - Allocation
      summary: Search allocation details
      description: Search allocation by query and return the response
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  $ref: '#/components/schemas/MsgSignature'
                header:
                  allOf:
                    - $ref: '#/components/schemas/MsgHeader'
                    - properties:
                        action:
                          example: search
                message:
                  allOf:
                    - $ref: '#/components/schemas/AllocationSearch'
              required:
                - header
                - message
      responses:
        '401':
          $ref: '#/components/responses/HttpErrorResponse'
        '403':
          $ref: '#/components/responses/HttpErrorResponse'
        '500':
          $ref: '#/components/responses/HttpErrorResponse'
        default:
          $ref: '#/components/responses/AllocationSearchResponse'

      deprecated: false
    
  /on-allocation/_create:
    post:
      tags:
        - Allocation
      summary: Callback after allocation/_create
      description: Update created allocation if exists or create new
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  $ref: '#/components/schemas/MsgSignature'
                header:
                  allOf:
                    - $ref: '#/components/schemas/MsgHeader'
                    # - $ref: '#/components/schemas/MsgCallbackHeader'
                    - properties:
                        action:
                          example: create
                message:
                  $ref: '#/components/schemas/AllocationDetails'
              required:
                - header
                - message
      responses:
        '401':
          $ref: '#/components/responses/HttpErrorResponse'
        '403':
          $ref: '#/components/responses/HttpErrorResponse'
        '500':
          $ref: '#/components/responses/HttpErrorResponse'
        default:
          $ref: '#/components/responses/Response'
      deprecated: false

  /on-allocation/_update:
    post:
      tags:
        - Allocation
      summary: Request to update allocation 
      description: Updated status of create disburse request.
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  $ref: '#/components/schemas/MsgSignature'
                header:
                  allOf:
                    - $ref: '#/components/schemas/MsgHeader'
                    - properties:
                        action:
                          example: update
                    
                message:
                  $ref: '#/components/schemas/AllocationDetails'
              required:
                - header
                - message
      responses:
        '401':
          $ref: '#/components/responses/HttpErrorResponse'
        '403':
          $ref: '#/components/responses/HttpErrorResponse'
        '500':
          $ref: '#/components/responses/HttpErrorResponse'
        default:
          $ref: '#/components/responses/Response'
      deprecated: false

  
  
  # Disburse Requests-----------------------------------------
  /disburse/_create:
    post:
      tags:
        - Disburse
      summary: Initiate payment request
      description: Create new disbursement request to initiate payment.
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  $ref: '#/components/schemas/MsgSignature'
                header:
                  allOf:
                    - $ref: '#/components/schemas/MsgHeader'
                    - properties:
                        action:
                          example: create

                message:
                  allOf:
                    - $ref: '#/components/schemas/DisburseDetails'
              required:
                - header
                - message
      responses:
        '401':
          $ref: '#/components/responses/HttpErrorResponse'
        '403':
          $ref: '#/components/responses/HttpErrorResponse'
        '500':
          $ref: '#/components/responses/HttpErrorResponse'
        default:
          $ref: '#/components/responses/Response'
      deprecated: false

  /disburse/_search:
    post:
      tags:
        - Disburse
      summary: Search created disbursements
      description: Return disbursements based on query
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                # signature:
                #   $ref: '#/components/schemas/MsgSignature'
                header:
                  allOf:
                    - $ref: '#/components/schemas/MsgHeader'
                    - properties:
                        action:
                          example: search
                message:
                  allOf:
                    - $ref: '#/components/schemas/DisburseSearch'
              required:
                - header
                - message
      responses:
        '401':
          $ref: '#/components/responses/HttpErrorResponse'
        '403':
          $ref: '#/components/responses/HttpErrorResponse'
        '500':
          $ref: '#/components/responses/HttpErrorResponse'
        default:
          $ref: '#/components/responses/DisburseSearchResponse'
      deprecated: false

  /on-disburse/_create:
    post:
      tags:
        - Disburse
      summary: Updated status of create disburse request
      description: Updated status of create disburse request
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  $ref: '#/components/schemas/MsgSignature'
                header:
                  allOf:
                    - $ref: '#/components/schemas/MsgHeader'
                    - properties:
                        action:
                          example: create
                message:
                  allOf:
                    - $ref: '#/components/schemas/DisburseDetails'
              required:
                - header
                - message
      responses:
        '401':
          $ref: '#/components/responses/HttpErrorResponse'
        '403':
          $ref: '#/components/responses/HttpErrorResponse'
        '500':
          $ref: '#/components/responses/HttpErrorResponse'
        default:
          $ref: '#/components/responses/Response'
      deprecated: false

  /on-disburse/_update:
    post:
      tags:
        - Disburse
      summary: Updated status of create disburse request
      description: Enables exchange of disburse related messages
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signature:
                  $ref: '#/components/schemas/MsgSignature'
                header:
                  allOf:
                    - $ref: '#/components/schemas/MsgHeader'
                    - properties:
                        action:
                          example: update
                message:
                  allOf:
                    - $ref: '#/components/schemas/DisburseDetails'
              required:
                - header
                - message
      responses:
        '401':
          $ref: '#/components/responses/HttpErrorResponse'
        '403':
          $ref: '#/components/responses/HttpErrorResponse'
        '500':
          $ref: '#/components/responses/HttpErrorResponse'
        default:
          $ref: '#/components/responses/Response'
      deprecated: false

components:
  schemas:
    ProgramDetails:
      allOf:
        - $ref: '#/components/schemas/Program'
        - $ref: '#/components/schemas/ExchangeCode'

    EstimateDetails:
      allOf:
        - $ref: '#/components/schemas/Estimate'
        - $ref: '#/components/schemas/ExchangeCode'
        - properties:
            children:
              $ref: '#/components/schemas/EstimateDetails'

    SanctionDetails:
      allOf:
        - $ref: '#/components/schemas/Sanction'
        - $ref: '#/components/schemas/ExchangeCode'
        - properties:
            children:
              $ref: '#/components/schemas/SanctionDetails'

    AllocationDetails:
      allOf:
        - $ref: '#/components/schemas/Allocation'
        - $ref: '#/components/schemas/ExchangeCode'
        - properties:
            children:
              $ref: '#/components/schemas/AllocationDetails'

    DisburseDetails:
      allOf:
        - $ref: '#/components/schemas/Disburse'
        - $ref: '#/components/schemas/ExchangeCode'
        - properties:
              children:
                $ref: '#/components/schemas/DisburseDetails'

    correlation_id:
      description: |
        1. correlation_id acknowledged by end txn processing system (i.e receiver) to co-relate all related requests in the context of a business transaction.
        2. correlation_id uniqueness is ensured by txn processing system (i.e receiver)
      type: string
      maxLength: 99
      example: '9876543210'
        
    Ack:
      type: string
      description: |
        1. ACK: If the request is valid (for basic checks) and async callback (i.e webhook) will be invoked by reciever back to the sender.
        2. NACK: If the request is valid (for basic checks) and there is no futher updates from reciever back to the sender.
        3. ERR: If the reuqest is invalid and reciver can't process the request. error object holds error code, message.
      enum:
        - ACK
        - NACK
        - ERR
    AdditionalInfo:
      type: object
      description: Additional JSON property oject to hold custom user defined contextual data
    Amount:
      type: string
      description: Describes amount in decimal value format
      pattern: '^\d{1,13}\.\d{1,2}$'
    CurrencyCode:
      description: <br> 1. Currency code allocated as per ISO 4217 format.<br> 2. Codes for the representation of currencies and funds.
      type: string
      pattern: '^[A-Z]{3,3}$'
      example: INR
    Timestamp:
      description: |
        1. All dates and timestamps are represented in epoc timestamp - e.g 1708428280.
      type: string
      format: int64
      example: 1708428280
    Error:
      description: |
        Commumication layer Asyn errors that are returned as part of message acknowledgement.
        1. Messages that are not parsable or message integrity check fails.
        2. This object may be used across all transport layer protocols (https, sftp, messaging, etc,) to ack the receipt of a message.
        3. Business context and related validation is NOT in scope of this error object.
      type: object
      properties:
        code:
          type: string
          description: Standard error code
          enum:
            - err.request.bad
            - err.request.unauthorized
            - err.request.forbidden
            - err.request.not_found
            - err.request.timeout
            - err.version.not_supported
            - err.request.too_many_requests
            - err.sender_id.invalid
            - err.sender_uri.invalid
            - err.receiver_id.invalid
            - err.signature.missing
            - err.signature.invalid
            - err.encryption.invalid
            - err.service.unavailable
        message:
          type: string
          description: message to describe above error code
          maxLength: 999
    LanguageCode:
      type: string
      description: indicates language code. country codes as per ISO 639.3 standard
      pattern: '^[a-z]{3,3}$'
      example: en

    MsgCallbackHeader:
      type: object
      description: Message header
      properties:
        message_id:
          description: |
            1. Unique message id to communicate between sender and receiver systems to realiable deliver the message over any transport layer i.e https, pub/sub, sftp etc.,
            2. The scope of message_id end with successful ack of the message by the receiver.
            3. To realy the message between hops, underlying relying parties may consider to store and forward the message with integirty, ie Signature intact.
          type: string
          example: '789'
        message_ts:
          $ref: '#/components/schemas/Timestamp'
        status:
          $ref: '#/components/schemas/RequestStatus'
        status_reason_code:
          $ref: '#/components/schemas/MsgHeaderStatusReasonCode'
        status_reason_message:
          description: 'Status reascon code message, if any, Helps actionanble messaging for system/end users'
          type: string
          maxLength: 999
        sender_id:
          description: |
            1. sender_id registered with the receiving system or gateway. 
            2. Used for authorization, encryption, digital sign verfication, etc.,
          type: string
          example: civilregistry.example.org
        receiver_id:
          description: 'receiver id registered with the calling system. Used for authorization, encryption, digital sign verfication, etc., functions.'
          type: string
          example: registry.example.org
      required:
        - message_id
        - message_ts
        - action
        - status
    MsgHeader:
      type: object
      description: Message header
      properties:
        message_id:
          description: |
            1. Unique message id to communicate between sender and receiver systems to realiable deliver the message over any transport layer i.e https, pub/sub, sftp etc.,
            2. The scope of message_id end with successful ack of the message by the receiver.
            3. To realy the message between hops, underlying relying parties may consider to store and forward the message with integirty, ie Signature intact.
          type: string
          example: '123'
        message_ts:
          $ref: '#/components/schemas/Timestamp'
        action:
          description: 'identity payload type in message property.'
          type: string
          enum:
            - create
            - update
            - search
        sender_id:
          description: |
            1. sender_id registered with the receiving system or gateway. 
            2. Used for authorization, encryption, digital sign verfication, etc.,
          type: string
          example: program@https://spp.example.org
        sender_uri:
          description: |
            1. sender url to accept callbacks. Applicable only for async communications and if response ack_status is ACK.
            2. Default uri is assumed to be configred on the gateway as part of sender/receiver onboarding. 
            3. For SFTP based communications, this shall be set to server/folder details.
          type: string
          format: uri
          example: 'https://spp.example.org/{namespace}/callback/on-search'
        receiver_id:
          description: 'receiver id registered with the calling system. Used for authorization, encryption, digital sign verfication, etc., functions.'
          type: string
          example: program@https://pymts.example.org
      required:
        - message_id
        - message_ts
        - sender_id
        - receiver_id
    MsgHeaderStatusReasonCode:
      type: string
      description: Message header related common status reason codes
      enum:
        - rjct.version.invalid
        - rjct.message_id.duplicate
        - rjct.message_ts.invalid
        - rjct.action.invalid
        - rjct.action.not_supported
        - rjct.total_count.invalid
        - rjct.total_count.limit_exceeded
        - rjct.errors.too_many
    MsgSignature:
      type: string
      description: 'Signature of {header}+{message} body verified using sender''s signing public key'
      example: 'TgE1hcA2E+YPMdPGz4vveKQpR0x+pgzRTlet52qh63Kekr71vWWScXqaRFtQW64uRFZGBUhHYYZQ2y6LffwnNOOQhhssaThhqVBhXNEwX9i75SNYXi5XSJVDYzSyHrhF20HW6RE9mAVWdc80i7d+FXlh+b/U+fnj+SrZ2s6Xd0WUZvU29LgqeUpyznlWLu1mDdJxNZavsDLWmxjTnknqBjDvwSc35WhFDhXDA2lWmm8YpZ1Y6TBmvvtVS7mAOTnhFy9sdCbrLcfXk5QWIsdzlvPqlkvdwEf30OZ6ewb680Aj3hO2OT5LCv7iLyz7C7srnB9lJT5gXiw+eSnktPXlDA=='
    Pagination:
      description: Pagination details
      type: object
      properties:
        limit:
          description: >-
            Limit for total no of records in single search max limit should be
            defined as envirnment variable
          type: number
          default: 10
          maximum: 100
          format: double
        off_set:
          description: offset or page no
          type: number
          default: 0
          format: double
        total_count:
          description: Total count for a perticular criteria
          readOnly: true
          type: number
          format: double
        sort_by:
          description: result sorting order
          type: string
        order:
          type: object
          allOf:
            - $ref: '#/components/schemas/Order'
            - description: Sorting order
    Order:
      description: Sorting order
      type: string
      enum:
        - asc
        - desc
    Purpose:
      description: 'Payment disbursement purpose e.g Salary, Farmer Relief 2023, etc.,'
      type: string
      maxLength: 99
      example: Farmer Relief 2023
    ReferenceId:
      type: string
      description: Unique reference_id set by txn initiating system for each request in a batch
      example: '12345678901234567890'
    ReferenceIdList:
      type: array
      items:
        $ref: '#/components/schemas/ReferenceId'
    RequestStatus:
      type: string
      description: 'Request (e.g disburse, link, unlink, resolve, issue, search, verify, etc.,) status: <br> 1. rcvd: Received; Request received <br> 2. pdng: Pending; Request initiated <br> 3. succ: Success; Request successful <br> 4. rjct: Rejected; Request rejected'
      enum:
        - rcvd
        - pdng
        - succ
        - rjct
    SearchSort:
      description: Sorting definition
      type: object
      properties:
        attribute_name:
          type: string
          description: |
            @context: "https://example.org/schema/Attribute" <br>
            @type: "Attribute" <br>

            **Notes:**
              1. Attribute names defined as per implementation context.
              2. Usually a list of **enum** values of all possible attribute names.
              3. e.g: UIN, YOB, DOB, age, mobile, area-code, pin-code, etc.,
          example: YOB
        sort_order:
          type: string
          enum:
            - asc
            - desc
    TransactionId:
      description: |
        1. transaction_id set by txn initiating system (i.e sender) to co-relate all related requests in the context of a business transaction.
        2. transaction_id should be samme across processing systems/service end points.
        2. transaction_id uniqueness is ensured by txn initiating system (i.e sender)
      type: string
      maxLength: 99
      example: 0123456789

    Program:
      type: object
      description: |
        1. Describes payment schema that enable transfer from payer to payee accounts. 
        2. This entity supports immediate and scheduling one time payment request into future. 
        3. Recurring payments is not part of the scope of this entity.
      properties:
        id:
          type: string
          format: uuid
          example: 251c51eb-e970-4e01-a99a-70136c47a934
          minLength: 2
          maxLength: 64
          readOnly: true
        location_code:
          type: string
          description: Unique identifier of the tenant that could be a department/ulb/state
          minLength: 2
          maxLength: 64
          example: pb.jalandhar,dwss
        program_code:
          type: string
          description: Formated program code PROG/{FINANCIAL_YEAR}/{ULB-CODE}/{AUTO_NUMBER}
          minLength: 2
          maxLength: 64
          example: PORG/2023-24/PG.CITYA/00001
        name:
          type: string
          description: 'Name of the program'
          minLength: 2
          maxLength: 64
          example: Community Development Initiative
        parent_id:
          type: string
          description: Parent Id of a program
          format: uuid
          example: 251c51eb-e970-4e01-a99a-70136c47a934
          minLength: 2
          maxLength: 64
        description:
          type: string
          description: 'Description of the program'
          minLength: 2
          maxLength: 256
          example: "Empowering local communities through sustainable development projects."
        start_date:
          type: number
          example: 1672531200
        end_date:
          type: number
          example: 1704067200
        children:
          type: array
          items:
            type: object
        status:
          allOf:
            - $ref: '#/components/schemas/Status'
            - properties:
                status_code:
                    enum:
                    - ACTIVE
                    - INACTIVE
                    example: ACTIVE
        additional_details: 
          $ref: "#/components/schemas/AdditionalInfo"
        audit_details:
          $ref: "#/components/schemas/AuditDetails"
      required:
        - location_code
        - name
        - description
        - start_date

    ProgramSearch:
      type: object
      description: 'Program search criteria'
      properties:
        ids:
          type: array
          items:
            type: string
            example: 251c51eb-e970-4e01-a99a-70136c47a934
        parent_id:
          type: string
          example: 251c51eb-e970-4e01-a99a-70136c47a934
        name:
          type: string
          example: "Mukta"
        program_code:
          type: string
          example: "PG/2023-24/000091"
        location_code:
          type: string
          example: "pg.citya"
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
        - location_code
  
    Estimate:
      type: object
      description: |
        1. Describes payment schema that enable transfer from payer to payee accounts. 
        2. This entity supports immediate and scheduling one time payment request into future. 
        3. Recurring payments is not part of the scope of this entity.
      properties:
        id:
          type: string
          format: uuid
          example: 251c51eb-e970-4e01-a99a-70136c47a934
          minLength: 2
          maxLength: 64
          readOnly: true
        location_code:
          type: string
          description: Unique identifier of the tenant that could be a department/ulb/state
          minLength: 2
          maxLength: 64
          example: pb.jalandhar,dwss
        program_code:
          type: string
          description: Formated program code PROG/{FINANCIAL_YEAR}/{ULB-CODE}/{AUTO_NUMBER}
          minLength: 2
          maxLength: 64
          example: PORG/2023-24/PG.CITYA/00001
        description:
          type: string
          description: 'Description of the program'
          minLength: 2
          maxLength: 256
          example: "Empowering local communities through sustainable development projects."
        net_amount:
          type: number
          description: Amount to be paid including deduction amount
          example: 1000
        gross_amount:
          type: number
          description: Actual amount to be paid without deduction
          example: 1000
        children:
          type: array
          items:
            type: object
        status:
          allOf:
            - $ref: '#/components/schemas/Status'
            - properties:
                status_code:
                    enum:
                    - INITIATED
                    - APPROVED
                    example: INITIATED
        additional_details: 
          $ref: "#/components/schemas/AdditionalInfo"
        audit_details:
          $ref: "#/components/schemas/AuditDetails"
      required:
        - location_code
        - name
        - description
        - start_date
    
    EstimateSearch:
      type: object
      description: 'Program search criteria'
      properties:
        ids:
          type: array
          items:
            type: string
            example: 251c51eb-e970-4e01-a99a-70136c47a934
        program_code:
          type: string
          example: "PG/2023-24/000091"
        location_code:
          type: string
          example: "pg.citya"
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
        - location_code
  
    ExchangeCode:
      type: object
      description: 'Exchange message content which will be shared with all request'
      properties:
        type:
          type: string
          minLength: 2
          maxLength: 64
          readOnly: true
          enum:
            - program
            - sanction
            - allocation
            - disburse
        function_code:
          type: string
          minLength: 2
          maxLength: 64
          example: FC001
        administration_code:
          type: string
          minLength: 2
          maxLength: 64
          example: AC002
        recipient_segment_code:
          type: string
          minLength: 2
          maxLength: 64
          example: RSC003
        economic_segment_code:
          type: string
          minLength: 2
          maxLength: 64
          example: ESC004
        source_of_fund_code:
          type: string
          minLength: 2
          maxLength: 64
          example: SFC005
        target_segment_code:
          type: string
          minLength: 2
          maxLength: 64
          example: TSC006
        currency_code:
          type: string
          minLength: 2
          maxLength: 64
          example: INR
        locale_code:
          type: string
          minLength: 2
          maxLength: 64
          example: LC007
        
    Status:
      type: object
      properties:
        status_code:
          type: string
          enum:
            - RECEIVED
            - APPROVED
            - REJECTED
            - INPROCESS
            - INITIATED
            - SUCCESSFUL
            - FAILED
            - PARTIAL
            - CANCELLED
            - COMPLETED
            - ERROR
            - INFO
            - ACTIVE
            - INACTIVE
          example: SUCCESSFUL
        status_message:
          type: string

    Sanction:
      type: object
      description: |
        1. Describes payment schema that enable transfer from payer to payee accounts.
        2. This entity supports immediate and scheduling one time payment request into future. 
        3. Recurring payments is not part of the scope of this entity.
      properties:
        id:
          type: string
          format: uuid
          example: 251c51eb-e970-4e01-a99a-70136c47a934
          minLength: 2
          maxLength: 64
          readOnly: true
        location_code:
          type: string
          description: Unique identifier of the tenant that could be a department/ulb/state
          minLength: 2
          maxLength: 64
          example: pb.jalandhar,dwss
        program_code:
          type: string
          description: Formated program code PROG/{FINANCIAL_YEAR}/{ULB-CODE}/{AUTO_NUMBER}
          minLength: 2
          maxLength: 64
          example: PORG/2023-24/PG.CITYA/00001
        net_amount:
          type: number
        gross_amount:
          type: number
        available_amount:
          type: number
          readOnly: true
        children:
          type: array
          items:
            type: object
        status:
          $ref: '#/components/schemas/Status'
        additional_details: 
          $ref: "#/components/schemas/AdditionalInfo"
        audit_details:
          $ref: "#/components/schemas/AuditDetails"
      required:
        - location_code
        - program_code
        - sanctioned_amount
    
    SanctionSearch:
      type: object
      description: 'Sanction search criteria'
      properties:
        ids:
          type: array
          items:
            type: string
        location_code:
          type: string
        program_code:
          type: string
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
        - location_code
  
    
    Allocation:
      type: object
      description: |
        1. Describes payment schema that enable transfer from payer to payee accounts.
        2. This entity supports immediate and scheduling one time payment request into future. 
        3. Recurring payments is not part of the scope of this entity.
      properties:
        id:
          type: string
          format: uuid
          example: 251c51eb-e970-4e01-a99a-70136c47a934
          minLength: 2
          maxLength: 64
          readOnly: true
        location_code:
          type: string
          description: Unique identifier of the tenant that could be a department/ulb/state
          minLength: 2
          maxLength: 64
          example: pb.jalandhar,dwss
        program_code:
          type: string
          description: Formated program code PROG/{FINANCIAL_YEAR}/{ULB-CODE}/{AUTO_NUMBER}
          minLength: 2
          maxLength: 64
          example: PORG/2023-24/PG.CITYA/00001
        sanction_id:
          type: string
          format: uuid
          example: 251c51eb-e970-4e01-a99a-70136c47a934
          minLength: 2
          maxLength: 64
        net_amount:
          type: number
        gross_amount:
          type: number
        allocation_type:
          type: string
          default: ALLOCATION
          enum:
            - ALLOCATION
            - DEDUCTION
        children:
          type: array
          items:
            type: object
        status:
          $ref: '#/components/schemas/Status'
        additional_details: 
          $ref: "#/components/schemas/AdditionalInfo"
        audit_details:
          $ref: "#/components/schemas/AuditDetails"
      required:
        - location_code
        - sanction_id
        - program_code
        - net_amount
        - gross_amount
        - type
    
    AllocationSearch:
      type: object
      description: 'Allocation search criteria'
      properties:
        ids:
          type: array
          items:
            type: string
        location_code:
          type: string
        program_code:
          type: string
        sanction_id:
          type: string
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
        - location_code

    Disburse:
      type: object
      description: 'Exchange message content which will be shared with all request'
      properties:
        id:
          type: string
          format: uuid
          example: 251c51eb-e970-4e01-a99a-70136c47a934
          minLength: 2
          maxLength: 64
          readOnly: true
        location_code:
          type: string
          description: Unique identifier of the tenant that could be a department/ulb/state
          minLength: 2
          maxLength: 64
          example: pb.jalandhar,dwss
        program_code:
          type: string
          description: Formated program code PROG/{FINANCIAL_YEAR}/{ULB-CODE}/{AUTO_NUMBER}
          minLength: 2
          maxLength: 64
          example: PORG/2023-24/PG.CITYA/00001
        target_id:
          type: string
          description: Refernece id of works payment
          example: EP/0/2023-24/08/14/000267, 251c51eb-e970-4e01-a99a-70136c47a934
        transaction_id:
          type: string
          description: Formated transaction code, it will return after transaction is created at another end.
          minLength: 2
          maxLength: 64
          example: PI/2023-24/00001,BENF/2023-24/00001
        sanction_id:
          type: string
          example: 251c51eb-e970-4e01-a99a-70136c47a934
        account_code:
          type: string
          description: Account no with ifsc code will be account code, it will be in format ACCOUNT_NO@IFSC_CODE
          example: 1234567890@SBIN0003491
        net_amount:
          type: number
          description: Amount to be paid including deduction amount
          example: 1000
        gross_amount:
          type: number
          description: Actual amount to be paid without deduction
          example: 1000
        individual:
          allOf:
            - $ref: "#/components/schemas/Individual"
        children:
          type: array
          items:
            type: object
        status:
          $ref: '#/components/schemas/Status'
        additional_details: 
          $ref: "#/components/schemas/AdditionalInfo"
        audit_details:
          $ref: "#/components/schemas/AuditDetails"
      required:
        - target_id
        - location_code
        - program_code
        - individual
        - account_code
        - net_amount
        - gross_amount

    Individual:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
        phone:
          type: string
        pin:
          type: string
        address:
          type: string
      required:
        - name
        - phone
        - address
    DisburseSearch:
      type: object
      description: 'Disburse search criteria'
      properties:
    
        ids:
          type: array
          items:
            type: string
        location_code:
          type: string
        program_code:
          type: string
        target_id:
          type: string
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
        - location_code
     
    AuditDetails:
      type: object
      description: Collection of audit related fields used by most models
      readOnly: true
      properties:
        created_by: 
          type: string
          description: username (preferred) or userid of the user that created the object
        last_modified_by: 
          type: string
          description: username (preferred) or userid of the user that last modified the object
        created_time:
          type: integer
          format: int64
          description: epoch of the time object is created
        last_modified_time:
          type: integer
          format: int64
          description: epoch of the time object is last modified
  responses:
    HttpErrorResponse:
      description: HTTP layer error details
      content:
        application/json:
          schema:
            type: object
            description: 'HTTP transport layer error codes. Used by components like gateways, LB responding with HTTP status codes 1xx, 2xx, 3xx, 4xx and 5xx'
            properties:
              errors:
                items:
                  type: object
                  properties:
                    code:
                      type: string
                      description: error code
                    message:
                      type: string
                      description: error message
    Response:
      description: Acknowledgement of message received after successful validation of message and signature
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: object
                properties:
                  ack_status:
                    $ref: '#/components/schemas/Ack'
                  timestamp:
                    $ref: '#/components/schemas/Timestamp'
                  error:
                    $ref: '#/components/schemas/Error'
                  correlation_id:
                    $ref: '#/components/schemas/correlation_id'
                required:
                  - ack_status
                  - timestamp
                  - correlation_id
    ProgramSearchResponse:
      description: 'Request to update the register has been accepted.'
      content:
        application/json:
          schema:
            type: object
            properties:
              header:
                allOf:
                  - $ref: '#/components/schemas/MsgHeader'
                  # - $ref: '#/components/schemas/MsgCallbackHeader'
              programs:
                type: array
                items:
                  $ref: '#/components/schemas/ProgramDetails'
          
     
    AllocationSearchResponse:
      description: 'Request to update the register has been accepted.'
      content:
        application/json:
          schema:
            type: object
            properties:
              header:
                allOf:
                  - $ref: '#/components/schemas/MsgHeader'
                  # - $ref: '#/components/schemas/MsgCallbackHeader'
              allocations:
                type: array
                items:
                  allOf:
                    - $ref: '#/components/schemas/Allocation'
                    - $ref: "#/components/schemas/ExchangeCode"

    SanctionSearchResponse:
      description: 'Sanction Search response with sanction details'
      content:
        application/json:
          schema:
            type: object
            properties:
              header:
                allOf:
                  - $ref: '#/components/schemas/MsgHeader'
                  # - $ref: '#/components/schemas/MsgCallbackHeader'
              sanctions:
                type: array
                items:
                  allOf:
                    - $ref: '#/components/schemas/Sanction'
                    - $ref: "#/components/schemas/ExchangeCode"

    EstimateSearchResponse:
      description: 'Request to update the register has been accepted.'
      content:
        application/json:
          schema:
            type: object
            properties:
              header:
                allOf:
                  - $ref: '#/components/schemas/MsgHeader'
                  # - $ref: '#/components/schemas/MsgCallbackHeader'
              programs:
                type: array
                items:
                  $ref: '#/components/schemas/EstimateDetails'
          
    DisburseSearchResponse:
      description: 'Request to update the register has been accepted.'
      content:
        application/json:
          schema:
            type: object
            properties:
              header:
                allOf:
                  - $ref: '#/components/schemas/MsgHeader'
                  # - $ref: '#/components/schemas/MsgCallbackHeader'
              disbursements:
                type: array
                items:
                  allOf:
                    - $ref: '#/components/schemas/DisburseDetails'