Activar la cuenta de un comercio

Activar la cuenta de pago fiat de un comercio le da acceso a canales bancarios locales en los países admitidos. Una vez activada, el comercio recibe una cuenta virtual dedicada (por ejemplo, un número CVU/CUIT para Argentina) y puede empezar de inmediato a enviar y recibir fondos por transferencia bancaria o por canales de pago locales. VelaFi concilia automáticamente los depósitos entrantes y los acredita al saldo de la cuenta del comercio. Se admiten cuentas de persona física y de empresa, así que puedes activar cuentas para usuarios finales y clientes corporativos dentro de la misma integración.

Monedas admitidas

Moneda	País	Métodos de pago de ejemplo
`MXN`	México	SPEI mediante Finco Pay, SPEI mediante Tesored
`ARS`	Argentina	CBU/CVU (Momentum), Transferencia 3.0 (QR)
`BRL`	Brasil	Pix (Genial), Pix - Woovi (Avenia)
`COP`	Colombia	PSE, ACH, Bre-B
`PEN`	Perú	Transferencia bancaria
`USD`	EE. UU. / Global	ACH, Wire, SEPA (Lead Bank); Wire, SEPA, FEDWIRE (CPN)
`EUR`	Europa	SEPA (Lead Bank), SEPA (CPN)

Activar una cuenta EUR mediante Lead Bank también habilita transacciones en USD a través de la misma cuenta.

Endpoint

Las activaciones de persona física y de empresa usan el mismo endpoint:

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

Headers

X-BH-TOKEN: <your-token>
Content-Type: application/json

Activar para un comercio persona física

Usa esta ruta cuando el merchantType del comercio sea INDIVIDUAL.

Parámetros principales de la solicitud

string

requerido

El ID del comercio que se devolvió cuando creaste el comercio.

string

requerido

La moneda fiat que se va a activar. Valores aceptados: MXN, ARS, BRL, COP, PEN, USD, EUR.

string

requerido

El canal de pago (proveedor) que se usará para esta moneda. Los valores de trench disponibles dependen del fiat seleccionado. Consulta los ejemplos más abajo para ver la lista completa.

object

Campos adicionales específicos del canal que requiere el trench seleccionado. Los campos obligatorios varían según la moneda y el proveedor; consulta los ejemplos más abajo.

string

Opcional. Para cuentas USD/EUR mediante Lead Bank, la URL a la que se redirige al usuario después de aceptar el acuerdo de la cuenta. Si la omites, se usa una URL de redirección predeterminada de VelaFi.

Solicitudes de ejemplo (persona física)

México MXN — SPEI (Finco Pay)

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

México MXN — SPEI (Tesored)

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

Argentina ARS — CBU/CVU (Momentum)

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

Argentina ARS — Transferencia 3.0 (QR)

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

Brasil BRL — Pix (Genial)

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

Colombia COP — PSE/ACH/Bre-B

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

Perú PEN — Transferencia bancaria

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

EUR/USD — Lead Bank

{
  "merchantId": "100001",
  "fiat": "EUR",
  "trench": "Lead Bank",
  "callbackUri": "https://yourapp.com/account/verified",
  "fieldList": {
    "email": "user@example.com",
    "firstName": "Maria",
    "lastName": "Lopez"
  }
}

Brasil BRL — Pix (Woovi) para personas físicas: primero llama a Obtener la URL de prueba de vida de Woovi y pide al comercio que complete la prueba de vida. Después llama a este endpoint con trench: "Pix - Woovi" y un objeto personalInfo (consulta Activar persona física). Si la prueba de vida no está completa, la solicitud falla con el código de error -5059.

Activar para un comercio empresa

Usa esta ruta cuando el merchantType del comercio sea BUSINESS. El endpoint y los parámetros principales son idénticos; la estructura de fieldList cambia en los canales que requieren información detallada de la empresa y de los UBO (beneficiarios finales). Si tu cuenta no usa Reliance Mode, activar CLABE - FINCO PAY, CLABE - TESORED, CVU - Momentum, QR Argentina, COP Account, BANCO GENIAL o PEN Account para un comercio empresa devuelve status: 0 y un verifyLink para una verificación adicional de la empresa, en lugar de abrir el canal directamente. Consulta Activar empresa.

Solicitudes de ejemplo (empresa)

México MXN — SPEI (Finco Pay)

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

Argentina ARS — CBU/CVU (Momentum)

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

Brasil BRL — Pix (Woovi) — Ejemplo completo de empresa

{
  "merchantId": "100001",
  "fiat": "BRL",
  "trench": "Pix - Woovi",
  "fieldList": {
    "companyInfo": {
      "companyName": "EXEMPLO TECNOLOGIA LTDA.",
      "companyDescription": "Fintech payments provider",
      "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": 50000,
      "companyRegistrationNumber": "00000000000001",
      "taxIdentificationNumberTin": "00000000000002",
      "taxIdentificationDocumentUrl": "100001/00000000-0000-0000-0000-000000000002.pdf",
              "certificateOfIncorporationDocumentUrl": "100001/00000000-0000-0000-0000-000000000003.pdf"
    },
    "companyUbosInfo": [
      {
        "personType": "CEO",
        "firstName": "Ana",
        "lastName": "Souza",
        "email": "ana@example.com",
        "phone": "+5511999999999",
        "percentageOfOwnership": 1,
        "nationality": "BR",
        "taxIdentificationNumber": "000000000000000000",
        "dateOfBirth": "1985-03-22",
        "street1": "Rua das Flores, 42",
        "city": "São Paulo",
        "countryStateCode": "BR-SP",
        "postcode": "01310-100",
        "idType": "3",
        "govIdCountryAbbr": "BR",
        "govIdFrontUrl": "100001/00000000-0000-0000-0000-000000000001.jpg"
      }
    ]
  }
}

EUR/USD — Lead Bank (empresa)

{
  "merchantId": "100001",
  "fiat": "EUR",
  "trench": "Lead Bank",
  "callbackUri": "https://yourapp.com/account/verified",
  "fieldList": {
    "email": "finance@acme.com",
    "companyName": "Acme Payments Ltd"
  }
}

Respuesta

Campos de la respuesta

number

Código de respuesta. 200 indica que la solicitud fue aceptada.

string

Mensaje de resultado legible, por ejemplo SUCCESS.

object

Mostrar campos de data

string

La moneda que se activó.

number

Estado del canal: 0 = inicializado (con un verifyLink, se requiere una verificación adicional de la empresa), 1 = pendiente, 2 = activo, 3 = fallido (consulta failReason), 4 = incompleto (por ejemplo, cuentas de Lead Bank que todavía necesitan los pasos en verifyLink). Consulta periódicamente Listar cuentas del comercio hasta que status sea 2.

string

Un enlace que el comercio debe abrir para continuar la activación. Para cuentas USD/EUR de Lead Bank, lleva al acuerdo de la cuenta; para comercios empresa que necesitan una verificación adicional de la empresa, se devuelve con status: 0.

string

Descripción de cualquier falla. Vacío en caso de éxito.

MXN / ARS / COP / BRL / PEN
USD / EUR

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

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

Cómo se concilian los fondos

Una vez que la cuenta de un comercio está activa, recibe datos bancarios dedicados, como un número CLABE para México o un CVU/CUIT para Argentina. El comercio puede indicar a sus pagadores que envíen transferencias bancarias a esos datos. VelaFi detecta y concilia automáticamente las transferencias entrantes con el saldo del comercio y acredita la cuenta sin que tengas que intervenir manualmente.

Algunas monedas y configuraciones de trench requieren documentación adicional (por ejemplo, documentos de identidad para Brasil Pix - Woovi o actas constitutivas para cuentas de empresa). Escribe a contact@velafi.com para obtener la lista completa de documentos requeridos por país y tipo de cuenta antes de iniciar la activación.

Primeros pasos

Conceptos clave

Guías

Referencia

Activar la cuenta de un comercio

Monedas admitidas

Endpoint

Activar para un comercio persona física

Parámetros principales de la solicitud

Solicitudes de ejemplo (persona física)

Activar para un comercio empresa

Solicitudes de ejemplo (empresa)

Respuesta

Campos de la respuesta

Cómo se concilian los fondos

​Monedas admitidas

​Endpoint

​Activar para un comercio persona física

​Parámetros principales de la solicitud

​Solicitudes de ejemplo (persona física)

​Activar para un comercio empresa

​Solicitudes de ejemplo (empresa)

​Respuesta

​Campos de la respuesta

​Cómo se concilian los fondos

Monedas admitidas

Endpoint

Activar para un comercio persona física

Parámetros principales de la solicitud

Solicitudes de ejemplo (persona física)

Activar para un comercio empresa

Solicitudes de ejemplo (empresa)

Respuesta

Campos de la respuesta

Cómo se concilian los fondos