Merchant Place

How to build a Merchant Place Query

  1. Required parameters
  2. Optional parameters
  3. Merchant Place API Response
  4. Example

The Woosmap Merchant API supports POST request, passing in your “dirty” transactions as JSON objects in the request body. There are currently two different endpoints which allow retrieving different level of information. Here is how to retrieve a Google Maps Place ID in addition to clean names and logos.

Requests should be built as follows:

curl -X POST \{your_private_key} \
  -d '{"merchants":[ {
		  "dirty_name": "MCDO UK 2231 EP",
		  "country": "GB",
		  "merchant_id": "234482729011"

Required parameters

Some parameters are required to initiate a Merchant API request on the Place endpoint. These parameters are specified below. Only the API key is set in the URL parameters. Other parameters are set in the body of the request.


It is your own project’s API key. This key identifies your Woosmap Project for purposes of quota management. We recommend using a private key to perform queries to the API.

Said API key should be set as Read Only.

Please refer to the documentation to get an API key if necessary.


The dirty_name is the unique merchant identifier which is provided on transactions by a payment provider.


The merchant_id, also known as MID, is a code attached to a merchant name in the transaction’s payload of the payment provider.


The country field is mandatory on the Place endpoint. The API accepts ISO-3166-1-alpha2 country codes only.

One POST request cannot accept more than 1000 dirty merchants. If you need to clean more merchants, please do multiple requests.

Optional parameters

The parameters below are non-mandatory but are highly recommended to retrieve a Place ID.


The description is provided to you by the payment provider and is the transaction description attached to any payment.


The merchant’s street, typically found in the raw transaction.


The merchant’s zipcode.


The merchant’s city.


The merchant’s state.


The geographic coordinates where the transaction occurred. Retrieving this information can be achieved by leveraging our open-source Geofencing SDK (see our Community website to access it). Sending in a position will significantly increase the possibility of finding a Place ID.

Merchant Place API Response

The Woosmap Merchant API provides a JSON response containing an array of merchants, each containing dirty_name, country, clean_name, logo, logo_url and status.

 "merchants": [{
     "dirty_name": "dirty_name_0",
     "clean_name": "clean_name_0",
     "status": "OK",
     "logo": "logo_id_0",
     "logo_url": "",
     "country": "US",
     "merchant_id": "1070060999900835",
     "place_id": "ChIJgUbEo8cfqokR5lP9_Wh_DaM"
     "dirty_name": "dirty_name_1",
     "clean_name": "clean_name_1",
     "status": "OK",
     "logo": "",
     "logo_url": "",
     "country": "US",
     "merchant_id": "107896500200825",
     "place_id": ""
     "dirty_name": "dirty_name_2",
     "clean_name": "",
     "status": "OK",
     "logo": "",
     "logo_url": "",
     "country": "GB",
     "merchant_id": "107006500234835",
     "place_id": "ChIJgUbEo8cfqokR5lP9_Btz3"
     "dirty_name": "dirty_name_3",
     "clean_name": "",
     "status": "NOT_FOUND",
     "logo": "",
     "logo_url": "",
     "country": "FR",
     "merchant_id": "1070065986574835",
     "place_id": ""


Each merchant contains the following fields:
dirty_name: The merchant’s dirty name.
clean_name: A clean name for the above merchant, when available.
status: See Status Codes for a list of possible status codes.
logo: This is a hash generated for the logo based on the image.
logo_url: The logo image with image/png content-type.
country: The merchant’s country.
merchant_id: Provided by you and return to help you to sort results.
place_id : The Google Maps Place ID of the merchant’s location.

Status Codes

OK when an information is found on a dirty merchant. It can be a clean name, a logo, a Place ID, or all of them.
NOT_FOUND when no added information can be returned for the transaction.


Here is a sample of Merchant API call using JavaScript.

Was this article helpful?
Have more questions? Submit a request