Activar la cuenta de un comercio empresa

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>"
  }
}

Usa este endpoint para activar uno o más canales de pago fiat para un comercio empresarial (tipo BUSINESS). El proceso es similar al flujo de activación de personas físicas, pero las cuentas empresariales normalmente requieren menos campos personales y, según el proveedor de pago, pueden requerir en cambio datos de registro de la empresa e información del UBO (beneficiario final).

Todas las solicitudes deben incluir el header X-BH-TOKEN y Content-Type: application/json.

Endpoint

POST https://api.velafi.com/v2/merchant/accounts

Campos principales de la solicitud

string

requerido

El ID del comercio empresarial que se va a activar.

string

requerido

Moneda fiat de destino. Valores admitidos: MXN, ARS, COP, BRL, PEN, EUR, USD.

string

requerido

Identificador del proveedor de pago o del tipo de cuenta. Debe coincidir con un valor admitido para el fiat elegido.

string

URL de redirección después de que el comercio acepta un acuerdo de cumplimiento. La usan los canales de Lead Bank; si la omites, se usa una URL de redirección predeterminada de VelaFi.

object

Campos específicos del canal. El contenido varía según fiat y trench. Consulta los ejemplos por moneda más abajo.

Campos de la respuesta

number

Código de respuesta de estilo HTTP. 200 indica éxito.

string

Mensaje de estado legible, por ejemplo SUCCESS.

object

Mostrar campos de data

string

La moneda fiat que se activó.

number

Estado del canal: 0 = inicializado (cuando se devuelve con un verifyLink, se requiere una verificación adicional de la empresa; consulta más abajo), 1 = pendiente (el canal se está abriendo o revisando), 2 = activo, 3 = fallido (consulta failReason), 4 = incompleto (se requieren pasos adicionales, por ejemplo en verifyLink). Consulta Listar cuentas del comercio periódicamente hasta que status sea 2.

string

Una URL que la empresa debe abrir para continuar. Se devuelve con status: 0 cuando se requiere una verificación adicional de la empresa, y para los canales USD/EUR de Lead Bank, donde la empresa completa el acuerdo de cumplimiento requerido.

string

Describe por qué falló la activación, si aplica.

Cómo funciona la activación empresarial

Una activación empresarial sigue uno de dos caminos. La respuesta te indica cuál se aplicó. Verificación adicional de la empresa (status: 0 con un verifyLink). Para un comercio empresarial, los canales locales de MXN (CLABE - FINCO PAY, CLABE - TESORED), COP (COP Account), ARS (CVU - Momentum, QR Argentina), BRL (BANCO GENIAL) y PEN (PEN Account) normalmente requieren una verificación KYB adicional para ese canal. La respuesta devuelve status: 0 y un verifyLink. Envía a la empresa al enlace para que complete la verificación. Cuando VelaFi la aprueba, el canal se abre automáticamente, así que no necesitas volver a llamar a este endpoint. En este camino, el fieldList de tu solicitud no se usa. Activación directa. Si VelaFi habilitó la activación directa para tu cuenta, el canal se abre a partir de tu solicitud y fieldList debe contener los campos obligatorios del canal. Si falta un campo o es inválido, la solicitud se rechaza.

Trench	Campos obligatorios de `fieldList`
`CLABE - FINCO PAY`	`alias` (hasta 40 caracteres)
`CLABE - TESORED`	`alias` (hasta 64 caracteres)
`COP Account`	`alias` (hasta 64 caracteres)
`CVU - Momentum`	`cuit`, `name`; `alias` es opcional
`QR Argentina`	`cuit` (hasta 40 caracteres)
`PEN Account`	`customerIdentificationType`, `customerIdentification`, `customerName`, `customerEmail`, `customerPhone` (solo dígitos, hasta 9)
`BANCO GENIAL`	Ninguno

Ejemplos por moneda

MXN
ARS
COP / BRL / PEN
BRL Woovi (empresa)
USD/EUR

MXN: SPEI vía Finco Pay (trench: "CLABE - FINCO PAY")

Request body

{
  "merchantId": "100001",
  "fiat": "MXN",
  "trench": "CLABE - FINCO PAY"
}

MXN: SPEI vía Tesored (trench: "CLABE - TESORED")

Request body

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

ARS: CVU vía Momentum (trench: "CVU - Momentum")

Request body

{
  "merchantId": "100001",
  "fiat": "ARS",
  "trench": "CVU - Momentum"
}

ARS: transferencia QR 3.0 (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"
}

BRL: Pix vía Genial (trench: "BANCO GENIAL")

Request body

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

PEN: transferencia bancaria (trench: "PEN Account")

Request body

{
  "merchantId": "100001",
  "fiat": "PEN",
  "trench": "PEN Account"
}

BRL: Pix vía Woovi. Requiere la información completa de la empresa y de los UBO.

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 (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"
  }
}

Multimoneda: Circle Payment Network (trench: "Circle Payment Network")Admite: USD, HKD, EUR, SGD, NGN. Solo pagos (payout).

Request body

{
  "merchantId": "100001",
  "fiat": "USD",
  "trench": "Circle Payment Network"
}

Ejemplos de respuesta

{
  "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": ""
  }
}

Las activaciones empresariales de BRL Woovi requieren un companyInfo completo y de 1 a 50 entradas en companyUbosInfo. Los campos de documentos (certificateOfIncorporationDocumentUrl, taxIdentificationDocumentUrl y el govIdFrontUrl de cada UBO) deben ser valores fileUrl devueltos por Subir archivo. Las URL públicas se rechazan. Si faltan campos o son inválidos, la activación falla de inmediato.

⌘I

Activar la cuenta de un comercio empresa

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>"
  }
}

Descripción general

Cuenta

Configuración

Comercios

Billetera cripto

Beneficiarios

Cotizaciones

Órdenes

Webhooks

Activar la cuenta de un comercio empresa

Endpoint

Campos principales de la solicitud

Campos de la respuesta

Cómo funciona la activación empresarial

Ejemplos por moneda

Ejemplos de respuesta

​Endpoint

​Campos principales de la solicitud

​Campos de la respuesta

​Cómo funciona la activación empresarial

​Ejemplos por moneda

​Ejemplos de respuesta

Endpoint

Campos principales de la solicitud

Campos de la respuesta

Cómo funciona la activación empresarial

Ejemplos por moneda

Ejemplos de respuesta