Retrieve 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."

internalMerchantIdstring

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.

Example:12345679

externalMerchantIdstring

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.

Example:1234523456789

parentInternalMerchantIdstring

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.

Example:23456789

merchantStatusIndexstring

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.

Example:001

merchantLevelCode'MEMBER' | 'GROUP' | 'SUB_GROUP'

The merchant hierarchy level at which the merchant is boarded.

Example:MEMBER

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.

Example:DOWN

limitinteger

The number of items to return.

offsetinteger

The number of items to skip before returning the results

Content-Type'application/json' | 'application/json;charset=UTF-8' required

Standard HTTP Header; Represents the format of the payload being provided in the request. This must be set to application/json and applicable for POST/PATCH.

FSV-Interaction-Idstring required

Example:9591e6d8-0d70-11ea-8d71-362b9e155667

An RFC4122 UUID used as to trace requests.

Institution-Numberstring required

Example:00000099

Institution number (8-digit number) associated with the merchant. This information defines the acquirer for the merchant.

Environmentstring required

For test environment, specific test environment name should be passed (e.g. "bwu15"). Contact Fiserv OmniPay Project team to get confirmation on the test environment to be used. For production, value "prod" should be populated.

Response

OK

Example response

{
  "meta": {
    "paging": {
      "count": 100,
      "totalPages": 10,
      "currentOffset": 1,
      "currentNumberOfRetrievedRecords": 10,
      "maxLimit": 10,
      "hasMoreRecords": true,
      "pageNumber": 1
    },
    "sorting": {
      "sort": "name,-startDate"
    },
    "messages": [
      {
        "id": "dd4ba13c-4a3c-4078-a31f-35ac9c07a8f7",
        "code": "ACCOUNT_NUMBER_NOT_FOUND",
        "title": "The authorization credentials required for this request are invalid.",
        "detail": "SQLException found while trying to establish the connection with table TUKCDHN.",
        "source": {
          "pointer": "/dogs/name",
          "parameter": "type",
          "header": "type"
        }
      }
    ]
  },
  "data": [
    {
      "merchantProperty": {
        "propertyIndex": "001"
      },
      "propertyValue": "6,000,000,000",
      "lastUpdatedBy": "John Smith",
      "lastUpdatedDate": "20210406"
    }
  ],
  "errors": [
    {
      "id": "dd4ba13c-4a3c-4078-a31f-35ac9c07a8f7",
      "code": "ACCOUNT_NUMBER_NOT_FOUND",
      "title": "The authorization credentials required for this request are invalid.",
      "detail": "SQLException found while trying to establish the connection with table TUKCDHN.",
      "source": {
        "pointer": "/dogs/name",
        "parameter": "type",
        "header": "type"
      }
    }
  ],
  "links": {
    "self": "https://api.firstdata.com/ipp/accounts-management/v1/accounts?offset=3&limit=10",
    "first": "https://api.firstdata.com/ipp/accounts-management/v1/accounts?offset=1&limit=10",
    "last": "https://api.firstdata.com/ipp/accounts-management/v1/accounts?offset=10&limit=10",
    "prev": "https://api.firstdata.com/ipp/accounts-management/v1/accounts?offset=2&limit=10",
    "next": "https://api.firstdata.com/ipp/accounts-management/v1/accounts?offset=4&limit=10"
  }
}

v1

Retrieve Merchant Hierarchy

Query parameters

Headers

Response

Example response