Merchants
List Merchants
Retrieve a paginated list of merchants with their KYC verification status, daily and monthly transaction limits, and current usage figures.
GET
/
v2
/
merchants
List Merchants
curl --request GET \
--url https://api-test.velafi.com/v2/merchants \
--header 'X-BH-TOKEN: <api-key>'import requests
url = "https://api-test.velafi.com/v2/merchants"
headers = {"X-BH-TOKEN": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-BH-TOKEN': '<api-key>'}};
fetch('https://api-test.velafi.com/v2/merchants', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.get("https://api-test.velafi.com/v2/merchants")
.header("X-BH-TOKEN", "<api-key>")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"currentPage": 123,
"size": 123,
"total": 123,
"record": [
{
"merchantId": 123,
"country": "<string>",
"merchantName": "<string>",
"email": "<string>",
"merchantType": 123,
"status": 123,
"rejectReason": "<string>",
"upgradeMerchantLimitStatus": 123,
"upgradeMerchantLimitRejectReason": "<string>",
"dayFiatLimit": 123,
"dayFiatUsed": 123,
"monthFiatLimit": 123,
"monthFiatUsed": 123,
"monthCryptoLimit": 123,
"monthCryptoUsed": 123,
"remark": "<string>",
"createTime": "<string>",
"updateTime": "<string>"
}
]
}
}Use this endpoint to query merchants registered under your account. You can filter by name, email, or verification status, and paginate through results. The response includes each merchant’s KYC state, daily and monthly transaction limits, and current usage — useful for monitoring compliance headroom.
All requests must include the
X-BH-TOKEN header with a business token from GET /v2/token/generate.Endpoint
GET https://api.velafi.com/v2/merchants
Query Parameters
string
Filter results by merchant name (partial match supported).
string
Filter results by merchant email address.
integer
Filter by KYC/KYB verification status:
-1— all statuses1— authenticating2— normal (default)3— authentication failed4— incomplete
integer
Page number to retrieve (1-based). Defaults to
1.integer
Number of records per page. Default is
10, maximum is 1000.Response Fields
number
HTTP-style response code.
200 indicates success.string
Human-readable status message, e.g.
SUCCESS.object
Show data fields
Show data fields
number
The current page number returned.
number
Number of records returned on this page.
number
Total number of merchants matching the query.
array
Show record item fields
Show record item fields
number
Unique identifier for the merchant.
string
Country of the merchant.
string
Display name of the merchant.
string
Email address of the merchant.
number
Merchant type:
1 = INDIVIDUAL, 2 = BUSINESS.number
KYC/KYB status:
1 = authenticating, 2 = normal, 3 = failed, 4 = incomplete.string
Reason provided if KYC/KYB verification was rejected.
number
Status of any pending limit upgrade request:
1 = authenticating, 2 = normal, 3 = failed, 4 = incomplete.string
Rejection reason for a limit upgrade request, if applicable.
number
Maximum fiat amount the merchant may transact per day.
number
Fiat amount used against the daily limit so far today.
number
Maximum fiat amount the merchant may transact per calendar month.
number
Fiat amount used against the monthly limit in the current month.
number
Maximum crypto equivalent (in USD) the merchant may transact per month.
number
Crypto equivalent used against the monthly crypto limit.
string
Free-text remark attached to the merchant record.
string
Unix timestamp (milliseconds) when the merchant was created.
string
Unix timestamp (milliseconds) when the merchant record was last updated.
Example
cURL
curl -G https://api.velafi.com/v2/merchants \
-H "X-BH-TOKEN: YOUR_TOKEN" \
--data-urlencode "status=-1" \
--data-urlencode "currentPage=1" \
--data-urlencode "pageSize=10"
Response
{
"code": 200,
"msg": "SUCCESS",
"data": {
"currentPage": 1,
"size": 10,
"total": 100,
"record": [
{
"merchantId": 1,
"country": "Mexico",
"merchantName": "Example Merchant",
"email": "merchant@example.com",
"merchantType": 1,
"status": 2,
"rejectReason": "",
"upgradeMerchantLimitStatus": 2,
"upgradeMerchantLimitRejectReason": "",
"dayFiatLimit": 25000.0,
"dayFiatUsed": 0.0,
"monthFiatLimit": 25000.0,
"monthFiatUsed": 0.0,
"monthCryptoLimit": 15000.0,
"monthCryptoUsed": 0.0,
"remark": "",
"createTime": "1737452292000",
"updateTime": "1737452344000"
}
]
}
}
Use
status=-1 to retrieve merchants at all KYC stages, including those that failed or are still in progress.Was this page helpful?
⌘I
List Merchants
curl --request GET \
--url https://api-test.velafi.com/v2/merchants \
--header 'X-BH-TOKEN: <api-key>'import requests
url = "https://api-test.velafi.com/v2/merchants"
headers = {"X-BH-TOKEN": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-BH-TOKEN': '<api-key>'}};
fetch('https://api-test.velafi.com/v2/merchants', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.get("https://api-test.velafi.com/v2/merchants")
.header("X-BH-TOKEN", "<api-key>")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"currentPage": 123,
"size": 123,
"total": 123,
"record": [
{
"merchantId": 123,
"country": "<string>",
"merchantName": "<string>",
"email": "<string>",
"merchantType": 123,
"status": 123,
"rejectReason": "<string>",
"upgradeMerchantLimitStatus": 123,
"upgradeMerchantLimitRejectReason": "<string>",
"dayFiatLimit": 123,
"dayFiatUsed": 123,
"monthFiatLimit": 123,
"monthFiatUsed": 123,
"monthCryptoLimit": 123,
"monthCryptoUsed": 123,
"remark": "<string>",
"createTime": "<string>",
"updateTime": "<string>"
}
]
}
}