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

Las aplicaciones fintech rara vez comienzan de cero hoy en día. Cuando un usuario vincula una cuenta corriente a tu aplicación, lo más probable es que Plaid se encuentre en el medio, traduciendo los inicios de sesión bancarios a un JSON limpio que tu backend pueda usar. La API de Plaid impulsa la vinculación de cuentas, comprobaciones de saldo, historial de transacciones y verificación de identidad para miles de aplicaciones, incluyendo Venmo, Robinhood y Chime.

Esta guía te acompaña a través de la API de Plaid desde la perspectiva de un desarrollador: cómo obtener claves, cómo funciona el flujo del token de Link de principio a fin, qué productos debes conocer y qué significan los errores comunes cuando las cosas fallan en producción. También verás cómo probar cada paso con Apidog para que dejes de adivinar las cargas útiles de las solicitudes. Si quieres la fuente original de la verdad, mantén la documentación oficial de Plaid abierta en una segunda pestaña mientras lees.

La banca abierta es un espacio concurrido, y Plaid es una opción entre varias. Si aún estás comparando proveedores, nuestro resumen de las mejores APIs de banca abierta es un compañero útil. Para esta publicación, asume que has elegido Plaid y estás listo para implementar.

button

TL;DR

Plaid es un agregador de datos financieros que conecta tu aplicación con más de 12,000 bancos en EE. UU., Canadá y Europa.
Obtienes tres entornos listos para usar: sandbox (gratis, datos falsos), desarrollo (100 Items reales gratuitos) y producción (pago por llamada).
El flujo de vinculación es un protocolo de cuatro pasos: crea link_token en el lado del servidor, abre Plaid Link en el lado del cliente, intercambia public_token por access_token, luego llama a los endpoints del producto.
Los productos principales son Auth, Balance, Transactions, Identity, Investments, Liabilities e Income. Los habilitas por Item.
Los errores de producción más comunes son ITEM_LOGIN_REQUIRED e INVALID_CREDENTIALS. Los webhooks te informan cuando un Item necesita atención.
Los límites de tasa son por Item y por cliente. Agrupa tus lecturas y escucha los webhooks en lugar de sondear.

¿Qué es Plaid?

Plaid es una empresa de infraestructura fintech con sede en EE. UU. que se sitúa entre tu aplicación y el banco del usuario. Cuando un usuario introduce sus credenciales bancarias en Plaid Link, Plaid se conecta al banco (a través de APIs oficiales de banca abierta donde estén disponibles, o sitios web bancarios de ingeniería inversa donde no), extrae los datos solicitados, los normaliza y te entrega una respuesta JSON consistente, independientemente del banco de origen.

Nunca ves ni almacenas las credenciales bancarias del usuario. Plaid mantiene la conexión, a la que llama Item, y te proporciona un access_token que representa el permiso para consultar ese Item. Un Item equivale a un conjunto de credenciales en una institución financiera, y puede incluir varias cuentas (corriente, de ahorro, tarjeta de crédito).

Plaid cubre cuentas de ahorro y corrientes de consumidores, tarjetas de crédito, préstamos, cuentas de inversión y datos de nóminas. No mueve dinero por sí mismo; para transferencias ACH, normalmente emparejas Plaid Auth con un procesador de pagos separado. Nuestro artículo sobre las mejores APIs de pagos ACH explica cómo suele ser esa combinación.

Autenticación y configuración

Paso 1: Crea una cuenta de desarrollador de Plaid

Regístrate en plaid.com y verifica tu correo electrónico. Aterrizarás en el Panel de Control de Plaid con tres entornos ya provisionados:

Sandbox: instituciones falsas, usuarios falsos, sin costo. Usa user_good / pass_good para iniciar sesión.
Development: conexiones bancarias reales, limitado a 100 Items activos, gratis.
Production: conexiones reales, ilimitadas, facturación por uso.

Paso 2: Obtén tus claves

Desde el Panel de Control, ve a Team Settings > Keys. Necesitas dos valores:

client_id: el mismo en todos los entornos
secret: diferente por entorno (sandbox, desarrollo, producción)

Almacena estos en variables de entorno. Nunca los subas a git.

Paso 3: Instala el SDK

El SDK oficial de Node.js se encuentra en github.com/plaid/plaid-node.

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);

Reemplaza PlaidEnvironments.sandbox por .development o .production cuando promociones.

Endpoints principales

El flujo del token de Link

Cada integración de Plaid sigue el mismo baile de cuatro pasos. Realizas los pasos 1 y 3 en el lado del servidor; Plaid Link maneja el paso 2 en el navegador o la aplicación móvil del usuario.

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;

La 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 a tu frontend y pásalo al SDK de Plaid Link. El usuario elige su banco, inicia sesión, y Plaid devuelve un public_token a tu callback de 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;

Almacena accessToken en el lado del servidor, vinculado a tu usuario. Este token tiene una larga vida útil y es el que usarás para cada llamada futura.

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 devuelve números de cuenta y enrutamiento para ACH (/auth/get).
Balance devuelve saldos en tiempo real, omitiendo la caché (/accounts/balance/get).
Transactions devuelve hasta 24 meses de datos de transacciones limpias (/transactions/sync).
Identity devuelve el nombre del titular de la cuenta, correo electrónico, teléfono, dirección (/identity/get). Si tu caso de uso es puramente KYC, compáralo con proveedores dedicados en nuestro resumen de las mejores APIs de KYC.
Investments devuelve tenencias y transacciones de inversión (/investments/holdings/get).
Liabilities devuelve detalles de préstamos estudiantiles, tarjetas de crédito e hipotecas (/liabilities/get).
Income devuelve datos de nómina a través de Plaid Income (/credit/payroll_income/get).

Probando la API de Plaid con Apidog

Probar Plaid de principio a fin es complicado porque el paso de Link ocurre en un navegador. Aún necesitas una forma confiable de acceder a los endpoints del lado del servidor con cargas útiles válidas, ver cómo se manifiestan los errores y compartir solicitudes de trabajo con tus compañeros de equipo. Apidog lo maneja mejor que la mayoría de las herramientas.

Importa la especificación OpenAPI de Plaid en Apidog y obtendrás cada endpoint preconfigurado con tipos, ejemplos de cuerpos y los encabezados de autenticación correctos. Puedes crear un conjunto de variables de entorno de sandbox (client_id, secret, access_token) y cambiar a producción con un solo clic. Las solicitudes encadenadas te permiten ejecutar linkTokenCreate → sandboxPublicTokenCreate → itemPublicTokenExchange → accountsGet en un solo flujo, para que puedas verificar el protocolo completo sin un navegador.

El servidor simulado de Apidog es útil cuando tu equipo de frontend necesita respuestas de /accounts/get antes de que tu integración de backend esté lista. Si estás migrando de otra herramienta, nuestra guía sobre pruebas de API sin Postman en 2026 cubre la migración en detalle. Descarga Apidog y apúntalo a la especificación de Plaid para empezar.

Errores comunes y límites de tasa

Los errores de Plaid se devuelven con un error_type, error_code y un error_message legible para humanos. Maneja estos cuatro en producción:

INVALID_CREDENTIALS: el usuario escribió la contraseña incorrecta en el banco. Pídele que lo intente de nuevo a través del modo de actualización de Link.
ITEM_LOGIN_REQUIRED: el banco invalidó la sesión (cambio de contraseña, rotación de MFA). Activa Link en modo de actualización para volver a autenticar. Te enteras de esto a través de un webhook, no de una llamada fallida.
RATE_LIMIT_EXCEEDED: has alcanzado un límite por Item o por endpoint. Espera un poco y vuelve a intentarlo con una pequeña demora aleatoria.
PRODUCT_NOT_READY: los datos de transacciones aún se están extrayendo. Vuelve a intentarlo después de que se active el webhook INITIAL_UPDATE.

Webhooks

Pasa una URL de webhook cuando crees el link_token y Plaid enviará POST con las actualizaciones a ella. Los tres que no puedes ignorar son SYNC_UPDATES_AVAILABLE (nuevas transacciones), ITEM: LOGIN_REQUIRED (se necesita volver a autenticar) e ITEM: ERROR (fallo permanente). Verifica la firma JWT en cada webhook antes de actuar sobre él.

Límites de tasa

Plaid aplica límites de tasa por Item por endpoint. Por ejemplo, /accounts/balance/get tiene un límite de alrededor de 5 llamadas por minuto por Item en producción. También se aplican límites agregados a nivel de cliente en endpoints con mucho tráfico. La regla práctica: sondea los webhooks, guarda los saldos en caché durante unos minutos y nunca accedas a Plaid desde una ruta de solicitud de cara al usuario.

Precios de Plaid

Plaid utiliza precios escalonados de pago por llamada a la API en producción. El precio aproximado es:

Sandbox: gratis, ilimitado.
Development: gratis hasta 100 Items.
Production:
Auth: aproximadamente $1.50 por cuenta vinculada, una sola vez.
Balance: precios por llamada.
Transactions: tarifa mensual por Item (alrededor de $0.30).
Identity: por llamada.
Investments / Liabilities / Income: tarifas separadas por Item.

Plaid negocia precios personalizados por encima de ciertos volúmenes, por lo que la lista de precios pública es un punto de partida. Consulta la página de productos de Plaid para conocer las cifras actuales.

Preguntas frecuentes

¿Cuánto tiempo dura un access_token? Indefinidamente, hasta que el usuario revoque el acceso o el banco invalide la sesión. Almacénalo cifrado y no lo expires por tu parte.

¿Puedo usar Plaid solo para verificación de identidad? Puedes usar Plaid Identity, pero si tu necesidad principal es KYC, puede que te convenga más un producto de verificación dedicado. Cubrimos las ventajas y desventajas en nuestra guía sobre cómo usar la API de Stripe Identity.

¿Plaid es compatible con países fuera de EE. UU.? Sí. Plaid cubre EE. UU., Canadá, Reino Unido y la mayor parte de la UE. El soporte por país varía según el producto; consulta el parámetro de códigos de país en la llamada a /link/token/create.

¿Qué sucede si un usuario cambia su contraseña bancaria? El Item pasa al estado ITEM_LOGIN_REQUIRED y recibes un webhook. Activa Plaid Link en modo de actualización y el usuario se autentica de nuevo sin perder su access_token.

¿Puedo probar el flujo de Link sin un navegador real? Sí. El endpoint /sandbox/public_token/create omite Link por completo y devuelve un public_token que puedes intercambiar. Úsalo para pruebas de integración automatizadas.

¿Cómo gestiono Plaid en el desarrollo local? Mantén un secret de sandbox en tu archivo .env y conecta tu entorno de desarrollo a PlaidEnvironments.sandbox. Usa tunelización (ngrok, Cloudflare Tunnel) para recibir webhooks localmente.