Cómo Usar la API de Plaid (Guía para Desarrolladores 2026)

Las aplicaciones fintech rara vez comienzan desde cero hoy en día. Cuando un usuario vincula una cuenta corriente a tu aplicación, probablemente Plaid está en el medio, traduciendo los inicios de sesión bancarios a un JSON limpio que tu backend pueda consumir. La API de Plaid permite la vinculación de cuentas, comprobaciones de saldo, historial de transacciones y verificación de identidad para miles de aplicaciones como Venmo, Robinhood y Chime.

Prueba Apidog hoy

En esta guía verás cómo usar la API de Plaid desde el punto de vista de un desarrollador: cómo obtener claves, cómo funciona el flujo de token de Link, qué productos debes conocer y los errores más frecuentes en producción. Además, aprenderás cómo probar cada paso con Apidog para dejar de adivinar las cargas útiles de las solicitudes. Para información oficial, mantén la documentación oficial de Plaid abierta en otra pestaña.

La banca abierta es un sector competido, y Plaid es una opción entre varias. Si aún comparas proveedores, revisa nuestro resumen de las mejores APIs de banca abierta. Para esta guía, asumimos que ya elegiste Plaid y quieres implementarlo.

TL;DR

• Plaid es un agregador de datos financieros que conecta tu app con más de 12,000 bancos en EE. UU., Canadá y Europa.
• Dispones de tres entornos: sandbox (gratis, datos simulados), development (100 Items reales gratuitos), production (pago por uso).
• El flujo de vinculación consiste en 4 pasos: crea link_token (servidor), abre Plaid Link (cliente), intercambia public_token por access_token (servidor), llama a los endpoints de producto.
• Productos clave: Auth, Balance, Transactions, Identity, Investments, Liabilities, Income. Los habilitas por Item.
• Errores comunes: ITEM_LOGIN_REQUIRED e INVALID_CREDENTIALS. Usa webhooks para manejar Items que requieren atención.
• Límites de tasa por Item y cliente. Agrupa lecturas y usa webhooks en vez de sondear constantemente.

¿Qué es Plaid?

Plaid es infraestructura fintech que se interpone entre tu app y el banco del usuario. Cuando el usuario introduce sus credenciales en Plaid Link, Plaid se conecta al banco (API oficial o scraping), extrae y normaliza los datos y te entrega una respuesta JSON uniforme, sin importar el banco.

No almacenas ni accedes a las credenciales bancarias. Plaid mantiene la conexión (Item) y te da un access_token para consultar ese Item. Un Item representa un set de credenciales en una institución financiera y puede contener varias cuentas.

Plaid cubre cuentas corrientes, de ahorro, tarjetas, préstamos, inversiones y datos de nómina. No transfiere dinero: para ACH, combina Plaid Auth con un procesador de pagos. Más detalles en nuestra guía de las mejores APIs de pagos ACH.

Autenticación y configuración

Paso 1: Crea una cuenta de desarrollador de Plaid

Regístrate en plaid.com y verifica tu email. Tendrás acceso a tres entornos:

• Sandbox: bancos y usuarios simulados, sin costo. Usa user_good / pass_good.
• Development: conexiones reales, hasta 100 Items activos, gratis.
• Production: conexiones ilimitadas, pago por uso.

Paso 2: Obtén tus claves

En el Dashboard de Plaid, ve a Team Settings > Keys. Necesitas:

• client_id: igual para todos los entornos.
• secret: diferente por entorno.

Guárdalos en variables de entorno. Nunca subas estos valores a git.

Paso 3: Instala el SDK

Instala el SDK oficial de Node.js:

npm install plaid

Paso 4: Inicializa el cliente

import { Configuration, PlaidApi, PlaidEnvironments } from 'plaid';

const config = new Configuration({
  basePath: PlaidEnvironments.sandbox,
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
    },
  },
});

const client = new PlaidApi(config);

Cambia PlaidEnvironments.sandbox por .development o .production según el entorno.

Endpoints principales

El flujo del token de Link

La integración de Plaid requiere cuatro pasos. Los pasos 1 y 3 ocurren en el backend; Plaid Link se ejecuta en el cliente:

Paso 1: Crea un link_token

const response = await client.linkTokenCreate({
  user: { client_user_id: 'user_123' },
  client_name: 'Your App',
  products: ['auth', 'transactions'],
  country_codes: ['US'],
  language: 'en',
});
const linkToken = response.data.link_token;

Versión curl:

curl -X POST https://sandbox.plaid.com/link/token/create \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "secret": "YOUR_SANDBOX_SECRET",
    "user": { "client_user_id": "user_123" },
    "client_name": "Your App",
    "products": ["auth", "transactions"],
    "country_codes": ["US"],
    "language": "en"
  }'

Paso 2: Abre Plaid Link en el cliente

Envía el link_token al frontend y pásalo al SDK de Plaid Link. El usuario selecciona su banco y Plaid devuelve un public_token al callback onSuccess.

Paso 3: Intercambia el public_token

const exchange = await client.itemPublicTokenExchange({
  public_token: publicToken,
});
const accessToken = exchange.data.access_token;
const itemId = exchange.data.item_id;

Guarda accessToken en el backend asociado a tu usuario. Este token es persistente y se usa para todas las consultas futuras.

Paso 4: Llama a los endpoints del producto

const accounts = await client.accountsGet({ access_token: accessToken });
const balance = await client.accountsBalanceGet({ access_token: accessToken });

Endpoints de producto que debes conocer

• Auth: Números de cuenta y routing para ACH (/auth/get).
• Balance: Saldos en tiempo real (/accounts/balance/get).
• Transactions: Hasta 24 meses de transacciones (/transactions/sync).
• Identity: Nombre, email, teléfono, dirección (/identity/get). Si solo necesitas KYC, compara con otros proveedores en nuestro resumen de las mejores APIs de KYC.
• Investments: Tenencias y transacciones (/investments/holdings/get).
• Liabilities: Préstamos, tarjetas, hipotecas (/liabilities/get).
• Income: Datos de nómina (/credit/payroll_income/get).

Probando la API de Plaid con Apidog

Probar Plaid de punta a punta es complejo porque el paso de Link ocurre en el navegador. Para testear los endpoints de backend, validar cargas útiles y compartir requests con tu equipo, Apidog facilita el proceso.

Importa la especificación OpenAPI de Plaid en Apidog para tener cada endpoint listo con ejemplos, tipos y headers correctos. Usa variables de entorno (client_id, secret, access_token) para alternar entre sandbox y producción fácilmente. Encadena requests (linkTokenCreate → sandboxPublicTokenCreate → itemPublicTokenExchange → accountsGet) para validar el flujo completo sin navegador.

El mock server de Apidog es útil cuando el frontend requiere respuestas de /accounts/get antes de que tu backend esté listo. Si migras desde otra herramienta, revisa nuestra guía sobre pruebas de API sin Postman en 2026. Descarga Apidog y apunta a la spec de Plaid para comenzar.

Errores comunes y límites de tasa

Plaid devuelve errores con error_type, error_code y error_message legible. Maneja estos casos en producción:

• INVALID_CREDENTIALS: Contraseña incorrecta del usuario. Pídele que reintente vía Link en modo actualización.
• ITEM_LOGIN_REQUIRED: El banco invalidó la sesión (cambio de contraseña, MFA). Habilita Link en modo actualización para reautenticar. Lo sabrás por webhook.
• RATE_LIMIT_EXCEEDED: Excediste el límite por Item o endpoint. Espera e intenta de nuevo con backoff aleatorio.
• PRODUCT_NOT_READY: Los datos aún se están extrayendo. Reintenta después del webhook INITIAL_UPDATE.

Webhooks

Pasa una URL de webhook al crear el link_token. Plaid enviará POSTs con actualizaciones. Los más relevantes:

• SYNC_UPDATES_AVAILABLE: nuevas transacciones
• ITEM: LOGIN_REQUIRED: requiere reautenticación
• ITEM: ERROR: fallo permanente

Verifica la firma JWT antes de procesar cualquier webhook.

Límites de tasa

Plaid impone límites por Item y endpoint. Por ejemplo, /accounts/balance/get ~5 llamadas/minuto por Item en producción. Hay límites agregados por cliente en endpoints populares. Recomendación: usa webhooks, cachea saldos y evita llamar a Plaid en rutas de usuario en tiempo real.

Precios de Plaid

Plaid usa precios por llamada en producción. Resumen:

• Sandbox: gratis, ilimitado.
• Development: gratis hasta 100 Items.
• Production:
• Auth: ~$1.50 por cuenta vinculada (único).
• Balance: por llamada.
• Transactions: mensual por Item (~$0.30).
• Identity: por llamada.
• Investments / Liabilities / Income: tarifas por Item.

Pueden negociar precios personalizados según volumen. Consulta la página de productos de Plaid para cifras actuales.

Preguntas frecuentes

¿Cuánto dura un access_token? Indefinidamente, a menos que el usuario revoque acceso o el banco invalide la sesión. Guárdalo cifrado y no lo expires por tu cuenta.

¿Puedo usar Plaid solo para verificación de identidad? Sí, con Plaid Identity. Para solo KYC, evalúa también productos dedicados (ver cómo usar la API de Stripe Identity).

¿Plaid funciona fuera de EE. UU.? Sí. Soporta EE. UU., Canadá, Reino Unido y gran parte de la UE. El soporte depende del producto y país; revisa country_codes en /link/token/create.

¿Qué pasa si el usuario cambia su contraseña bancaria? El Item entra en estado ITEM_LOGIN_REQUIRED y recibes un webhook. Activa Plaid Link en modo actualización para reautenticar sin perder el access_token.

¿Puedo probar el flujo de Link sin navegador? Sí, el endpoint /sandbox/public_token/create omite Link y devuelve un public_token para intercambiar. Útil para tests de integración.

¿Cómo trabajo con Plaid en desarrollo local? Usa un secret de sandbox en .env y conecta a PlaidEnvironments.sandbox. Usa ngrok o Cloudflare Tunnel para recibir webhooks en local.