Merchant Brand

How to build a Merchant Brand query

  1. Required parameters
  2. Optional parameters
  3. Merchant Brand 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 allows retrieving different level of information. Here is how to retrieve clean names and logos.

Requests should be built as follows:

curl -X POST \{your_private_key} \
  -d '{"merchants":[ {
          "dirty_name": "APPLE.COM/BILL",
          "description": "APPLE.COM/BILL ITUNES.COM IE WEB 2232445* BR11",
          "country": "IE"

Required parameters

Some parameters are required to initiate a Merchant API request. 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.

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

Optional parameters


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


The country field is not mandatory but strongly suggested in order to refine and be able to differentiate logos from one country to another. The API accepts ISO-3166-1-alpha2 country codes only.


This optional field allows integrators to send a value of their choosing and receive it in the body of the response.

Merchant Brand API Response

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

 "merchants": [{
     "dirty_name": "dirty_name_0",
     "country": "IE",
     "clean_name": "clean_name_0",
     "logo": "logo_id",
     "logo_url": "",
     "status": "OK",
     "custom_id": "my_internal_id_1"
     "dirty_name": "dirty_name_1",
     "country": "",
     "status": "OK",
     "clean_name": "clean_name_1",
     "logo": "",
     "logo_url":  ""
     "dirty_name": "dirty_name_2",
     "country": "GB",
     "status": "NOT_FOUND",
     "clean_name": "",
     "logo": "",
     "logo_url":  ""


Each merchant contains the following fields:
dirty_name: The merchant’s dirty name.
country: The merchant’s country.
clean_name: a clean name for the above merchant.
logo: this is a hash generated for the logo based on the image.
logo_url: The logo image with content type image/png content-type.
status: See Status Codes for a list of possible status codes.
custom_id: Provided by you and returned if specified.

Status Codes

OK when there is a clean name or a clean name and a logo.
NOT_FOUND when there is no clean name or clean name and logo for the specified dirty merchant.


Here is a sample of Merchant API call using JavaScript.

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