Merchant Brand
How to build a Merchant Brand query
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 \
https://api.woosmap.com/merchants/brand?private_key={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 'https://api.woosmap.com/merchants/brand?private_key={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.
https://api.woosmap.com/merchants/brand?private_key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx
private_key
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.
dirty_name
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
description
The description is provided to you by the payment provider and is the transaction description attached to any payment.
custom_id
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": "https://api.woosmap.com/merchants/logos/logo_id.png",
"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": ""
}
]
}
Merchants
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:
POSTMaximum of 2 queries per second (QPS) per Project (so possibly the sum of client-side and server-side queries) - up to 1000dirty_nameper JSON in the body of the requestGETMaximum of 50 queries per second (QPS) per Project (so possibly the sum of client-side and server-side queries) - only 1dirty_nameper request
Example
Here is a sample of Merchant API call using JavaScript.