Search Merchants API

Searches and retrieves merchant records using text and active-status filters, with configurable pagination and sorting metadata. Returns matching results in a paginated response structure.

1. Overview

The Search Merchants API allows authorized users to search and retrieve merchant records using configurable search criteria and pagination.

The endpoint supports filtering merchants by text and active status, while pagination parameters control the page number and number of records returned.

Access Levels: SUPER_ADMIN, PARTNER, MERCHANT

2. Endpoint Details

PropertyValue
API NameSearch Merchants
HTTP MethodGET
Endpoint/api/v1/merchant/search
Production Base URLhttps://app-api.edfapay.com
Accept*/*
Request BodyNot required

3. Authentication

Include the API key in the request headers.

HeaderValue
X-API-KEYYOUR_API_KEY
Accept*/*

4. Query Parameters

The endpoint defines two required query parameter objects: pageProperties and searchCriteria.

4.1 pageProperties

Controls pagination for the merchant search results.

FieldTypeDescription
pageNumberIntegerPage number. The example uses zero-based pagination, starting at 0.
pageSizeIntegerNumber of records requested per page.

Example:

{
  "pageNumber": 0,
  "pageSize": 10
}

4.2 searchCriteria

Defines the criteria used to filter merchant records.

FieldTypeDescription
textStringText used to search merchant records.
activeBooleanFilters merchants by active status.

Example:

{
  "text": "Merchant",
  "active": true
}

The provided Swagger example demonstrates these fields. Additional filtering fields are not specified in the supplied schema.

5. Request Example

HTTP method: GET

Endpoint: /api/v1/merchant/search

The API accepts pageProperties and searchCriteria as query parameter objects. The exact serialization format for these objects in the URL is not established by the supplied Swagger screenshots.

Use Swagger's Try it out feature to confirm the generated query string before implementing the request in your application.

6. cURL Example

The following is a request template. Replace the query parameter placeholders with the exact serialized values generated by Swagger.

curl --request GET \
  --url 'https://app-api.edfapay.com/api/v1/merchant/search?<SERIALIZED_QUERY_PARAMETERS>' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'Accept: */*'

<SERIALIZED_QUERY_PARAMETERS> is a placeholder, not a literal parameter name. Replace it with the actual query string produced by Swagger.

7. Responses

7.1 HTTP 200 — OK

Description: The request was processed successfully.

The response uses the standard EdfaPay response envelope. The data object contains paginated search results.

Response Schema

FieldTypeDescription
codeNumberAPI response code.
messageStringResponse message.
errorCodeStringError identifier, if applicable.
data.totalPagesIntegerTotal number of result pages.
data.totalElementsIntegerTotal number of matching records.
data.sizeIntegerPage size represented in the response.
data.contentArrayMerchant result records. The supplied schema does not define the individual merchant fields.
data.numberIntegerCurrent page number.
data.pageableObjectPagination configuration and metadata.
data.pageable.offsetIntegerOffset of the current page.
data.pageable.pagedBooleanIndicates whether paginated retrieval is being used.
data.pageable.pageNumberIntegerCurrent page number in the pagination configuration.
data.pageable.pageSizeIntegerConfigured page size.
data.pageable.sortArraySorting configuration.
data.pageable.unpagedBooleanIndicates whether the results are unpaged.
data.sortArraySorting information for the result set.
data.numberOfElementsIntegerNumber of elements in the current page.
data.firstBooleanIndicates whether the current page is the first page.
data.lastBooleanIndicates whether the current page is the last page.
data.emptyBooleanIndicates whether the current page contains no records.

Sort Object

Each item in the sort and pageable.sort arrays contains the following fields:

FieldTypeDescription
directionStringSort direction.
nullHandlingStringNull-value handling configuration.
ascendingBooleanIndicates ascending sort order.
propertyStringProperty used for sorting.
ignoreCaseBooleanIndicates whether case is ignored when sorting.

Example Response

{
  "code": 0,
  "message": "string",
  "errorCode": "string",
  "data": {
    "totalPages": 0,
    "totalElements": 0,
    "size": 0,
    "content": [
      {}
    ],
    "number": 0,
    "pageable": {
      "offset": 0,
      "paged": true,
      "pageNumber": 0,
      "pageSize": 0,
      "sort": [
        {
          "direction": "string",
          "nullHandling": "string",
          "ascending": true,
          "property": "string",
          "ignoreCase": true
        }
      ],
      "unpaged": true
    },
    "sort": [
      {
        "direction": "string",
        "nullHandling": "string",
        "ascending": true,
        "property": "string",
        "ignoreCase": true
      }
    ],
    "numberOfElements": 0,
    "first": true,
    "last": true,
    "empty": true
  }
}

The merchant objects inside data.content are represented as {} because the supplied Swagger schema does not expose their fields.

7.2 HTTP 400 — Bad Request

Description: The request could not be processed because of invalid query parameters or other request-related issues.

Example response:

{
  "code": 0,
  "message": "string",
  "errorCode": "string",
  "data": {}
}

The values shown are Swagger placeholders and may differ from actual runtime responses.

8. Implementation Notes

  • Include both pageProperties and searchCriteria as required by the documented endpoint.
  • Use pageNumber: 0 for the first page, following the supplied example.
  • Use pageSize to control the number of records requested per page.
  • Use text and active to filter merchant records.
  • Confirm the URL serialization of query parameter objects through Swagger's Try it out feature.
  • The supplied schema does not define the individual fields returned for each merchant in data.content.
  • Handle HTTP 400 responses by inspecting the returned error details.

9. Summary

The Search Merchants API retrieves merchant records using text and active-status filters, with pagination metadata returned alongside the results. It supports SUPER_ADMIN, PARTNER, and MERCHANT access levels, subject to the authenticated user's permissions.


Did this page help you?