Merchants
Activate a Business Merchant Account
Activate a fiat payment channel for a business merchant across MXN, ARS, COP, BRL, PEN, USD, and EUR currencies and payment providers.
POST
/
v2
/
merchant
/
accounts
Activate a Business Merchant Account
curl --request POST \
--url https://api-test.velafi.com/v2/merchant/accounts \
--header 'Content-Type: application/json' \
--header 'X-BH-TOKEN: <api-key>' \
--data '
{
"merchantId": "<string>",
"fiat": "<string>",
"trench": "<string>",
"callbackUri": "<string>",
"fieldList": {}
}
'import requests
url = "https://api-test.velafi.com/v2/merchant/accounts"
payload = {
"merchantId": "<string>",
"fiat": "<string>",
"trench": "<string>",
"callbackUri": "<string>",
"fieldList": {}
}
headers = {
"X-BH-TOKEN": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-BH-TOKEN': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
merchantId: '<string>',
fiat: '<string>',
trench: '<string>',
callbackUri: '<string>',
fieldList: {}
})
};
fetch('https://api-test.velafi.com/v2/merchant/accounts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api-test.velafi.com/v2/merchant/accounts")
.header("X-BH-TOKEN", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"merchantId\": \"<string>\",\n \"fiat\": \"<string>\",\n \"trench\": \"<string>\",\n \"callbackUri\": \"<string>\",\n \"fieldList\": {}\n}")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"fiat": "<string>",
"status": 123,
"verifyLink": "<string>",
"failReason": "<string>"
}
}Use this endpoint to activate one or more fiat payment channels for a business (BUSINESS type) merchant. The process mirrors the individual activation flow, but business accounts typically require fewer personal fields and may instead require company registration data and UBO (Ultimate Beneficial Owner) information depending on the payment provider.
All requests must include the
X-BH-TOKEN header and Content-Type: application/json.Endpoint
POST https://api.velafi.com/v2/merchant/accounts
Core Request Fields
string
required
The ID of the business merchant to activate.
string
required
Target fiat currency. Supported values:
MXN, ARS, COP, BRL, PEN, EUR, USD.string
required
Payment provider or account type identifier. Must match a supported value for the chosen
fiat.string
Redirect URL after the merchant accepts a compliance agreement. Used by Lead Bank channels; if you omit it, a VelaFi default redirect URL is used.
object
Channel-specific fields. Content varies by
fiat and trench. See per-currency examples below.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
string
The fiat currency that was activated.
number
Channel status:
0 = initialized (when returned with a verifyLink, additional business verification is required; see below), 1 = pending (the channel is being opened or reviewed), 2 = active, 3 = failed (see failReason), 4 = incomplete (further steps are required, for example at verifyLink). Poll List Merchant Accounts until status is 2.string
A URL the business must open to continue. It is returned with
status: 0 when additional business verification is required, and for USD/EUR Lead Bank channels, where the business completes the required compliance agreement.string
Describes why activation failed, if applicable.
How Business Activation Works
A business activation takes one of two paths. The response tells you which one applied. Additional business verification (status: 0 with a verifyLink). For a business merchant, the local channels for MXN (CLABE - FINCO PAY, CLABE - TESORED), COP (COP Account), ARS (CVU - Momentum, QR Argentina), BRL (BANCO GENIAL) and PEN (PEN Account) normally require an additional KYB verification for that channel. The response returns status: 0 and a verifyLink. Send the business to the link to complete the verification. After VelaFi approves it, the channel is opened automatically, so you do not need to call this endpoint again. On this path, the fieldList in your request is not used.
Direct activation. If VelaFi has enabled direct activation for your account, the channel is opened from your request and fieldList must contain the channel’s required fields. A missing or invalid field rejects the request.
| Trench | Required fieldList fields |
|---|---|
CLABE - FINCO PAY | alias (up to 40 characters) |
CLABE - TESORED | alias (up to 64 characters) |
COP Account | alias (up to 64 characters) |
CVU - Momentum | cuit, name; alias is optional |
QR Argentina | cuit (up to 40 characters) |
PEN Account | customerIdentificationType, customerIdentification, customerName, customerEmail, customerPhone (digits only, up to 9) |
BANCO GENIAL | None |
Examples by Currency
- MXN
- ARS
- COP / BRL / PEN
- BRL Woovi (Business)
- USD/EUR
MXN — SPEI via Finco Pay (MXN — SPEI via Tesored (
trench: "CLABE - FINCO PAY")Request body
{
"merchantId": "100001",
"fiat": "MXN",
"trench": "CLABE - FINCO PAY"
}
trench: "CLABE - TESORED")Request body
{
"merchantId": "100001",
"fiat": "MXN",
"trench": "CLABE - TESORED"
}
ARS — CVU via Momentum (ARS — QR 3.0 Transfer (
trench: "CVU - Momentum")Request body
{
"merchantId": "100001",
"fiat": "ARS",
"trench": "CVU - Momentum"
}
trench: "QR Argentina")Request body
{
"merchantId": "100001",
"fiat": "ARS",
"trench": "QR Argentina",
"fieldList": { "cuit": "123456789" }
}
COP — PSE / ACH / Bre-B (BRL — Pix via Genial (PEN — Bank Transfer (
trench: "COP Account")Request body
{
"merchantId": "100001",
"fiat": "COP",
"trench": "COP Account"
}
trench: "BANCO GENIAL")Request body
{
"merchantId": "100001",
"fiat": "BRL",
"trench": "BANCO GENIAL"
}
trench: "PEN Account")Request body
{
"merchantId": "100001",
"fiat": "PEN",
"trench": "PEN Account"
}
BRL — Pix via Woovi — requires full company and UBO information.
Request body
{
"merchantId": "100001",
"fiat": "BRL",
"trench": "Pix - Woovi",
"fieldList": {
"companyInfo": {
"companyName": "EXEMPLO TECNOLOGIA LTDA.",
"companyDescription": "Fintech platform",
"countryStateOfIncorporation": "BR-SP",
"website": "example.com.br",
"socialMedia": "@example",
"street1": "Avenida Paulista, 1000",
"city": "São Paulo",
"countryStateCode": "BR-SP",
"postcode": "01310-100",
"reasonForAccountOpening": "ecommerce_retail_payments",
"sourceOfFunds": "sales_of_goods_and_services",
"numberOfEmployees": "11-50",
"estimatedAnnualRevenueUsd": "1m_to_10m",
"estimatedMonthlyVolumeUsd": 10000,
"companyRegistrationNumber": "00000000000001",
"taxIdentificationNumberTin": "00000000000002",
"taxIdentificationDocumentUrl": "100001/00000000-0000-0000-0000-000000000002.pdf",
"certificateOfIncorporationDocumentUrl": "100001/00000000-0000-0000-0000-000000000003.pdf"
},
"companyUbosInfo": [
{
"personType": "CEO",
"firstName": "Maria",
"lastName": "Silva",
"email": "maria@example.com",
"phone": "+5511999990000",
"percentageOfOwnership": 0.51,
"nationality": "BR",
"taxIdentificationNumber": "000000000000000000",
"dateOfBirth": "1985-03-20",
"street1": "Rua Augusta, 500",
"city": "São Paulo",
"countryStateCode": "BR-SP",
"postcode": "01305-000",
"idType": "1",
"govIdCountryAbbr": "BR",
"govIdFrontUrl": "100001/00000000-0000-0000-0000-000000000001.jpg"
}
]
}
}
USD/EUR — Lead Bank (Multi-currency — Circle Payment Network (
trench: "Lead Bank")Request body
{
"merchantId": "100001",
"fiat": "EUR",
"trench": "Lead Bank",
"callbackUri": "https://your-app.com/agreement-callback",
"fieldList": {
"email": "admin@company.com",
"companyName": "Example Company Inc"
}
}
trench: "Circle Payment Network")Supports: USD, HKD, EUR, SGD, NGN. Payout only.Request body
{
"merchantId": "100001",
"fiat": "USD",
"trench": "Circle Payment Network"
}
Response Examples
{
"code": 200,
"msg": "SUCCESS",
"data": {
"fiat": "MXN",
"status": 0,
"verifyLink": "https://verify-sandbox.aiprise.com/?business_onboarding_session_id=xxx",
"failReason": ""
}
}
{
"code": 200,
"msg": "SUCCESS",
"data": {
"fiat": "USD",
"status": 4,
"verifyLink": "https://www.velafi.com/business/channel/verify?token=12ceff08",
"failReason": ""
}
}
Business BRL Woovi activations require complete
companyInfo and 1 to 50 entries in companyUbosInfo. The document fields (certificateOfIncorporationDocumentUrl, taxIdentificationDocumentUrl and each UBO’s govIdFrontUrl) must be fileUrl values returned by Upload File. Public URLs are rejected. Missing or invalid fields cause the activation to fail immediately.Was this page helpful?
⌘I
Activate a Business Merchant Account
curl --request POST \
--url https://api-test.velafi.com/v2/merchant/accounts \
--header 'Content-Type: application/json' \
--header 'X-BH-TOKEN: <api-key>' \
--data '
{
"merchantId": "<string>",
"fiat": "<string>",
"trench": "<string>",
"callbackUri": "<string>",
"fieldList": {}
}
'import requests
url = "https://api-test.velafi.com/v2/merchant/accounts"
payload = {
"merchantId": "<string>",
"fiat": "<string>",
"trench": "<string>",
"callbackUri": "<string>",
"fieldList": {}
}
headers = {
"X-BH-TOKEN": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-BH-TOKEN': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
merchantId: '<string>',
fiat: '<string>',
trench: '<string>',
callbackUri: '<string>',
fieldList: {}
})
};
fetch('https://api-test.velafi.com/v2/merchant/accounts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api-test.velafi.com/v2/merchant/accounts")
.header("X-BH-TOKEN", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"merchantId\": \"<string>\",\n \"fiat\": \"<string>\",\n \"trench\": \"<string>\",\n \"callbackUri\": \"<string>\",\n \"fieldList\": {}\n}")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"fiat": "<string>",
"status": 123,
"verifyLink": "<string>",
"failReason": "<string>"
}
}