Merchant Brand

How to build a Merchant Brand query

  1. Required parameters
  2. Optional parameters
  3. Merchant Brand API Response
  4. Usage limits
  5. Example

The Woosmap Merchant API is a REST API that allows fintech entities to “clean” dirty transactions and transforms them into easy-to-check, human-readable data thanks to a clean name and a logo.

The API supports a POST request, which allows batch cleaning of up to 1000 dirty_name at once in a JSON payload. This is particularly indicated for asynchronous back-end implementations.

Requests should be built as follows:

curl -X POST \{your_private_key} \
  -d '{"merchants":[ {
          "dirty_name": "APPLE.COM/BILL"

Alternativley, the API also supports a GET request accepting only 1 dirty_name. See usage limits below.

curl -L -X GET '{your_private_key}&dirty_name=APPLE.COM/BILL'

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 POST 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.


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

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 as sent in the request. 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 on a POST request.

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 name provided.

Usage limits

The following usage limits are in place for the Merchant API on the brand endpoint:


Here is a sample of Merchant API call using JavaScript.

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