API de Vizum

Conecta tu ERP, tesorería o plataforma con Vizum para consultar saldos, dar de alta beneficiarios y crear pagos nacionales e internacionales sin entrar al panel.

La API es REST sobre HTTPS, recibe y devuelve JSON, y es un espejo del panel de Vizum: lo que tu sistema hace por API es exactamente lo que tu equipo puede hacer en el panel, con los mismos permisos, las mismas comisiones y la misma revisión.

Antes de empezar

• Todo pago pasa por la revisión de Vizum. Crear un pago lo deja en pending; Vizum lo revisa y lo envía. Igual que en el panel, un cliente no puede ejecutar el envío por su cuenta.
• El tipo de cambio es indicativo. No existe una cotización con folio ni vencimiento: el pago toma el tipo de cambio vigente al crearse. Ver Montos y tipo de cambio.
• Toda escritura lleva Idempotency-Key. Es obligatorio. Ver Idempotencia.

Ambientes

Hay dos ambientes, cada uno con sus propias llaves. Una llave de pruebas no funciona en producción ni al revés.

Todas las rutas de esta documentación son relativas a la URL base. Por ejemplo, GET /accounts es GET https://open.vizum.mx/v1/accounts.

Llama a la API desde tu servidor. No pongas tu llave en código que corra en el navegador de tus usuarios: quien la vea puede operar con ella.

Autenticación

Cada llamada se autentica con una llave de API en el header X-Api-Key. Las llaves empiezan con vzk_.

curl https://open.vizum.mx/v1/accounts \
  -H "X-Api-Key: vzk_tu_llave"

Crear una llave

1. Entra al panel de Vizum y ve a Configuración → API y Webhooks → API keys.
2. Ponle un nombre, elige sus alcances y, si quieres, las IPs desde las que va a funcionar y una vigencia en días (hasta 3,650).
3. Copia la llave. Se muestra una sola vez: Vizum guarda sólo su huella y después únicamente ve sus primeros caracteres. Si la pierdes, revócala y crea otra.

La llave actúa a nombre del usuario que la creó: alcanza las mismas cuentas que ese usuario y nunca más permisos que los que tiene en el panel. Si el usuario deja de estar activo, sus llaves dejan de funcionar.

Alcances

Cada llave lleva una lista de alcances. Una ruta exige un alcance concreto, y leer no habilita escribir: una llave de sólo lectura no puede mover dinero ni cambiar a quién se le paga.

Para escribir no basta el alcance de la llave: el usuario dueño de la llave también tiene que tener ese permiso en la cuenta, igual que en el panel.

Restricción por IP

Puedes limitar una llave a una lista de hasta 50 IPs o rangos CIDR (por ejemplo 203.0.113.10 o 203.0.113.0/24). Una lista vacía significa sin restricción. La lista se puede cambiar desde el panel sin volver a emitir la llave. Recomendamos usarla siempre en producción.

Respuestas de autenticación

Guía rápida: tu primer pago

El flujo completo, de la llave al pago, usando el ambiente de pruebas.

1. Encuentra tu cuenta. GET /accounts devuelve tus razones sociales. Guarda el id de la que va a pagar.
2. Elige la wallet de origen. GET /accounts/{accountId}/wallets te da las wallets de esa cuenta, su moneda y su saldo.
3. Pregunta qué datos pide el corredor. POST /accounts/{accountId}/beneficiary-requirements con país, moneda y tipo de entidad. Dibuja tu formulario con lo que regrese; no supongas campos.
4. Da de alta al beneficiario. POST /accounts/{accountId}/beneficiaries con esos datos en details. Si registration viene en ready, ya le puedes pagar.
5. Cotiza. GET /accounts/{accountId}/exchange-rates para el tipo de cambio indicativo y POST /accounts/{accountId}/transactions/calculate-fee para las comisiones.
6. Crea el pago. POST /accounts/{accountId}/transactions con un Idempotency-Key nuevo. Queda en pending, esperando la revisión de Vizum.
7. Si es diferido, fondéalo. Un pago con isPayLater: true no debita la wallet hasta que llamas POST .../pay-now.
8. Sigue su estatus. Consulta GET /transactions/{transactionId} hasta que llegue a un estatus final. Su línea de tiempo viene en events.

# 1. Tu cuenta
curl https://dev.open.vizum.mx/v1/accounts -H "X-Api-Key: $VIZUM_KEY"

# 2. Sus wallets
curl https://dev.open.vizum.mx/v1/accounts/$ACCOUNT_ID/wallets -H "X-Api-Key: $VIZUM_KEY"

# 6. El pago (una llave de idempotencia nueva por pago)
curl -X POST https://dev.open.vizum.mx/v1/accounts/$ACCOUNT_ID/transactions \
  -H "X-Api-Key: $VIZUM_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "walletId": "'$WALLET_ID'",
    "beneficiaryId": "'$BENEFICIARY_ID'",
    "sourceCurrencyCode": "MXN",
    "sourceAmount": "15000.00",
    "concept": "Factura 1042"
  }'

Idempotencia

Toda escritura (crear o editar beneficiario, crear pago, fondear pago diferido) exige el header Idempotency-Key. Sin él la API responde 400 IDEMPOTENCY_KEY_REQUIRED y no ejecuta nada.

Genera un valor único por operación (un UUID sirve, hasta 255 caracteres) y repite el mismo valor si reintentas. Así, si tu sistema reintenta por un timeout sin saber si el pago se creó, el reintento no crea un segundo pago.

Si la operación falla (por ejemplo, un dato inválido), la llave se libera: corriges y reintentas con la misma. Las llaves se aíslan por cuenta y por endpoint, y el orden de los campos del JSON no importa.

Las consultas que usan POST sólo porque llevan cuerpo (beneficiary-requirements y calculate-fee) no escriben nada y no piden la llave.

Límites de uso

Cada llave tiene un presupuesto de 120 llamadas por minuto. El límite es por cliente, no por IP. Cada respuesta trae el estado de tu presupuesto:

x-ratelimit-limit-whitelabel: 120
x-ratelimit-remaining-whitelabel: 119
x-ratelimit-reset-whitelabel: 60

Al agotarlo la API responde 429. Espera los segundos que indica x-ratelimit-reset-whitelabel antes de reintentar.

Cada respuesta trae también x-request-id. Inclúyelo si nos escribes a soporte por una llamada concreta.

Paginación

Las listas de beneficiarios y de pagos son paginadas, del más reciente al más antiguo.

{
  "data": [ ... ],
  "total": 57,
  "page": 1,
  "limit": 30,
  "totalPages": 2
}

Un parámetro que la ruta no reconoce se rechaza con 400 en vez de ignorarse.

Errores

Los errores usan los códigos HTTP estándar y un cuerpo JSON. Siempre traen statusCode, message, requestId, path y timestamp, salvo el 404 de una ruta que no existe, que sólo trae statusCode y message. Según el error, traen además uno de estos identificadores estables, que es en lo que debe basarse tu código:

• reason: errores de acceso, idempotencia y validación de la API (por ejemplo SCOPE_DENIED), a veces con campos extra como scope o accountId.
• code y userMessage: errores de negocio al operar (saldo, beneficiario, pago). userMessage está pensado para mostrarse a tu usuario.

{
  "statusCode": 403,
  "message": "Esa cuenta no está disponible para esta credencial. Si es una razón social tuya, cada cuenta se habilita por separado: revisa que su onboarding esté completo y que la cuenta esté activa.",
  "reason": "ACCOUNT_NOT_AVAILABLE",
  "accountId": "0a0a0a0a-0000-4000-8000-000000000000",
  "requestId": "66c567eb-ed6e-424d-8c28-d0eca9986385",
  "path": "/api/v1/whitelabel/accounts/0a0a0a0a-0000-4000-8000-000000000000/wallets",
  "timestamp": "2026-10-27T10:48:02.855Z"
}

{
  "statusCode": 422,
  "code": "TRANSACTION_NOT_PROCESSABLE",
  "message": "No se pudo procesar esta operación con los datos enviados. Verifica los datos o intenta de nuevo más tarde.",
  "userMessage": "No se pudo procesar esta operación con los datos enviados. Verifica los datos o intenta de nuevo más tarde.",
  "requestId": "…",
  "path": "…",
  "timestamp": "…"
}

Cuando la validación del cuerpo o de los parámetros falla, message es una lista con cada problema, por ejemplo ["property foo should not exist"].

Códigos HTTP

Identificadores de error de la API

Estatus de un pago

La API no envía notificaciones de cambio de estatus: consulta GET /transactions/{transactionId} periódicamente mientras el pago no esté en un estatus final. Un intervalo de uno o dos minutos sobra; respeta los límites de uso.

Montos y tipo de cambio

• Los montos son cadenas, no números: "15000.00". Así no se pierden centavos en montos grandes. Mándalos igual.
• Monedas en ISO 4217 (MXN, USD, EUR) y países en ISO 3166-1 alfa-2 (MX, US).
• Fechas en ISO 8601, UTC.
• Un pago se ancla por un solo lado. Manda sourceAmount (lo que sale de tu wallet) o targetAmount (lo que le llega al beneficiario). El otro lo calcula Vizum con el tipo de cambio del momento.
• El tipo de cambio es indicativo. indicativeRate ya incluye el margen de tu cuenta y es el que se aplicaría si creas el pago en ese momento. validUntil es la vigencia del dato en caché, no un precio garantizado. Si necesitas certeza del monto que sale, ancla el pago con sourceAmount.
• null significa "no aplica" o "no hay dato", nunca cero. Una comisión en null no es una comisión de cero pesos.

Versionado

La versión va en la ruta: /v1. Dentro de una versión sólo hacemos cambios compatibles: agregar endpoints, agregar campos a las respuestas o agregar parámetros opcionales. Tu integración debe ignorar los campos que no conozca. Quitar o renombrar un campo, o cambiar su tipo, sólo ocurre en una versión nueva.