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
| Property | Value |
|---|---|
| API Name | Search Merchants |
| HTTP Method | GET |
| Endpoint | /api/v1/merchant/search |
| Production Base URL | https://app-api.edfapay.com |
| Accept | */* |
| Request Body | Not required |
3. Authentication
Include the API key in the request headers.
| Header | Value |
|---|---|
X-API-KEY | YOUR_API_KEY |
Accept | */* |
4. Query Parameters
The endpoint defines two required query parameter objects: pageProperties and searchCriteria.
4.1 pageProperties
pagePropertiesControls pagination for the merchant search results.
| Field | Type | Description |
|---|---|---|
pageNumber | Integer | Page number. The example uses zero-based pagination, starting at 0. |
pageSize | Integer | Number of records requested per page. |
Example:
{
"pageNumber": 0,
"pageSize": 10
}4.2 searchCriteria
searchCriteriaDefines the criteria used to filter merchant records.
| Field | Type | Description |
|---|---|---|
text | String | Text used to search merchant records. |
active | Boolean | Filters 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
| Field | Type | Description |
|---|---|---|
code | Number | API response code. |
message | String | Response message. |
errorCode | String | Error identifier, if applicable. |
data.totalPages | Integer | Total number of result pages. |
data.totalElements | Integer | Total number of matching records. |
data.size | Integer | Page size represented in the response. |
data.content | Array | Merchant result records. The supplied schema does not define the individual merchant fields. |
data.number | Integer | Current page number. |
data.pageable | Object | Pagination configuration and metadata. |
data.pageable.offset | Integer | Offset of the current page. |
data.pageable.paged | Boolean | Indicates whether paginated retrieval is being used. |
data.pageable.pageNumber | Integer | Current page number in the pagination configuration. |
data.pageable.pageSize | Integer | Configured page size. |
data.pageable.sort | Array | Sorting configuration. |
data.pageable.unpaged | Boolean | Indicates whether the results are unpaged. |
data.sort | Array | Sorting information for the result set. |
data.numberOfElements | Integer | Number of elements in the current page. |
data.first | Boolean | Indicates whether the current page is the first page. |
data.last | Boolean | Indicates whether the current page is the last page. |
data.empty | Boolean | Indicates whether the current page contains no records. |
Sort Object
Each item in the sort and pageable.sort arrays contains the following fields:
| Field | Type | Description |
|---|---|---|
direction | String | Sort direction. |
nullHandling | String | Null-value handling configuration. |
ascending | Boolean | Indicates ascending sort order. |
property | String | Property used for sorting. |
ignoreCase | Boolean | Indicates 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
pagePropertiesandsearchCriteriaas required by the documented endpoint. - Use
pageNumber: 0for the first page, following the supplied example. - Use
pageSizeto control the number of records requested per page. - Use
textandactiveto 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
400responses 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.
Updated 25 days ago