DEV Community

Cover image for Hướng Dẫn Sử Dụng Plaid API (Phiên Bản 2026 Dành Cho Nhà Phát Triển)
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

Hướng Dẫn Sử Dụng Plaid API (Phiên Bản 2026 Dành Cho Nhà Phát Triển)

Các ứng dụng Fintech hiện đại thường tích hợp với tài khoản ngân hàng của người dùng ngay từ đầu. Plaid đóng vai trò trung gian, chuyển đổi thông tin đăng nhập ngân hàng thành dữ liệu JSON sạch mà backend của bạn có thể thao tác. API Plaid hỗ trợ liên kết tài khoản, kiểm tra số dư, truy xuất lịch sử giao dịch và xác minh danh tính cho hàng nghìn ứng dụng như Venmo, Robinhood, Chime.

Dùng thử Apidog ngay hôm nay

Bài viết này hướng dẫn bạn sử dụng API Plaid dưới góc độ kỹ thuật: lấy khóa, thực hiện quy trình Link token từ đầu đến cuối, các sản phẩm cốt lõi, ý nghĩa các lỗi thường gặp, và cách kiểm thử từng bước với Apidog. Để tra cứu chi tiết, hãy mở tài liệu chính thức của Plaid song song khi đọc.

Nếu bạn còn phân vân giữa các nền tảng ngân hàng mở, hãy tham khảo bài tổng hợp các API ngân hàng mở tốt nhất. Ở đây, ta giả định bạn đã chọn Plaid và bắt đầu triển khai.

Tóm tắt

  • Plaid kết nối ứng dụng với hơn 12.000 ngân hàng tại Mỹ, Canada, Châu Âu.
  • Ba môi trường: sandbox (miễn phí, dữ liệu giả), development (100 Item thực miễn phí), production (tính phí).
  • Quy trình liên kết: tạo link_token (server) → mở Plaid Link (client) → đổi public_token lấy access_token (server) → gọi các endpoint sản phẩm.
  • Các sản phẩm chính: Auth, Balance, Transactions, Identity, Investments, Liabilities, Income. Kích hoạt từng Item.
  • Lỗi phổ biến: ITEM_LOGIN_REQUIRED, INVALID_CREDENTIALS. Webhook cảnh báo khi Item gặp vấn đề.
  • Giới hạn tần suất theo Item và client. Ưu tiên đọc hàng loạt và lắng nghe webhook thay vì polling.

Plaid là gì?

Plaid là nền tảng hạ tầng fintech đặt giữa app của bạn và ngân hàng của người dùng. Người dùng nhập thông tin vào Plaid Link; Plaid sẽ kết nối với ngân hàng (qua API chính thức hoặc reverse engineering web), chuẩn hóa dữ liệu và trả về phản hồi JSON đồng nhất — bạn không cần xử lý sự khác biệt từng ngân hàng.

Bạn không lưu trữ thông tin đăng nhập ngân hàng. Plaid giữ kết nối (gọi là Item), cung cấp access_token để truy vấn. Một Item là một thông tin đăng nhập tại một tổ chức tài chính, có thể chứa nhiều loại tài khoản.

Plaid hỗ trợ tài khoản tiền gửi, tiết kiệm, thẻ tín dụng, khoản vay, đầu tư và bảng lương. Plaid không xử lý chuyển tiền trực tiếp; muốn chuyển khoản ACH, hãy kết hợp Plaid Auth với một payment processor. Tham khảo thêm ở danh sách API thanh toán ACH tốt nhất.

Xác thực và thiết lập

Bước 1: Đăng ký tài khoản Plaid Developer

Truy cập plaid.com, đăng ký, xác minh email. Dashboard cấp sẵn 3 môi trường:

  • Sandbox: tổ chức/người dùng giả, miễn phí. Đăng nhập dùng user_good / pass_good.
  • Development: kết nối ngân hàng thực, tối đa 100 Item thực, miễn phí.
  • Production: không giới hạn, tính phí theo usage.

Bước 2: Lấy khóa API

Vào Team Settings > Keys trên Dashboard.

  • client_id: dùng cho mọi môi trường
  • secret: riêng mỗi môi trường (sandbox, development, production)

Lưu vào biến môi trường, không commit lên git.

Bước 3: Cài đặt SDK

SDK Node.js: github.com/plaid/plaid-node

npm install plaid

Bước 4: Khởi tạo client Plaid

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

Chuyển PlaidEnvironments.sandbox thành .development hoặc .production khi deploy lên môi trường tương ứng.

Các endpoint cốt lõi

Tích hợp Plaid luôn tuân theo 4 bước:

  1. Tạo link_token (server-side)
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;

Hoặc bằng 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"
  }'
  1. Mở Plaid Link (client-side)

Gửi link_token lên frontend và truyền vào Plaid Link SDK. Người dùng chọn ngân hàng, đăng nhập, SDK trả về public_token trong callback onSuccess.

  1. Đổi public_token sang access_token (server-side)
const exchange = await client.itemPublicTokenExchange({
  public_token: publicToken,
});
const accessToken = exchange.data.access_token;
const itemId = exchange.data.item_id;

Lưu accessToken (gắn với user), sử dụng cho các request sau này.

  1. Gọi endpoint sản phẩm (server-side)
const accounts = await client.accountsGet({ access_token: accessToken });
const balance = await client.accountsBalanceGet({ access_token: accessToken });

Các endpoint sản phẩm cần biết

  • Auth: Lấy số tài khoản, số routing cho ACH (/auth/get).
  • Balance: Lấy số dư thời gian thực (/accounts/balance/get).
  • Transactions: Lấy lịch sử giao dịch tối đa 24 tháng (/transactions/sync).
  • Identity: Lấy tên, email, SĐT, địa chỉ (/identity/get). Nếu chỉ cần KYC, tham khảo danh sách API KYC tốt nhất.
  • Investments: Lấy danh mục tài sản, giao dịch đầu tư (/investments/holdings/get).
  • Liabilities: Chi tiết khoản vay, thẻ tín dụng, thế chấp (/liabilities/get).
  • Income: Dữ liệu bảng lương qua Plaid Income (/credit/payroll_income/get).

Kiểm thử API Plaid với Apidog

Kiểm thử tích hợp Plaid khó vì bước Link diễn ra trên trình duyệt. Để test endpoint server-side với payload hợp lệ, xem lỗi, chia sẻ request với team – Apidog là lựa chọn tối ưu.

Nhập OpenAPI spec của Plaid vào Apidog, bạn sẽ có sẵn mọi endpoint, mẫu dữ liệu, header xác thực. Tạo biến môi trường sandbox (client_id, secret, access_token), chuyển sang production chỉ bằng 1 click. Có thể tạo chuỗi request: linkTokenCreate → sandboxPublicTokenCreate → itemPublicTokenExchange → accountsGet để kiểm thử cả flow không cần browser.

Server mock của Apidog giúp frontend lấy phản hồi /accounts/get trước khi backend hoàn thiện. Nếu chuyển từ công cụ khác, xem hướng dẫn kiểm thử API không cần Postman. Tải về Apidog, trỏ vào spec Plaid và bắt đầu.

Các lỗi thường gặp & giới hạn tần suất

Plaid trả về lỗi với error_type, error_code, error_message rõ ràng. 4 lỗi production cần xử lý:

  • INVALID_CREDENTIALS: Người dùng nhập sai mật khẩu. Yêu cầu đăng nhập lại qua Link update mode.
  • ITEM_LOGIN_REQUIRED: Phiên bị ngân hàng hủy (đổi mật khẩu, MFA). Nhận biết qua webhook, kích hoạt Link update để xác thực lại.
  • RATE_LIMIT_EXCEEDED: Vượt quá giới hạn trên Item hoặc endpoint. Giảm tần suất, retry với backoff ngẫu nhiên.
  • PRODUCT_NOT_READY: Dữ liệu đang sync. Đợi webhook INITIAL_UPDATE rồi thử lại.

Webhooks

Truyền webhook URL khi tạo link_token, Plaid sẽ POST update vào đó. 3 loại quan trọng:

  • SYNC_UPDATES_AVAILABLE: Có giao dịch mới
  • ITEM: LOGIN_REQUIRED: Yêu cầu xác thực lại
  • ITEM: ERROR: Lỗi không phục hồi

Luôn xác minh chữ ký JWT trên webhook trước khi xử lý.

Giới hạn tần suất

Plaid áp dụng limit theo Item và endpoint. Ví dụ /accounts/balance/get: ~5 lần/phút/Item ở production. Một số endpoint còn giới hạn tổng theo client. Thực tế: poll webhook, cache balance vài phút, không gọi Plaid từ endpoint user-facing.

Giá của Plaid

  • Sandbox: miễn phí, không giới hạn.
  • Development: miễn phí đến 100 Items thực.
  • Production:
    • Auth: ~$1.50/tài khoản liên kết (một lần)
    • Balance: tính phí theo call
    • Transactions: phí hàng tháng/Item (~$0.30)
    • Identity: tính phí theo call
    • Investments / Liabilities / Income: giá riêng/Item

Giá có thể thương lượng. Tham khảo trang sản phẩm Plaid để cập nhật mới nhất.

FAQ

access_token tồn tại bao lâu? Không hết hạn trừ khi user thu hồi hoặc ngân hàng hủy phiên. Lưu trữ mã hóa phía server.

Dùng Plaid chỉ để xác minh danh tính được không? Được, qua Plaid Identity. Nhưng nếu chỉ cần KYC, nên cân nhắc sản phẩm chuyên biệt (hướng dẫn Stripe Identity API).

Plaid hỗ trợ quốc gia nào? Mỹ, Canada, Anh, phần lớn EU. Kiểm tra country_codes khi gọi /link/token/create.

User đổi mật khẩu ngân hàng thì sao? Item chuyển sang ITEM_LOGIN_REQUIRED, nhận webhook, kích hoạt Link update để xác thực lại (không mất access_token).

Có test quy trình Link không cần browser không? Được, dùng endpoint /sandbox/public_token/create để lấy public_token test tự động.

Phát triển local thì dùng Plaid thế nào? Lưu secret sandbox vào .env, kết nối với PlaidEnvironments.sandbox. Để nhận webhook local, dùng tunneling (ngrok, Cloudflare Tunnel,...).

Top comments (0)