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):
  JSON

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