Activar la cuenta de un comercio persona física

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 persona física. Una vez activado, el comercio recibe credenciales bancarias dedicadas (por ejemplo, una CLABE para México o un CVU para Argentina) y puede recibir transferencias bancarias entrantes que VelaFi concilia automáticamente con su saldo. Cada combinación de moneda y proveedor de pago requiere una solicitud de activación por separado.

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 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 uno de los valores admitidos para el fiat elegido (consulta los ejemplos más abajo).

string

URL de redirección que se muestra 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 tipo 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, 1 = pendiente, 2 = activo, 3 = fallido (consulta failReason), 4 = incompleto (el comercio debe completar un paso en verifyLink). El valor que recibes depende del canal. Consulta Resultados de la activación.

string

Para los canales USD/EUR que requieren un paso adicional de aceptación de acuerdo, esta URL redirige al comercio a la página del acuerdo.

string

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

Ejemplos por moneda

MXN — SPEI mediante 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 mediante Tesored (trench: "CLABE - TESORED")

Request body

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

ARS — CVU mediante 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 — 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",
  "fieldList": { "alias": "example.alias" }
}

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

Request body

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

BRL — Pix mediante Woovi (trench: "Pix - Woovi") — requiere información personal completa y una prueba de vida completadaSigue este orden:

Llama a Obtener la URL de prueba de vida de Woovi y pide al comercio que complete la prueba de vida en el livenessUrl devuelto.
Envía la solicitud de activación de abajo. Si la prueba de vida no está completa, la solicitud falla con el código de error -5059.
La respuesta devuelve status: 1 (pendiente). Consulta periódicamente Listar cuentas del comercio hasta que el status del canal sea 2.

Reglas de los campos: govIdFrontUrl y govIdBackUrl son obligatorios y deben ser valores fileUrl devueltos por Subir archivo. Las URL públicas se rechazan. taxIdentificationNumber solo puede contener letras y dígitos. dateOfBirth usa el formato yyyy-MM-dd y la persona debe tener al menos 18 años. idType es 1 (documento de identidad), 2 (licencia de conducir) o 3 (pasaporte). countryStateCode es el código de país de dos letras, un guion y el código del estado, por ejemplo 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 — Transferencia bancaria (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"
  }
}

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

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

Resultados de la activación

Estado devuelto en una primera activación

La mayoría de los canales locales devuelven status: 1 (pendiente) y pasan a 2 (activo) una vez que el proveedor termina de abrir la cuenta. Revisa el canal más tarde con Listar cuentas del comercio.

Trench	Estado devuelto	Significado
`CLABE - FINCO PAY`, `CLABE - TESORED` (MXN)	`1`	Pendiente. La cuenta se está abriendo.
`CVU - Momentum`, `QR Argentina` (ARS)	`1`	Pendiente
`COP Account` (COP)	`1`	Pendiente
`BANCO GENIAL` (BRL)	`1`	Pendiente
`Pix - Woovi` (BRL, proporcionado por Avenia)	`1`	Pendiente. Solo se devuelve después de que el comercio completó la prueba de vida.
`PEN Account` (PEN)	`2`	Activo de inmediato
`Circle Payment Network`	`2`	Activo de inmediato
`Lead Bank` (USD/EUR)	`4`	Incompleto. Envía al comercio a `verifyLink` para aceptar el acuerdo y completar la verificación.

Lead Bank: volver a llamar

Si vuelves a llamar a este endpoint para Lead Bank cuando el comercio ya tiene una verificación de Lead Bank:

Situación	Estado devuelto
La verificación no ha terminado y todavía se puede reanudar	`4` con un nuevo `verifyLink`
La verificación no fue rechazada y no es necesario rehacerla	`3` con `failReason` `Kyc is on processing or completed`

Errores en lugar de un estado

En estos casos se devuelve un código de error en lugar de un status:

Código	Cuándo
`-5074`	El canal ya está activo para este comercio.
`-5062`	La activación del canal ya está pendiente.
`-5076`	El canal fue cerrado.
`-5078`	El canal fue deshabilitado.
`-5079`	El comercio no tiene permiso de activación para este canal.
`-5073`	El comercio no ha aprobado el KYC.
`-5077`	El comercio fue deshabilitado.
`-4010`	Falta un campo obligatorio de `fieldList` o no es válido.
`-5059`	El proveedor no pudo registrar al comercio (`msg`: `Merchant registration failure.`). Para `Pix - Woovi`, el mismo código significa que la prueba de vida no está completa (`msg`: `Please first pass the Liveness authentication`).
`-5066`	Solo `Pix - Woovi`: la cuenta ya está en revisión.
`-5067`	Solo `Pix - Woovi`: la cuenta ya está activa.

Cuando el proveedor rechaza el registro (-5059), el canal se registra como fallido (3) y puedes verlo con Listar cuentas del comercio.

Ejemplos de respuesta

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

Para BRL Woovi, el comercio debe completar la prueba de vida de Woovi antes de que llames a este endpoint (consulta Obtener la URL de prueba de vida de Woovi). Sin ella, la solicitud falla con el código de error -5059. Para USD/EUR con Lead Bank, la respuesta devuelve status: 4 con un verifyLink. Dirige al comercio a ese enlace para completar los pasos restantes.

⌘I

Activar la cuenta de un comercio persona física

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 persona física

Endpoint

Campos principales de la solicitud

Campos de la respuesta

Ejemplos por moneda

Resultados de la activación

Estado devuelto en una primera activación

Lead Bank: volver a llamar

Errores en lugar de un estado

Ejemplos de respuesta

​Endpoint

​Campos principales de la solicitud

​Campos de la respuesta

​Ejemplos por moneda

​Resultados de la activación

​Estado devuelto en una primera activación

​Lead Bank: volver a llamar

​Errores en lugar de un estado

​Ejemplos de respuesta

Endpoint

Campos principales de la solicitud

Campos de la respuesta

Ejemplos por moneda

Resultados de la activación

Estado devuelto en una primera activación

Lead Bank: volver a llamar

Errores en lugar de un estado

Ejemplos de respuesta