Returns a list of cities eligible for a given zip code

API Endpoint: GET /api/v1/merchant/acceptableCities

Overview:

The GET /api/v1/merchant/acceptableCities API method returns a list of cities that are eligible for merchant onboarding based on a specified ZIP code. This endpoint helps verify the cities associated with a ZIP code to ensure that merchants can register from acceptable locations within the payment processing service's coverage area.

Purpose:

This endpoint is used to check which cities are valid for merchant onboarding for a particular ZIP code. It ensures that merchants attempting to onboard can select a valid city tied to their ZIP code, improving accuracy during the registration process.

HTTP Request Method:

  • GET

URL:

  • /api/v1/merchant/acceptableCities

Authentication:

  • Required: Yes
  • Authentication Method: Basic Token or API Key provided in the request header.

Request Headers:

  • Authorization: Basic<token> (required) - Used to authenticate the API call.
  • Content-Type: application/json (optional).

Query Parameters:

  • zipCode (string, required): The ZIP code for which the list of eligible cities is being requested.

Success Response:

  • Status Code: 200 OK
  • Response Body with id 33160 (JSON format):

{ "data": [ { "city": "AVENTURA", "state": "FL", "stateCode": 10 }, { "city": "GOLDEN BEACH", "state": "FL", "stateCode": 10 }, { "city": "MIAMI", "state": "FL", "stateCode": 10 }, { "city": "N MIAMI BEACH", "state": "FL", "stateCode": 10 }, { "city": "SUNNY ISL BCH", "state": "FL", "stateCode": 10 }, { "city": "SUNNY ISLES BEACH", "state": "FL", "stateCode": 10 } ], "success": true }


#### Response Fields:
- `zipCode` (string): The ZIP code provided in the request.
- `eligibleCities` (array of strings): A list of cities that are eligible for onboarding within the specified ZIP code.

#### Error Responses:
- **400 Bad Request:**
- Occurs if the ZIP code is invalid or missing.
- Response body:
  ```json
  {
    "error": "Bad Request",
    "message": "Invalid or missing zip code"
  }
  ```
- **401 Unauthorized:**
- Occurs if the request lacks valid authentication credentials.
- Response body:
  ```json
  {
    "error": "Unauthorized",
    "message": "Invalid or missing token"
  }
  ```
- **404 Not Found:**
- Occurs if no cities are found for the given ZIP code.
- Response body:
  ```json
  {
    "error": "Not Found",
    "message": "No eligible cities found for the provided zip code"
  }
  ```

#### Notes:
- The list of cities returned is specific to the ZIP code and represents cities where merchants can register for the payment processing service.
- If a ZIP code does not have any eligible cities, the API will return a `404 Not Found` error.
Language
Credentials
Basic
base64
:
Click Try It! to start a request and see the response here!