---
title: "Retrieve Merchant Hierarchy"
method: GET
path: "/merchant-hierarchy"
tags: ["Generic Acquirer Setup"]
---

# Retrieve Merchant Hierarchy

`GET /merchant-hierarchy`

"This endpoint provides the merchant hierarchy details for an institution that are available on the Fiserv OmniPay database. To use this endpoint, you must include at least one of the following fields in the query parameters: 'internalMerchantId,' 'parentInternalMerchantId,' or 'externalMerchantId.' While these fields are not marked as mandatory, at least one of them is required."

## Query parameters

- `internalMerchantId` string — Unique OmniPay internal merchant number. When populated should be an existing merchant number within the institution and query parameters 'externalMerchantId', 'parentInternalMerchantId' should not be populated.
- `externalMerchantId` string — The external OmniPay merchant number that is linked to the unique internal OmniPay merchant number. The institution identifies the merchant by its external merchant number. This is typically the merchant number that would be used within the institution's own processing systems and that would for example be printed on cardholder receipts by the merchant's point of sale systems. When populated should be an existing merchant number within the institution and query parameters 'internalMerchantId', 'parentInternalMerchantId' should not be populated.
- `parentInternalMerchantId` string — The internal OmniPay MID to which the merchant needs to be linked to as a child merchant. When populated should be an existing group /sub group merchant MID within the institution and query parameters 'internalMerchantId', 'externalMerchantId' should not be populated.
- `merchantStatusIndex` string — Status of the merchant. For a list of valid status codes use Acquirer Profile API GET reference-data endpoint with query parameter clasifications equal merchantStatusIndex.
- `merchantLevelCode` 'MEMBER' | 'GROUP' | 'SUB_GROUP' — The merchant hierarchy level at which the merchant is boarded.
- `extractDirection` 'UP' | 'DOWN' — Extracts all merchants within the hierarchy above or below the submitted merchant Id (i.e. any one of the query parameter 'internalMerchantId' or 'parentInternalMerchantId' or 'externalMerchantId' provided). Leave blank to extract both up and down the hierarchy.
- `limit` integer — The number of items to return.
- `offset` integer

## Headers

- `Content-Type` 'application/json' | 'application/json;charset=UTF-8', required
- `FSV-Interaction-Id` string, required
- `Institution-Number` string, required
- `Environment` string, required

## Response `200`

OK

- InlineResponse20011 — An API response. The API response will be either a `SUCCESS` or an `ERROR`. A partial success or warning scenario will be treated as a Success with embedded messages in the meta data. A full success may not have messages. The API response will contain at least one of the following top level members."
  - `meta` MetaType — Supplementary information about the data.
    - `paging` PagingMetaType — Map containing pagination related information about data.
      - `count` integer — Total number of records present in system which can be retrieved.
      - `totalPages` integer — Total number of pages with maximum limit taken into account.
      - `currentOffset` integer — Current offset used in request.
      - `currentNumberOfRetrievedRecords` integer — Current number of retrieved records.
      - `maxLimit` integer — Maximum limit of records that can be retrieved.
      - `hasMoreRecords` boolean — Indicates if there are more records available.
      - `pageNumber` integer — Current page number.
    - `sorting` SortingMetaType — Map containing sorting related information about data.
      - `sort` string — Indicates the elements the current data is sorted with and the direction of sorting.
    - `messages` ErrorType[] — Messages related to request processing or response data - any additional information or warnings to be returned in the case of a successful API call.
      - `id` string — Generated message identifier for particular request, helping to locate server logs.
      - `code` string, required — Machine readable, unique code of the message related to particular case within operation execution. For complete list of codes please refer to API portal, messages page.
      - `title` string, required — Short description of the error. Not for displaying purposes.
      - `detail` string — Provides additional low-level details about the error to assist with troubleshooting. Not for displaying purposes.
      - `source` SourceType — Object containing references to the source of the message.
        - `pointer` string — Indicates the element in the request document which caused the error.
        - `parameter` string — Indicates which query parameter caused the error.
        - `header` string — Indicates which header caused the error.
  - `data` object[] — "Contains the primary data to be returned as the API response. Use this object only when respnse type is an array. It will not be returned in case of error."
    - `merchantProperty` OPYMerchantPropertyPropertyObj — Properties assigned to the merchant
      - `propertyIndex` string — Code for the institution defined property that is assigned to the merchant.
      - `propertyDescription` string — Contains description associated to a code in English.
    - `propertyValue` string — The value of the property type selected. For merchant boarding, if the field is left empty the system will default to a null value. For maintenance, if the field already contains a value, the system will set it to null if an empty string is provided.
    - `lastUpdatedBy` string — Contact name of the person or system description that last updated the record.
    - `lastUpdatedDate` string — Date when the record was last updated. Format YYYYMMDD.
  - `errors` ErrorType[] — "Contains one or more error messages and is mutually exclusive with the data item. This will not be returned in success scenarios."
    - `id` string — Generated message identifier for particular request, helping to locate server logs.
    - `code` string, required — Machine readable, unique code of the message related to particular case within operation execution. For complete list of codes please refer to API portal, messages page.
    - `title` string, required — Short description of the error. Not for displaying purposes.
    - `detail` string — Provides additional low-level details about the error to assist with troubleshooting. Not for displaying purposes.
    - `source` SourceType — Object containing references to the source of the message.
      - `pointer` string — Indicates the element in the request document which caused the error.
      - `parameter` string — Indicates which query parameter caused the error.
      - `header` string — Indicates which header caused the error.
  - `links` LinksType — Contains the links to retrieve the resources exposed as part of this API.
    - `self` string — The link to the primary resource being retrieved in the request.
    - `first` string — This is to provide the link to retrieve the first record/page. This SHOULD be used in case server provides pagination of the resource.
    - `last` string — This is to provide the link to retrieve the last record/page. This SHOULD be used in case server provides pagination of the resource.
    - `prev` string — This is to provide the link to retrieve the previous record/page. This SHOULD be used in case server provides pagination of the resource.
    - `next` string — This is to provide the link to retrieve the last record. This SHOULD be used in case server provides pagination of the resource

## Other responses

- `400` — Bad Request - the request could not be interpreted by the server due to incorrect syntax. The client SHOULD NOT repeat the request without modifications.
- `401` — Authentication error
- `403` — Forbidden error i.e. Consumer token credentials are valid but lack of permissions to do this action.
- `404` — Record does not exist.
- `500` — Internal Server Error

---

[API](https://skmtc.net/fiserv/apis/acquirer-profile-in-design.md) · [All operations](https://skmtc.net/fiserv/apis/acquirer-profile-in-design/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fiserv/acquirer-profile-in-design/revisions/dd7ef6ce81a1/schema)