Activate an Individual Merchant Account

POST

merchant

accounts

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 an individual merchant. Once activated, the merchant receives dedicated banking credentials (e.g., a CLABE for Mexico, a CVU for Argentina) and can receive inbound wire transfers that VelaFi automatically reconciles to their balance. Each currency and payment provider combination requires a separate activation request.

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 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 one of the supported values for the chosen fiat (see examples below).

string

Redirect URL shown 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

string

The fiat currency that was activated.

number

Channel status: 0 = initialized, 1 = pending, 2 = active, 3 = failed (see failReason), 4 = incomplete (the merchant must finish a step at verifyLink). Which value you get depends on the channel. See Activation Outcomes.

string

For USD/EUR channels that require an additional agreement step, this URL redirects the merchant to the agreement page.

string

Describes why activation failed, if applicable.

Examples by Currency

MXN — SPEI via Finco Pay (trench: "CLABE - FINCO PAY")

cURL

curl -X POST https://api.velafi.com/v2/merchant/accounts \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "100001",
    "fiat": "MXN",
    "trench": "CLABE - FINCO PAY",
    "fieldList": { "alias": "arturo_alias" }
  }'

MXN — SPEI via Tesored (trench: "CLABE - TESORED")

Request body

{
  "merchantId": "100001",
  "fiat": "MXN",
  "trench": "CLABE - TESORED",
  "fieldList": { "alias": "arturo_alias" }
}

ARS — CVU via Momentum (trench: "CVU - Momentum")

Request body

{
  "merchantId": "100001",
  "fiat": "ARS",
  "trench": "CVU - Momentum",
  "fieldList": {
    "email": "arturo@example.com",
    "cuit": "30000000001",
    "name": "EXAMPLE COMPANY SA",
    "alias": "example.alias"
  }
}

ARS — QR 3.0 Transfer (trench: "QR Argentina")

Request body

{
  "merchantId": "100001",
  "fiat": "ARS",
  "trench": "QR Argentina",
  "fieldList": { "cuit": "123456789" }
}

COP — PSE / ACH / Bre-B (trench: "COP Account")

Request body

{
  "merchantId": "100001",
  "fiat": "COP",
  "trench": "COP Account",
  "fieldList": { "alias": "example.alias" }
}

BRL — Pix via Genial (trench: "BANCO GENIAL")

Request body

{
  "merchantId": "100001",
  "fiat": "BRL",
  "trench": "BANCO GENIAL"
}

BRL — Pix via Woovi (trench: "Pix - Woovi") — requires full personal info and a completed liveness checkFollow this order:

Call Get Woovi Liveness URL and have the merchant complete the liveness check at the returned livenessUrl.
Send the activation request below. If the liveness check is not complete, the request fails with error code -5059.
The response returns status: 1 (pending). Poll List Merchant Accounts until the channel status is 2.

Field rules: govIdFrontUrl and govIdBackUrl are both required and must be fileUrl values returned by Upload File. Public URLs are rejected. taxIdentificationNumber may contain only letters and digits. dateOfBirth uses the yyyy-MM-dd format and the person must be at least 18. idType is 1 (ID card), 2 (driver’s license) or 3 (passport). countryStateCode is the two-letter country code, a hyphen and the state code, for example BR-SP.

Request body

{
  "merchantId": "100001",
  "fiat": "BRL",
  "trench": "Pix - Woovi",
  "fieldList": {
    "personalInfo": {
      "firstName": "MARIA",
      "lastName": "EXEMPLO",
      "email": "maria@example.com",
      "taxIdentificationNumber": "00000000001",
      "nationality": "BR",
      "dateOfBirth": "1990-01-01",
      "street1": "Rua das Flores 123",
      "city": "São Paulo",
      "countryStateCode": "BR-SP",
      "postcode": "01310-100",
      "idType": "1",
      "govIdCountryAbbr": "BR",
      "govIdFrontUrl": "100001/00000000-0000-0000-0000-000000000001.png",
      "govIdBackUrl": "100001/00000000-0000-0000-0000-000000000004.png"
    }
  }
}

PEN — Bank Transfer (trench: "PEN Account")

Request body

{
  "merchantId": "100001",
  "fiat": "PEN",
  "trench": "PEN Account",
  "fieldList": {
    "customerIdentificationType": "00",
    "customerIdentification": "12345678",
    "customerName": "Tom",
    "lastName": "Garcia",
    "customerEmail": "tom@example.com",
    "customerPhone": "975728895"
  }
}

USD/EUR — Lead Bank (trench: "Lead Bank")

Request body

{
  "merchantId": "100001",
  "fiat": "EUR",
  "trench": "Lead Bank",
  "callbackUri": "https://your-app.com/agreement-callback",
  "fieldList": {
    "email": "arturo@example.com",
    "firstName": "Arturo",
    "lastName": "Garcia"
  }
}

Multi-currency — Circle Payment Network (trench: "Circle Payment Network")Supports: USD, HKD, EUR, SGD, NGN. Payout only.

Request body

{
  "merchantId": "100001",
  "fiat": "USD",
  "trench": "Circle Payment Network",
  "fieldList": {
    "accountName": "Tom",
    "nationality": "HK",
    "idNumber": "123456",
    "countryStateCode": "HK-HK",
    "city": "Hong Kong",
    "street": "789 Finance Street",
    "postalCode": "123456",
    "dateOfBirth": "1990-01-01",
    "phoneNumber": "123456"
  }
}

Activation Outcomes

Status returned on a first activation

Most local channels return status: 1 (pending) and become 2 (active) once the provider finishes opening the account. Check the channel later with List Merchant Accounts.

Trench	Status returned	Meaning
`CLABE - FINCO PAY`, `CLABE - TESORED` (MXN)	`1`	Pending. The account is being opened.
`CVU - Momentum`, `QR Argentina` (ARS)	`1`	Pending
`COP Account` (COP)	`1`	Pending
`BANCO GENIAL` (BRL)	`1`	Pending
`Pix - Woovi` (BRL, provided by Avenia)	`1`	Pending. Returned only after the merchant has completed the liveness check.
`PEN Account` (PEN)	`2`	Active immediately
`Circle Payment Network`	`2`	Active immediately
`Lead Bank` (USD/EUR)	`4`	Incomplete. Send the merchant to `verifyLink` to accept the agreement and complete verification.

Lead Bank: calling again

If you call this endpoint again for Lead Bank while the merchant already has a Lead Bank verification:

Situation	Status returned
The verification is not finished and can still be resumed	`4` with a new `verifyLink`
The verification is not rejected and does not need to be redone	`3` with `failReason` `Kyc is on processing or completed`

Errors instead of a status

These cases return an error code instead of a status:

Code	When
`-5074`	The channel is already active for this merchant.
`-5062`	The channel’s activation is already pending.
`-5076`	The channel has been closed.
`-5078`	The channel has been disabled.
`-5079`	The merchant has no activation permission for this channel.
`-5073`	The merchant has not passed KYC.
`-5077`	The merchant has been disabled.
`-4010`	A required `fieldList` field is missing or invalid.
`-5059`	The provider could not register the merchant (`msg`: `Merchant registration failure.`). For `Pix - Woovi`, the same code means the liveness check is not complete (`msg`: `Please first pass the Liveness authentication`).
`-5066`	`Pix - Woovi` only: the account is already under review.
`-5067`	`Pix - Woovi` only: the account is already active.

When the provider rejects the registration (-5059), the channel is recorded as failed (3), and you can see it with List Merchant Accounts.

Response Examples

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "fiat": "MXN",
    "status": 1,
    "failReason": ""
  }
}

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "fiat": "PEN",
    "status": 2,
    "failReason": ""
  }
}

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "fiat": "EUR",
    "status": 4,
    "verifyLink": "https://www.velafi.com/business/channel/verify?token=12ceff08",
    "failReason": ""
  }
}

For BRL Woovi, the merchant must complete the Woovi liveness check before you call this endpoint (see Get Woovi Liveness URL). Without it, the request fails with error code -5059. For USD/EUR Lead Bank, the response returns status: 4 with a verifyLink. Direct the merchant to that link to complete the remaining steps.

⌘I

Activate an Individual 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>"
  }
}

Overview

Account

Configuration

Merchants

Crypto Wallet

Beneficiaries

Quotes

Orders

Webhooks

Activate an Individual Merchant Account

Endpoint

Core Request Fields

Response Fields

Examples by Currency

Activation Outcomes

Status returned on a first activation

Lead Bank: calling again

Errors instead of a status

Response Examples

​Endpoint

​Core Request Fields

​Response Fields

​Examples by Currency

​Activation Outcomes

​Status returned on a first activation

​Lead Bank: calling again

​Errors instead of a status

​Response Examples

Endpoint

Core Request Fields

Response Fields

Examples by Currency

Activation Outcomes

Status returned on a first activation

Lead Bank: calling again

Errors instead of a status

Response Examples