account-lookup-service 17.4.0-csi-1233.5 → 17.4.1-csi-1300.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "account-lookup-service",
   "description": "Account Lookup Service is used to validate Party and Participant lookups.",
-  "version": "17.4.0-csi-1233.5",
+  "version": "17.4.1-csi-1300.1",
   "license": "Apache-2.0",
   "author": "ModusBox",
   "contributors": [

package/src/domain/parties/deps.js

@@ -0,0 +1,49 @@
+/*****
+ License
+ --------------
+ Copyright © 2020-2025 Mojaloop Foundation
+ The Mojaloop files are made available by the Mojaloop Foundation under the Apache License, Version 2.0 (the "License") and you may not use these files except in compliance with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, the Mojaloop files are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+ Contributors
+ --------------
+ This is the official list of the Mojaloop project contributors for this file.
+ Names of the original copyright holders (individuals or organizations)
+ should be listed with a '*' in the first column. People who have
+ contributed from an organization can be listed under the organization
+ that actually holds the copyright for their contributions (see the
+ Mojaloop Foundation for an example). Those individuals should have
+ their names indented and be marked with a '-'. Email address can be added
+ optionally within square brackets <email>.
+
+ * Mojaloop Foundation
+ * Eugen Klymniuk <eugen.klymniuk@infitx.com>
+
+ --------------
+ ******/
+
+const { proxies } = require('@mojaloop/central-services-shared').Util
+const oracle = require('../../models/oracle/facade')
+const participant = require('../../models/participantEndpoint/facade')
+const config = require('../../lib/config')
+const partiesUtils = require('./partiesUtils')
+
+const createDeps = ({ cache, proxyCache, childSpan, log, stepState }) => Object.freeze({
+  cache,
+  proxyCache,
+  childSpan,
+  log,
+  stepState,
+  config,
+  oracle,
+  participant,
+  proxies,
+  partiesUtils
+})
+
+module.exports = {
+  createDeps
+}

package/src/domain/parties/getPartiesByTypeAndID.js

@@ -23,51 +23,11 @@
  --------------
  **********/
 
-const { Enum, Util } = require('@mojaloop/central-services-shared')
-const ErrorHandler = require('@mojaloop/central-services-error-handling')
 const Metrics = require('@mojaloop/central-services-metrics')
-
-const config = require('../../lib/config')
-const oracle = require('../../models/oracle/facade')
-const participant = require('../../models/participantEndpoint/facade')
-const { createCallbackHeaders } = require('../../lib/headers')
-const { ERROR_MESSAGES } = require('../../constants')
-const logger = require('../../lib').logger.child({ component: 'domain.getPartiesByTypeAndID' })
-const Config = require('../../lib/config')
-const utils = require('./utils')
-const util = require('../../lib/util')
-
-const { FspEndpointTypes, FspEndpointTemplates } = Enum.EndPoints
-const { Headers, RestMethods } = Enum.Http
-
-const proxyCacheTtlSec = 40 // todo: make configurable
-
-const validateRequester = async ({ source, proxy, proxyCache }) => {
-  const log = logger.child({ source, method: 'validateRequester' })
-  const sourceParticipant = await participant.validateParticipant(source)
-  if (sourceParticipant) {
-    log.debug('source is in scheme')
-    return source
-  }
-
-  if (!proxy) {
-    const errMessage = ERROR_MESSAGES.sourceFspNotFound
-    log.warn(errMessage)
-    throw ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.ID_NOT_FOUND, errMessage)
-  }
-
-  const proxyParticipant = await participant.validateParticipant(proxy)
-  if (!proxyParticipant) {
-    const errMessage = ERROR_MESSAGES.partyProxyNotFound
-    log.warn(errMessage, { proxy })
-    throw ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.ID_NOT_FOUND, errMessage)
-  }
-
-  const isCached = await proxyCache.addDfspIdToProxyMapping(source, proxy)
-  // think, what if isCached !== true?
-  log.info('source is added to proxyMapping cache:', { proxy, isCached })
-  return proxy
-}
+const libUtil = require('../../lib/util')
+const { logger } = require('../../lib')
+const { GetPartiesService } = require('./services')
+const { createDeps } = require('./deps')
 
 /**
  * @function getPartiesByTypeAndID
@@ -83,177 +43,32 @@ const validateRequester = async ({ source, proxy, proxyCache }) => {
  * @param {IProxyCache} [proxyCache] - IProxyCache instance
  */
 const getPartiesByTypeAndID = async (headers, params, method, query, span, cache, proxyCache = undefined) => {
+  const component = getPartiesByTypeAndID.name
   const histTimerEnd = Metrics.getHistogram(
-    'getPartiesByTypeAndID',
+    component,
     'Get party by Type and Id',
     ['success']
   ).startTimer()
-  const log = logger.child({ params })
-  const proxyEnabled = !!(Config.PROXY_CACHE_CONFIG.enabled && proxyCache)
-  const type = params.Type
-  const partySubId = params.SubId
-  const callbackEndpointType = utils.getPartyCbType(partySubId)
-  const source = headers[Headers.FSPIOP.SOURCE]
-  const proxy = proxyEnabled && headers[Headers.FSPIOP.PROXY]
-  let destination = headers[Headers.FSPIOP.DESTINATION]
-  // see https://github.com/mojaloop/design-authority/issues/79
-  // the requester has specified a destination routing header. We should respect that and forward the request directly to the destination
-  // without consulting any oracles.
+  const childSpan = span ? span.getChild(component) : undefined
+  const log = logger.child({ component, params })
+  const stepState = libUtil.initStepState()
 
-  const childSpan = span ? span.getChild('getPartiesByTypeAndID') : undefined
-  log.info('parties::getPartiesByTypeAndID start', { source, destination, proxy })
+  const deps = createDeps({ cache, proxyCache, childSpan, log, stepState })
+  const service = new GetPartiesService(deps)
+  const results = {}
 
-  let requester
-  let fspiopError
-  let step
   try {
-    requester = await validateRequester({ source, proxy, proxyCache })
-
-    const options = {
-      partyIdType: type,
-      partyIdentifier: params.ID,
-      ...(partySubId && { partySubIdOrType: partySubId })
-    }
-
-    if (destination) {
-      step = 'validateParticipant-1'
-      const destParticipantModel = await participant.validateParticipant(destination)
-      if (!destParticipantModel) {
-        step = 'lookupProxyByDfspId-2'
-        const proxyId = proxyEnabled && await proxyCache.lookupProxyByDfspId(destination)
-
-        if (!proxyId) {
-          log.warn('no destination participant, and no dfsp-to-proxy mapping', { destination })
-          const errMessage = ERROR_MESSAGES.partyDestinationFspNotFound
-          throw ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.ID_NOT_FOUND, errMessage)
-        }
-        destination = proxyId
-      }
-      // all ok, go ahead and forward the request
-      step = 'sendRequest-3'
-      await participant.sendRequest(headers, destination, callbackEndpointType, RestMethods.GET, undefined, options, childSpan)
-
-      histTimerEnd({ success: true })
-      log.info('discovery getPartiesByTypeAndID request was sent to destination', { destination })
-      return
-    }
-
-    step = 'oracleRequest-4'
-    const response = await oracle.oracleRequest(headers, method, params, query, undefined, cache)
-    if (Array.isArray(response?.data?.partyList) && response.data.partyList.length > 0) {
-      // Oracle's API is a standard rest-style end-point Thus a GET /party on the oracle will return all participant-party records. We must filter the results based on the callbackEndpointType to make sure we remove records containing partySubIdOrType when we are in FSPIOP_CALLBACK_URL_PARTIES_GET mode:
-      let filteredResponsePartyList
-      switch (callbackEndpointType) {
-        case FspEndpointTypes.FSPIOP_CALLBACK_URL_PARTIES_GET:
-          filteredResponsePartyList = response.data.partyList.filter(party => party.partySubIdOrType == null) // Filter records that DON'T contain a partySubIdOrType
-          break
-        case FspEndpointTypes.FSPIOP_CALLBACK_URL_PARTIES_SUB_ID_GET:
-          filteredResponsePartyList = response.data.partyList.filter(party => party.partySubIdOrType === partySubId) // Filter records that match partySubIdOrType
-          break
-        default:
-          filteredResponsePartyList = response // Fallback to providing the standard list
-      }
-
-      if (!Array.isArray(filteredResponsePartyList) || !filteredResponsePartyList.length) {
-        const errMessage = 'Requested FSP/Party not found'
-        log.warn(errMessage)
-        throw ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.ID_NOT_FOUND, errMessage)
-      }
-
-      let sentCount = 0 // if sentCount === 0 after sending, should we restart the whole process?
-      const sending = filteredResponsePartyList.map(async party => {
-        const { fspId } = party
-        const clonedHeaders = { ...headers }
-        if (!destination) {
-          clonedHeaders[Headers.FSPIOP.DESTINATION] = fspId
-        }
-        step = 'validateParticipant-5'
-        const schemeParticipant = await participant.validateParticipant(fspId)
-        if (schemeParticipant) {
-          sentCount++
-          log.verbose('participant is in scheme', { fspId })
-          return participant.sendRequest(clonedHeaders, party.fspId, callbackEndpointType, RestMethods.GET, undefined, options, childSpan)
-        }
-
-        // If the participant is not in the scheme and proxy routing is enabled,
-        // we should check if there is a proxy for it and send the request to the proxy
-        if (proxyEnabled) {
-          step = 'lookupProxyByDfspId-6'
-          const proxyName = await proxyCache.lookupProxyByDfspId(fspId)
-          if (!proxyName) {
-            log.warn('no proxyMapping for participant!  TODO: Delete reference in oracle...', { fspId })
-            // todo: delete reference in oracle
-          } else {
-            sentCount++
-            log.verbose('participant is NOT in scheme, use proxy name', { fspId, proxyName })
-            return participant.sendRequest(clonedHeaders, proxyName, callbackEndpointType, RestMethods.GET, undefined, options, childSpan)
-          }
-        }
-      })
-      step = 'sendRequests-7'
-      await Promise.all(sending)
-      log.info('participant.sendRequests to filtered oracle partyList are done', { sentCount })
-      // todo: think what if sentCount === 0 here
-    } else {
-      log.info('empty partyList form oracle, getting proxies list...', { proxyEnabled, params })
-      let filteredProxyNames = []
-
-      if (proxyEnabled) {
-        step = 'getAllProxiesNames-8'
-        const proxyNames = await Util.proxies.getAllProxiesNames(Config.SWITCH_ENDPOINT)
-        filteredProxyNames = proxyNames.filter(name => name !== proxy)
-      }
-
-      if (!filteredProxyNames.length) {
-        const callbackHeaders = createCallbackHeaders({
-          requestHeaders: headers,
-          partyIdType: type,
-          partyIdentifier: params.ID,
-          endpointTemplate: partySubId
-            ? FspEndpointTemplates.PARTIES_SUB_ID_PUT_ERROR
-            : FspEndpointTemplates.PARTIES_PUT_ERROR
-        })
-        fspiopError = ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.PARTY_NOT_FOUND)
-        const errorCallbackEndpointType = utils.errorPartyCbType(partySubId)
-        step = 'sendErrorToParticipant-9'
-        await participant.sendErrorToParticipant(requester, errorCallbackEndpointType,
-          fspiopError.toApiErrorObject(config.ERROR_HANDLING), callbackHeaders, params, childSpan)
-      } else {
-        const alsReq = utils.alsRequestDto(source, params)
-        log.info('starting setSendToProxiesList flow: ', { filteredProxyNames, alsReq, proxyCacheTtlSec })
-        step = 'setSendToProxiesList-10'
-        const isCached = await proxyCache.setSendToProxiesList(alsReq, filteredProxyNames, proxyCacheTtlSec)
-        if (!isCached) {
-          log.warn('failed to setSendToProxiesList')
-          throw ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.ID_NOT_FOUND, ERROR_MESSAGES.failedToCacheSendToProxiesList)
-        }
-
-        step = 'sending-11'
-        const sending = filteredProxyNames.map(
-          proxyName => participant.sendRequest(headers, proxyName, callbackEndpointType, RestMethods.GET, undefined, options, childSpan)
-            .then(({ status, data } = {}) => ({ status, data }))
-        )
-        const results = await Promise.allSettled(sending)
-        const isOk = results.some(result => result.status === 'fulfilled')
-        // If, at least, one request is sent to proxy, we treat the whole flow as successful.
-        // Failed requests should be handled by TTL expired/timeout handler
-        // todo: - think, if we should handle failed requests here (e.g., by calling receivedErrorResponse)
-        log.info('setSendToProxiesList flow is done:', { isOk, results, filteredProxyNames, alsReq })
-        if (!isOk) {
-          log.warn('no successful requests sent to proxies')
-          throw ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.ID_NOT_FOUND, ERROR_MESSAGES.proxyConnectionError)
-        }
-      }
-    }
+    await service.handleRequest({ headers, params, query, results })
+    log.info('getPartiesByTypeAndID is done')
     histTimerEnd({ success: true })
   } catch (err) {
-    fspiopError = await utils.createErrorHandlerOnSendingCallback(Config, log)(err, headers, params, requester)
+    results.fspiopError = await deps.partiesUtils.createErrorHandlerOnSendingCallback(deps.config, log)(err, headers, params, results.requester)
     histTimerEnd({ success: false })
-    if (fspiopError) {
-      util.countFspiopError(fspiopError, { operation: 'getPartiesByTypeAndID', step })
+    if (results.fspiopError) {
+      libUtil.countFspiopError(results.fspiopError, { operation: component, step: stepState.step })
     }
   } finally {
-    await utils.finishSpanWithError(childSpan, fspiopError)
+    await libUtil.finishSpanWithError(childSpan, results.fspiopError)
   }
 }
 

package/src/domain/parties/index.js

@@ -25,8 +25,11 @@
 
 'use strict'
 
-const parties = require('./parties')
+const getPartiesByTypeAndID = require('./getPartiesByTypeAndID')
+const { putPartiesByTypeAndID, putPartiesErrorByTypeAndID } = require('./putParties')
 
-exports.getPartiesByTypeAndID = parties.getPartiesByTypeAndID
-exports.putPartiesByTypeAndID = parties.putPartiesByTypeAndID
-exports.putPartiesErrorByTypeAndID = parties.putPartiesErrorByTypeAndID
+module.exports = {
+  getPartiesByTypeAndID,
+  putPartiesByTypeAndID,
+  putPartiesErrorByTypeAndID
+}

package/src/domain/parties/{utils.js → partiesUtils.js}

@@ -1,5 +1,31 @@
+/*****
+ License
+ --------------
+ Copyright © 2020-2025 Mojaloop Foundation
+ The Mojaloop files are made available by the Mojaloop Foundation under the Apache License, Version 2.0 (the "License") and you may not use these files except in compliance with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, the Mojaloop files are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+ Contributors
+ --------------
+ This is the official list of the Mojaloop project contributors for this file.
+ Names of the original copyright holders (individuals or organizations)
+ should be listed with a '*' in the first column. People who have
+ contributed from an organization can be listed under the organization
+ that actually holds the copyright for their contributions (see the
+ Mojaloop Foundation for an example). Those individuals should have
+ their names indented and be marked with a '-'. Email address can be added
+ optionally within square brackets <email>.
+
+ * Mojaloop Foundation
+ * Eugen Klymniuk <eugen.klymniuk@infitx.com>
+
+ --------------
+ ******/
+
 const { Enum, Util: { Hapi } } = require('@mojaloop/central-services-shared')
-const EventSdk = require('@mojaloop/event-sdk')
 const ErrorHandler = require('@mojaloop/central-services-error-handling')
 
 const participant = require('../../models/participantEndpoint/facade')
@@ -20,18 +46,6 @@ const errorPartyCbType = (partySubId) => partySubId
   ? FspEndpointTypes.FSPIOP_CALLBACK_URL_PARTIES_SUB_ID_PUT_ERROR
   : FspEndpointTypes.FSPIOP_CALLBACK_URL_PARTIES_PUT_ERROR
 
-const finishSpanWithError = async (childSpan, fspiopError) => {
-  if (childSpan && !childSpan.isFinished) {
-    if (fspiopError) {
-      const state = new EventSdk.EventStateMetadata(EventSdk.EventStatusType.failed, fspiopError.apiErrorCode.code, fspiopError.apiErrorCode.message)
-      await childSpan.error(fspiopError, state)
-      await childSpan.finish(fspiopError.message, state)
-    } else {
-      await childSpan.finish()
-    }
-  }
-}
-
 const makePutPartiesErrorPayload = async (config, fspiopError, headers, params) => {
   const body = fspiopError.toApiErrorObject(config.ERROR_HANDLING)
   return config.API_TYPE === Hapi.API_TYPES.iso20022
@@ -45,6 +59,12 @@ const alsRequestDto = (sourceId, params) => ({
   partyId: params.ID
 })
 
+const partiesRequestOptionsDto = (params) => ({
+  partyIdType: params.Type,
+  partyIdentifier: params.ID,
+  ...(params.SubId && { partySubIdOrType: params.SubId })
+})
+
 const swapSourceDestinationHeaders = (headers) => {
   const {
     [Headers.FSPIOP.SOURCE]: source,
@@ -62,7 +82,7 @@ const swapSourceDestinationHeaders = (headers) => {
 // change signature to accept object
 const createErrorHandlerOnSendingCallback = (config, logger) => async (err, headers, params, requester) => {
   try {
-    logger.error('error in sending parties callback', err)
+    logger.error('error in sending parties callback: ', err)
     const sendTo = requester || headers[Headers.FSPIOP.SOURCE]
     const errorCallbackEndpointType = errorPartyCbType(params.SubId)
     const fspiopError = ErrorHandler.Factory.reformatFSPIOPError(err)
@@ -75,7 +95,7 @@ const createErrorHandlerOnSendingCallback = (config, logger) => async (err, head
   } catch (exc) {
     // We can't do anything else here- we _must_ handle all errors _within_ this function because
     // we've already sent a sync response- we cannot throw.
-    logger.error('failed to handleErrorOnSendingCallback. No further processing!', exc)
+    logger.error('failed to handleErrorOnSendingCallback. No further processing! ', exc)
   }
 }
 
@@ -84,8 +104,8 @@ module.exports = {
   putPartyCbType,
   errorPartyCbType,
   makePutPartiesErrorPayload,
-  finishSpanWithError,
   createErrorHandlerOnSendingCallback,
   alsRequestDto,
+  partiesRequestOptionsDto,
   swapSourceDestinationHeaders
 }

package/src/domain/parties/{parties.js → putParties.js}

@@ -37,12 +37,12 @@ const Metrics = require('@mojaloop/central-services-metrics')
 
 const oracle = require('../../models/oracle/facade')
 const participant = require('../../models/participantEndpoint/facade')
+const libUtil = require('../../lib/util')
+const Config = require('../../lib/config')
+const { logger } = require('../../lib')
 const { ERROR_MESSAGES } = require('../../constants')
-const logger = require('../../lib').logger.child({ component: 'domain.putParties' })
 
-const Config = require('../../lib/config')
-const utils = require('./utils')
-const util = require('../../lib/util')
+const partiesUtils = require('./partiesUtils')
 const getPartiesByTypeAndID = require('./getPartiesByTypeAndID')
 
 /**
@@ -59,14 +59,13 @@ const getPartiesByTypeAndID = require('./getPartiesByTypeAndID')
  * @param {IProxyCache} [proxyCache] - IProxyCache instance
  */
 const putPartiesByTypeAndID = async (headers, params, method, payload, dataUri, cache, proxyCache = undefined) => {
+  const components = putPartiesByTypeAndID.name
   const histTimerEnd = Metrics.getHistogram(
-    'putPartiesByTypeAndID',
+    components,
     'Put parties by type and id',
     ['success']
   ).startTimer()
-  const log = logger.child({ params, method: 'putPartiesByTypeAndID' })
-  const type = params.Type
-  const partySubId = params.SubId
+  const log = logger.child({ params, components })
   const source = headers[Headers.FSPIOP.SOURCE]
   const destination = headers[Headers.FSPIOP.DESTINATION]
   const proxy = headers[Headers.FSPIOP.PROXY]
@@ -75,6 +74,7 @@ const putPartiesByTypeAndID = async (headers, params, method, payload, dataUri,
 
   let sendTo
   let step
+
   try {
     step = 'validateParticipant-1'
     const requesterParticipant = await participant.validateParticipant(source)
@@ -91,7 +91,7 @@ const putPartiesByTypeAndID = async (headers, params, method, payload, dataUri,
     }
 
     if (proxyEnabled && proxy) {
-      const alsReq = utils.alsRequestDto(destination, params) // or source?
+      const alsReq = partiesUtils.alsRequestDto(destination, params)
       step = 'receivedSuccessResponse-2'
       const isExists = await proxyCache.receivedSuccessResponse(alsReq)
       if (!isExists) {
@@ -122,21 +122,17 @@ const putPartiesByTypeAndID = async (headers, params, method, payload, dataUri,
     }
 
     const decodedPayload = decodePayload(dataUri, { asParsed: false })
-    const callbackEndpointType = utils.putPartyCbType(partySubId)
-    const options = {
-      partyIdType: type,
-      partyIdentifier: params.ID,
-      ...(partySubId && { partySubIdOrType: partySubId })
-    }
+    const callbackEndpointType = partiesUtils.putPartyCbType(params.SubId)
+    const options = partiesUtils.partiesRequestOptionsDto(params)
     step = 'sendRequest-6'
     await participant.sendRequest(headers, sendTo, callbackEndpointType, RestMethods.PUT, decodedPayload.body.toString(), options)
 
     log.info('parties::putPartiesByTypeAndID::callback was sent', { sendTo })
     histTimerEnd({ success: true })
   } catch (err) {
-    const fspiopError = await utils.createErrorHandlerOnSendingCallback(Config, log)(err, headers, params, sendTo)
+    const fspiopError = await partiesUtils.createErrorHandlerOnSendingCallback(Config, log)(err, headers, params, sendTo)
     if (fspiopError) {
-      util.countFspiopError(fspiopError, { operation: 'putPartiesByTypeAndID', step })
+      libUtil.countFspiopError(fspiopError, { operation: components, step })
     }
     histTimerEnd({ success: false })
   }
@@ -156,82 +152,110 @@ const putPartiesByTypeAndID = async (headers, params, method, payload, dataUri,
  * @param {IProxyCache} [proxyCache] - IProxyCache instance
  */
 const putPartiesErrorByTypeAndID = async (headers, params, payload, dataUri, span, cache, proxyCache = undefined) => {
+  const component = putPartiesErrorByTypeAndID.name
   const histTimerEnd = Metrics.getHistogram(
-    'putPartiesErrorByTypeAndID',
+    component,
     'Put parties error by type and id',
     ['success']
   ).startTimer()
-  const log = logger.child({ params, method: 'putPartiesErrorByTypeAndID' })
-  const partySubId = params.SubId
+  const log = logger.child({ params, component })
   const destination = headers[Headers.FSPIOP.DESTINATION]
-  const callbackEndpointType = utils.errorPartyCbType(partySubId)
   const proxyEnabled = !!(Config.PROXY_CACHE_CONFIG.enabled && proxyCache)
+  const proxy = proxyEnabled && headers[Headers.FSPIOP.PROXY]
 
-  const childSpan = span ? span.getChild('putPartiesErrorByTypeAndID') : undefined
+  const childSpan = span ? span.getChild(component) : undefined
+  const stepState = libUtil.initStepState()
+  log.info('parties::putPartiesErrorByTypeAndID start', { destination, proxy })
 
   let sendTo
   let fspiopError
-  let step
 
   try {
-    const proxy = proxyEnabled && headers[Headers.FSPIOP.PROXY]
     if (proxy) {
-      if (isNotValidPayeeCase(payload)) {
-        const swappedHeaders = utils.swapSourceDestinationHeaders(headers)
-        step = 'oracleRequest-1'
-        await oracle.oracleRequest(swappedHeaders, RestMethods.DELETE, params, null, null, cache)
-        getPartiesByTypeAndID(swappedHeaders, params, RestMethods.GET, {}, span, cache, proxyCache)
-        // todo: - think if we need to send errorCallback?
-        //       - or sentCallback after getPartiesByTypeAndID is done
-        log.info('notValidPayee case - deleted Participants and run getPartiesByTypeAndID:', { proxy, params, payload })
-        return
-      }
-
-      const alsReq = utils.alsRequestDto(destination, params) // or source?
-      step = 'receivedErrorResponse-2'
-      const isLast = await proxyCache.receivedErrorResponse(alsReq, proxy)
-      if (!isLast) {
-        log.info('got NOT last error callback from proxy:', { proxy, alsReq })
+      const isDone = await processProxyErrorCallback({
+        headers, params, payload, childSpan, cache, proxyCache, log, proxy, destination, stepState
+      })
+      if (isDone) {
+        log.info('putPartiesErrorByTypeAndID proxy callback was processed', { proxy })
+        histTimerEnd({ success: true })
         return
       }
     }
-    step = 'validateParticipant-3'
-    const destinationParticipant = await participant.validateParticipant(destination)
 
-    if (destinationParticipant) {
-      sendTo = destination
-    } else {
-      step = 'lookupProxyByDfspId-4'
-      const proxyName = proxyEnabled && await proxyCache.lookupProxyByDfspId(destination)
-      if (!proxyName) {
-        const errMessage = ERROR_MESSAGES.partyDestinationFspNotFound
-        log.warn(errMessage)
-        throw ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.DESTINATION_FSP_ERROR, errMessage)
-      }
-      sendTo = proxyName
-    }
-    const decodedPayload = decodePayload(dataUri, { asParsed: false })
-    await participant.sendErrorToParticipant(sendTo, callbackEndpointType, decodedPayload.body.toString(), headers, params, childSpan)
+    sendTo = await identifyDestinationForErrorCallback({
+      destination, proxyCache, proxyEnabled, log, stepState
+    })
+
+    await sendErrorCallbackToParticipant({
+      sendTo, headers, params, dataUri, childSpan, stepState
+    })
 
     log.info('putPartiesErrorByTypeAndID callback was sent', { sendTo })
     histTimerEnd({ success: true })
   } catch (err) {
-    fspiopError = await utils.createErrorHandlerOnSendingCallback(Config, log)(err, headers, params, sendTo)
+    fspiopError = await partiesUtils.createErrorHandlerOnSendingCallback(Config, log)(err, headers, params, sendTo)
     if (fspiopError) {
-      util.countFspiopError(fspiopError, { operation: 'putPartiesErrorByTypeAndID', step })
+      libUtil.countFspiopError(fspiopError, { operation: component, step: stepState.step })
     }
     histTimerEnd({ success: false })
   } finally {
-    await utils.finishSpanWithError(childSpan, fspiopError)
+    await libUtil.finishSpanWithError(childSpan, fspiopError)
   }
 }
 
+const processProxyErrorCallback = async ({
+  headers, params, payload, childSpan, cache, proxyCache, log, proxy, destination, stepState
+}) => {
+  log.verbose('processProxyErrorCallback...')
+  let isDone // whether or not to continue putPartiesErrorByTypeAndID
+
+  if (isNotValidPayeeCase(payload)) {
+    stepState.inProgress('notValidPayeeCase-1')
+    log.info('notValidPayee case - deleted Participants and run getPartiesByTypeAndID', { proxy, payload })
+    const swappedHeaders = partiesUtils.swapSourceDestinationHeaders(headers)
+    await oracle.oracleRequest(swappedHeaders, RestMethods.DELETE, params, null, null, cache)
+    getPartiesByTypeAndID(swappedHeaders, params, RestMethods.GET, {}, childSpan, cache, proxyCache)
+    isDone = true
+  } else {
+    stepState.inProgress('receivedErrorResponse-2')
+    const alsReq = partiesUtils.alsRequestDto(destination, params) // or source?
+    const isLast = await proxyCache.receivedErrorResponse(alsReq, proxy)
+    log.info(`got${isLast ? '' : 'NOT'} last error callback from proxy`, { proxy, alsReq, isLast })
+    isDone = !isLast
+  }
+  return isDone
+}
+
+const identifyDestinationForErrorCallback = async ({
+  destination, proxyCache, proxyEnabled, log, stepState
+}) => {
+  stepState.inProgress('validateParticipant-3')
+  const destinationParticipant = await participant.validateParticipant(destination)
+  if (destinationParticipant) return destination
+
+  stepState.inProgress('lookupProxyDestination-4')
+  const proxyName = proxyEnabled && await proxyCache.lookupProxyByDfspId(destination)
+  if (proxyName) return proxyName
+
+  const errMessage = ERROR_MESSAGES.partyDestinationFspNotFound
+  log.warn(errMessage)
+  throw ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.DESTINATION_FSP_ERROR, errMessage)
+}
+
+const sendErrorCallbackToParticipant = async ({
+  sendTo, headers, params, dataUri, childSpan, stepState
+}) => {
+  stepState.inProgress('sendErrorToParticipant-5')
+  const decodedPayload = decodePayload(dataUri, { asParsed: false })
+  const callbackEndpointType = partiesUtils.errorPartyCbType(params.SubId)
+  await participant.sendErrorToParticipant(sendTo, callbackEndpointType, decodedPayload.body.toString(), headers, params, childSpan)
+}
+
 function isNotValidPayeeCase (payload) {
   return payload?.errorInformation?.errorCode === MojaloopApiErrorCodes.PAYEE_IDENTIFIER_NOT_VALID.code
 }
 
 module.exports = {
-  getPartiesByTypeAndID,
   putPartiesByTypeAndID,
   putPartiesErrorByTypeAndID
 }

package/src/domain/parties/services/GetPartiesService.js

@@ -0,0 +1,291 @@
+/*****
+ License
+ --------------
+ Copyright © 2020-2025 Mojaloop Foundation
+ The Mojaloop files are made available by the Mojaloop Foundation under the Apache License, Version 2.0 (the "License") and you may not use these files except in compliance with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, the Mojaloop files are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+ Contributors
+ --------------
+ This is the official list of the Mojaloop project contributors for this file.
+ Names of the original copyright holders (individuals or organizations)
+ should be listed with a '*' in the first column. People who have
+ contributed from an organization can be listed under the organization
+ that actually holds the copyright for their contributions (see the
+ Mojaloop Foundation for an example). Those individuals should have
+ their names indented and be marked with a '-'. Email address can be added
+ optionally within square brackets <email>.
+
+ * Mojaloop Foundation
+ * Eugen Klymniuk <eugen.klymniuk@infitx.com>
+
+ --------------
+ ******/
+
+const ErrorHandler = require('@mojaloop/central-services-error-handling')
+const { Enum } = require('@mojaloop/central-services-shared')
+const { ERROR_MESSAGES } = require('../../../constants')
+const { createCallbackHeaders } = require('../../../lib/headers')
+
+const { FspEndpointTypes, FspEndpointTemplates } = Enum.EndPoints
+const { Headers, RestMethods } = Enum.Http
+
+const proxyCacheTtlSec = 40 // todo: make configurable
+
+class GetPartiesService {
+  #deps
+
+  constructor (deps) {
+    this.#deps = deps
+    this.log = this.#deps.log.child({ component: this.constructor.name })
+    this.proxyEnabled = !!(deps.config.PROXY_CACHE_CONFIG?.enabled && deps.proxyCache)
+  }
+
+  async handleRequest ({ headers, params, query, results }) {
+    const source = headers[Headers.FSPIOP.SOURCE]
+    const proxy = headers[Headers.FSPIOP.PROXY]
+    const destination = headers[Headers.FSPIOP.DESTINATION]
+    // see https://github.com/mojaloop/design-authority/issues/79
+    // the requester has specified a destination routing header. We should respect that and forward the request directly to the destination
+    // without consulting any oracles.
+    this.log.info('handling getParties request', { source, destination, proxy })
+
+    const requester = await this.validateRequester({ source, proxy })
+    results.requester = requester
+
+    if (destination) {
+      await this.forwardRequestToDestination({ destination, headers, params })
+      return
+    }
+    const response = await this.sendOracleDiscoveryRequest({ headers, params, query })
+
+    if (Array.isArray(response?.data?.partyList) && response.data.partyList.length > 0) {
+      const partyList = this.filterOraclePartyList({ response, params })
+      await this.processOraclePartyList({ partyList, headers, params, destination })
+      return
+    }
+
+    this.log.info('empty partyList form oracle, getting proxyList...', { params })
+    const proxyNames = await this.getFilteredProxyList(proxy)
+
+    if (proxyNames.length) {
+      return this.triggerSendToProxiesFlow({ proxyNames, headers, params, source })
+    }
+
+    results.fspiopError = await this.sendErrorCallback({ requester, headers, params })
+  }
+
+  async validateRequester ({ source, proxy }) {
+    this.#deps.stepState.inProgress('validateRequester-0')
+    const log = this.log.child({ source, method: 'validateRequester' })
+
+    const sourceParticipant = await this.#validateParticipant(source)
+    if (sourceParticipant) {
+      log.debug('source is in scheme')
+      return source
+    }
+
+    if (!this.proxyEnabled || !proxy) {
+      const errMessage = ERROR_MESSAGES.sourceFspNotFound
+      log.warn(errMessage)
+      throw ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.ID_NOT_FOUND, errMessage)
+    }
+
+    const proxyParticipant = await this.#validateParticipant(proxy)
+    if (!proxyParticipant) {
+      const errMessage = ERROR_MESSAGES.partyProxyNotFound
+      log.warn(errMessage, { proxy })
+      throw ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.ID_NOT_FOUND, errMessage)
+    }
+
+    const isCached = await this.#deps.proxyCache.addDfspIdToProxyMapping(source, proxy)
+    // think, what if isCached !== true?
+    log.info('source is added to proxyMapping cache:', { proxy, isCached })
+    return proxy
+  }
+
+  async forwardRequestToDestination ({ destination, headers, params }) {
+    this.#deps.stepState.inProgress('validateDestination-1')
+    const log = this.log.child({ method: 'forwardRequestToDestination' })
+    let sendTo = destination
+
+    const destParticipantModel = await this.#validateParticipant(destination)
+    if (!destParticipantModel) {
+      this.#deps.stepState.inProgress('lookupProxyDestination-2')
+      const proxyId = this.proxyEnabled && await this.#deps.proxyCache.lookupProxyByDfspId(destination)
+
+      if (!proxyId) {
+        log.warn('no destination participant, and no dfsp-to-proxy mapping', { destination })
+        const errMessage = ERROR_MESSAGES.partyDestinationFspNotFound
+        throw ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.ID_NOT_FOUND, errMessage)
+      }
+      sendTo = proxyId
+    }
+    // all ok, go ahead and forward the request
+    await this.#forwardGetPartiesRequest({ sendTo, headers, params })
+    log.info('discovery getPartiesByTypeAndID request was sent', { sendTo })
+  }
+
+  filterOraclePartyList ({ response, params }) {
+    // Oracle's API is a standard rest-style end-point Thus a GET /party on the oracle will return all participant-party records. We must filter the results based on the callbackEndpointType to make sure we remove records containing partySubIdOrType when we are in FSPIOP_CALLBACK_URL_PARTIES_GET mode:
+    this.#deps.stepState.inProgress('filterOraclePartyList-5')
+    const callbackEndpointType = this.#deps.partiesUtils.getPartyCbType(params.SubId)
+    let filteredResponsePartyList
+
+    switch (callbackEndpointType) {
+      case FspEndpointTypes.FSPIOP_CALLBACK_URL_PARTIES_GET:
+        filteredResponsePartyList = response.data.partyList.filter(party => party.partySubIdOrType == null) // Filter records that DON'T contain a partySubIdOrType
+        break
+      case FspEndpointTypes.FSPIOP_CALLBACK_URL_PARTIES_SUB_ID_GET:
+        filteredResponsePartyList = response.data.partyList.filter(party => party.partySubIdOrType === params.SubId) // Filter records that match partySubIdOrType
+        break
+      default:
+        filteredResponsePartyList = response // Fallback to providing the standard list
+    }
+
+    if (!Array.isArray(filteredResponsePartyList) || !filteredResponsePartyList.length) {
+      const errMessage = 'Requested FSP/Party not found'
+      this.#deps.log.warn(errMessage)
+      throw ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.ID_NOT_FOUND, errMessage)
+    }
+
+    return filteredResponsePartyList
+  }
+
+  async processOraclePartyList ({ partyList, headers, params, destination }) {
+    const log = this.log.child({ method: 'processOraclePartyList' })
+
+    let sentCount = 0 // if sentCount === 0 after sending, should we restart the whole process?
+    const sending = partyList.map(async party => {
+      const { fspId } = party
+      const clonedHeaders = { ...headers }
+      if (!destination) {
+        clonedHeaders[Headers.FSPIOP.DESTINATION] = fspId
+      }
+      this.#deps.stepState.inProgress('validateParticipant-6')
+      const schemeParticipant = await this.#validateParticipant(fspId)
+      if (schemeParticipant) {
+        sentCount++
+        log.info('participant is in scheme', { fspId })
+        return this.#forwardGetPartiesRequest({
+          sendTo: fspId,
+          headers: clonedHeaders,
+          params
+        })
+      }
+
+      // If the participant is not in the scheme and proxy routing is enabled,
+      // we should check if there is a proxy for it and send the request to the proxy
+      if (this.proxyEnabled) {
+        this.#deps.stepState.inProgress('lookupProxyByDfspId-7')
+        const proxyName = await this.#deps.proxyCache.lookupProxyByDfspId(fspId)
+        if (!proxyName) {
+          log.warn('no proxyMapping for participant!  TODO: Delete reference in oracle...', { fspId })
+          // todo: delete reference in oracle
+        } else {
+          sentCount++
+          log.info('participant is NOT in scheme, use proxy name', { fspId, proxyName })
+          return this.#forwardGetPartiesRequest({
+            sendTo: proxyName,
+            headers: clonedHeaders,
+            params
+          })
+        }
+      }
+    })
+    await Promise.all(sending)
+    log.verbose('processOraclePartyList is done', { sentCount })
+    // todo: think what if sentCount === 0 here
+  }
+
+  async getFilteredProxyList (proxy) {
+    this.#deps.stepState.inProgress('getAllProxies-8')
+    if (!this.proxyEnabled) {
+      this.log.warn('proxyCache is not enabled')
+      return []
+    }
+
+    const proxyNames = await this.#deps.proxies.getAllProxiesNames(this.#deps.config.SWITCH_ENDPOINT)
+    this.log.debug('getAllProxiesNames is done', { proxyNames })
+    return proxyNames.filter(name => name !== proxy)
+  }
+
+  async triggerSendToProxiesFlow ({ proxyNames, headers, params, source }) {
+    const log = this.log.child({ method: 'triggerSendToProxiesFlow' })
+    this.#deps.stepState.inProgress('setSendToProxiesList-10')
+    const alsReq = this.#deps.partiesUtils.alsRequestDto(source, params)
+    log.info('starting setSendToProxiesList flow: ', { proxyNames, alsReq, proxyCacheTtlSec })
+
+    const isCached = await this.#deps.proxyCache.setSendToProxiesList(alsReq, proxyNames, proxyCacheTtlSec)
+    if (!isCached) {
+      log.warn('failed to setSendToProxiesList')
+      throw ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.ID_NOT_FOUND, ERROR_MESSAGES.failedToCacheSendToProxiesList)
+    }
+
+    this.#deps.stepState.inProgress('sendingProxyRequests-11')
+    const sending = proxyNames.map(
+      sendTo => this.#forwardGetPartiesRequest({ sendTo, headers, params })
+        .then(({ status, data } = {}) => ({ status, data }))
+    )
+    const results = await Promise.allSettled(sending)
+    const isOk = results.some(result => result.status === 'fulfilled')
+    // If, at least, one request is sent to proxy, we treat the whole flow as successful.
+    // Failed requests should be handled by TTL expired/timeout handler
+    // todo: - think, if we should handle failed requests here (e.g., by calling receivedErrorResponse)
+    log.info('triggerSendToProxiesFlow is done:', { isOk, results, proxyNames, alsReq })
+    this.#deps.stepState.inProgress('allSent-12')
+    if (!isOk) {
+      log.warn('no successful requests sent to proxies')
+      throw ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.ID_NOT_FOUND, ERROR_MESSAGES.proxyConnectionError)
+    }
+  }
+
+  async #validateParticipant (participantId) {
+    return this.#deps.participant.validateParticipant(participantId)
+  }
+
+  async #forwardGetPartiesRequest ({ sendTo, headers, params }) {
+    this.#deps.stepState.inProgress('forwardRequest-3')
+    const callbackEndpointType = this.#deps.partiesUtils.getPartyCbType(params.SubId)
+    const options = this.#deps.partiesUtils.partiesRequestOptionsDto(params)
+
+    return this.#deps.participant.sendRequest(headers, sendTo, callbackEndpointType, RestMethods.GET, undefined, options, this.#deps.childSpan)
+  }
+
+  // async sendSuccessCallback ({ headers, sendTo }) {
+  //   return this.#deps.participant.sendRequest(headers, sendTo,)
+  // }
+
+  async sendErrorCallback ({ requester, headers, params }) {
+    this.#deps.stepState.inProgress('sendErrorCallback-9')
+    const callbackHeaders = createCallbackHeaders({
+      requestHeaders: headers,
+      partyIdType: params.Type,
+      partyIdentifier: params.ID,
+      endpointTemplate: params.SubId
+        ? FspEndpointTemplates.PARTIES_SUB_ID_PUT_ERROR
+        : FspEndpointTemplates.PARTIES_PUT_ERROR
+    })
+    const fspiopError = ErrorHandler.Factory.createFSPIOPError(ErrorHandler.Enums.FSPIOPErrorCodes.PARTY_NOT_FOUND)
+
+    await this.#deps.participant.sendErrorToParticipant(
+      requester,
+      this.#deps.partiesUtils.errorPartyCbType(params.SubId),
+      fspiopError.toApiErrorObject(this.#deps.config.ERROR_HANDLING),
+      callbackHeaders,
+      params,
+      this.#deps.childSpan
+    )
+    return fspiopError
+  }
+
+  async sendOracleDiscoveryRequest ({ headers, params, query }) {
+    this.#deps.stepState.inProgress('oracleRequest-4')
+    return this.#deps.oracle.oracleRequest(headers, RestMethods.GET, params, query, undefined, this.#deps.cache)
+  }
+}
+
+module.exports = GetPartiesService

package/src/domain/parties/services/index.js

@@ -0,0 +1,32 @@
+/*****
+ License
+ --------------
+ Copyright © 2020-2025 Mojaloop Foundation
+ The Mojaloop files are made available by the Mojaloop Foundation under the Apache License, Version 2.0 (the "License") and you may not use these files except in compliance with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, the Mojaloop files are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+ Contributors
+ --------------
+ This is the official list of the Mojaloop project contributors for this file.
+ Names of the original copyright holders (individuals or organizations)
+ should be listed with a '*' in the first column. People who have
+ contributed from an organization can be listed under the organization
+ that actually holds the copyright for their contributions (see the
+ Mojaloop Foundation for an example). Those individuals should have
+ their names indented and be marked with a '-'. Email address can be added
+ optionally within square brackets <email>.
+
+ * Mojaloop Foundation
+ * Eugen Klymniuk <eugen.klymniuk@infitx.com>
+
+ --------------
+ ******/
+
+const GetPartiesService = require('./GetPartiesService')
+
+module.exports = {
+  GetPartiesService
+}

package/src/domain/timeout/dto.js

@@ -13,7 +13,7 @@ const EventFrameworkUtil = require('@mojaloop/central-services-shared').Util.Eve
 
 const LibUtil = require('../../lib/util')
 const Config = require('../../lib/config')
-const partiesUtils = require('../parties/utils')
+const partiesUtils = require('../parties/partiesUtils')
 
 const timeoutCallbackDto = async ({ destination, partyId, partyType }) => {
   const headers = {

package/src/lib/headers.js

@@ -46,7 +46,8 @@ exports.createCallbackHeaders = (params) => {
   callbackHeaders[Enums.Http.Headers.FSPIOP.DESTINATION] = params.requestHeaders[Enums.Http.Headers.FSPIOP.SOURCE]
   callbackHeaders[Enums.Http.Headers.FSPIOP.HTTP_METHOD] = Enums.Http.RestMethods.PUT
   callbackHeaders[Enums.Http.Headers.FSPIOP.URI] = Mustache.render(params.endpointTemplate, {
-    partyIdType: params.partyIdType, partyIdentifier: params.partyIdentifier
+    partyIdType: params.partyIdType,
+    partyIdentifier: params.partyIdentifier
   })
 
   return callbackHeaders

package/src/lib/util.js

@@ -1,5 +1,33 @@
-const util = require('util')
-const Path = require('path')
+/*****
+ License
+ --------------
+ Copyright © 2020-2025 Mojaloop Foundation
+ The Mojaloop files are made available by the Mojaloop Foundation under the Apache License, Version 2.0 (the "License") and you may not use these files except in compliance with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, the Mojaloop files are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+ Contributors
+ --------------
+ This is the official list of the Mojaloop project contributors for this file.
+ Names of the original copyright holders (individuals or organizations)
+ should be listed with a '*' in the first column. People who have
+ contributed from an organization can be listed under the organization
+ that actually holds the copyright for their contributions (see the
+ Mojaloop Foundation for an example). Those individuals should have
+ their names indented and be marked with a '-'. Email address can be added
+ optionally within square brackets <email>.
+
+ * Mojaloop Foundation
+ * Eugen Klymniuk <eugen.klymniuk@infitx.com>
+
+ --------------
+ ******/
+
+const util = require('node:util')
+const Path = require('node:path')
+const EventSdk = require('@mojaloop/event-sdk')
 const Enum = require('@mojaloop/central-services-shared').Enum
 const { HeaderValidation, Hapi, rethrow } = require('@mojaloop/central-services-shared').Util
 const Config = require('../lib/config')
@@ -70,7 +98,30 @@ const countFspiopError = (error, options) => {
   rethrow.countFspiopError(error, options)
 }
 
+// todo: think better name
+const initStepState = (initStep = 'start') => {
+  let step = initStep
+  return Object.freeze({
+    get step () { return step }, // or rename to current ?
+    inProgress (nextStep) { step = nextStep }
+  })
+}
+
+const finishSpanWithError = async (childSpan, fspiopError) => {
+  if (childSpan && !childSpan.isFinished) {
+    if (fspiopError) {
+      const state = new EventSdk.EventStateMetadata(EventSdk.EventStatusType.failed, fspiopError.apiErrorCode.code, fspiopError.apiErrorCode.message)
+      await childSpan.error(fspiopError, state)
+      await childSpan.finish(fspiopError.message, state)
+    } else {
+      await childSpan.finish()
+    }
+  }
+}
+
 module.exports = {
+  initStepState,
+  finishSpanWithError,
   getSpanTags,
   pathForInterface,
   getStackOrInspect,

package/test/unit/domain/parties/parties.test.js

@@ -41,8 +41,8 @@ const Metrics = require('@mojaloop/central-services-metrics')
 
 const Config = require('../../../../src/lib/config')
 const Db = require('../../../../src/lib/db')
-const partiesDomain = require('../../../../src/domain/parties/parties')
-const partiesUtils = require('../../../../src/domain/parties/utils')
+const partiesDomain = require('../../../../src/domain/parties')
+const partiesUtils = require('../../../../src/domain/parties/partiesUtils')
 const participant = require('../../../../src/models/participantEndpoint/facade')
 const oracle = require('../../../../src/models/oracle/facade')
 const oracleEndpointCached = require('../../../../src/models/oracle/oracleEndpointCached')

package/test/unit/domain/parties/utils.test.js

@@ -36,7 +36,7 @@ jest.mock('@mojaloop/central-services-shared', () => ({
 
 const { API_TYPES } = require('@mojaloop/central-services-shared').Util.Hapi
 const { logger } = require('../../../../src/lib')
-const utils = require('../../../../src/domain/parties/utils')
+const partiesUtils = require('../../../../src/domain/parties/partiesUtils')
 const config = require('../../../../src/lib/config')
 const fixtures = require('../../../fixtures')
 
@@ -48,7 +48,7 @@ describe('parties utils Tests -->', () => {
     const headers = fixtures.partiesCallHeadersDto({ source })
     const params = { ID: '1234', Type: 'MSISDN' }
 
-    const handleError = utils.createErrorHandlerOnSendingCallback(isoConfig, logger)
+    const handleError = partiesUtils.createErrorHandlerOnSendingCallback(isoConfig, logger)
     await handleError(err, headers, params, source)
 
     expect(mockSendRequest).toHaveBeenCalledTimes(1)

package/test/unit/lib/util.test.js

@@ -65,4 +65,29 @@ describe('Util', () => {
     const expectedApiExtendedAdminMockPath = path.join('interface', 'thirdparty', 'admin_swagger.json')
     expect(apiExtendedAdminMockPath).toContain(expectedApiExtendedAdminMockPath)
   })
+
+  describe('stepState Tests -->', () => {
+    it('should initiate stepState with default step', async () => {
+      const stepState = Util.initStepState()
+      expect(stepState.step).toBe('start')
+    })
+
+    it('should initiate stepState with custom step', async () => {
+      const step = 'customStep'
+      const stepState = Util.initStepState(step)
+      expect(stepState.step).toBe(step)
+    })
+
+    it('should set ongoing step using inProgress() method', async () => {
+      const step = 'nextStep'
+      const stepState = Util.initStepState()
+      stepState.inProgress(step)
+      expect(stepState.step).toBe(step)
+    })
+
+    it('should not be able to change internal state directly', async () => {
+      const stepState = Util.initStepState()
+      expect(() => { stepState.step = 'impossible' }).toThrowError()
+    })
+  })
 })