Blog

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

Ashley Innocent

Ashley Innocent

23 tháng 4 2026

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

Apidog cho doanh nghiệp

Triển khai tại chỗ

SSO & RBAC

Tuân thủ SOC 2

Khám phá Apidog Enterprise

Các ứng dụng Fintech ngày nay hiếm khi bắt đầu từ con số không. Khi người dùng liên kết tài khoản ngân hàng vãng lai với ứng dụng của bạn, Plaid có thể sẽ nằm ở giữa, dịch 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ể sử dụng. API của Plaid hỗ trợ việc liên kết tài khoản, kiểm tra số dư, lịch sử giao dịch và xác minh danh tính cho hàng nghìn ứng dụng bao gồm Venmo, Robinhood và Chime.

Hướng dẫn này sẽ đưa bạn qua API của Plaid từ góc độ nhà phát triển: cách lấy khóa, cách hoạt động của quy trình Link token từ đầu đến cuối, những sản phẩm bạn nên biết và ý nghĩa của các lỗi thường gặp khi có sự cố trong môi trường production. Bạn cũng sẽ thấy cách kiểm tra mọi bước với Apidog để bạn không còn phải đoán mò về payload yêu cầu. Nếu bạn muốn nguồn thông tin chính xác, hãy mở tài liệu chính thức của Plaid trong một tab thứ hai khi đọc.

Ngân hàng mở là một lĩnh vực đông đúc, và Plaid là một trong số nhiều lựa chọn. Nếu bạn vẫn đang so sánh các nhà cung cấp, bài tổng hợp của chúng tôi về các API ngân hàng mở tốt nhất là một tài liệu hữu ích. Đối với bài viết này, giả sử bạn đã chọn Plaid và sẵn sàng triển khai.

button

Tóm tắt

Plaid là gì?

Plaid là một công ty hạ tầng fintech có trụ sở tại Hoa Kỳ, nằm giữa ứng dụng của bạn và ngân hàng của người dùng. Khi người dùng nhập thông tin đăng nhập ngân hàng của họ vào Plaid Link, Plaid kết nối với ngân hàng (thông qua các API ngân hàng mở chính thức nếu có, hoặc các trang web ngân hàng được kỹ thuật đảo ngược nếu không có), kéo dữ liệu được yêu cầu, chuẩn hóa nó và đưa cho bạn một phản hồi JSON nhất quán bất kể nó đến từ ngân hàng nào.

Bạn không bao giờ thấy hoặc lưu trữ thông tin đăng nhập ngân hàng của người dùng. Plaid giữ kết nối, mà họ gọi là một Item, và cung cấp cho bạn một access_token đại diện cho quyền truy vấn Item đó. Một Item tương đương với một bộ thông tin đăng nhập tại một tổ chức tài chính, và có thể bao gồm nhiều tài khoản (tiền gửi, tiết kiệm, thẻ tín dụng).

Plaid bao gồm các tài khoản tiền gửi và tiết kiệm của người tiêu dùng, thẻ tín dụng, khoản vay, tài khoản đầu tư và dữ liệu bảng lương. Nó không tự mình chuyển tiền; đối với các khoản chuyển khoản ACH, bạn thường ghép nối Plaid Auth với một bộ xử lý thanh toán riêng biệt. Bài viết của chúng tôi về các API thanh toán ACH tốt nhất giải thích cách ghép nối đó thường trông như thế nào.

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

Bước 1: Tạo tài khoản nhà phát triển Plaid

Đăng ký tại plaid.com và xác minh email của bạn. Bạn sẽ vào Plaid Dashboard với ba môi trường đã được cấp phép:

Bước 2: Lấy khóa của bạn

Từ Dashboard, đi tới Team Settings > Keys. Bạn cần hai giá trị:

Lưu trữ chúng trong các biến môi trường. Không bao giờ commit chúng vào git.

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

SDK Node.js chính thức có tại github.com/plaid/plaid-node.

npm install plaid

Bước 4: Khởi tạo máy khách

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

Thay thế PlaidEnvironments.sandbox bằng .development hoặc .production khi bạn chuyển sang môi trường cao hơn.

Các endpoint cốt lõi

Mọi tích hợp Plaid đều tuân theo cùng một quy trình bốn bước. Bạn thực hiện bước 1 và 3 phía máy chủ; Plaid Link xử lý bước 2 trong trình duyệt hoặc ứng dụng di động của người dùng.

Bước 1: Tạo 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;

Phiên bả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"
  }'

Bước 2: Mở Plaid Link trên máy khách

Gửi link_token đến frontend của bạn và truyền nó vào Plaid Link SDK. Người dùng chọn ngân hàng của họ, đăng nhập, và Plaid trả về một public_token cho callback onSuccess của bạn.

Bước 3: Đổi public_token

const exchange = await client.itemPublicTokenExchange({
  public_token: publicToken,
});

const accessToken = exchange.data.access_token;
const itemId = exchange.data.item_id;

Lưu trữ accessToken phía máy chủ, gắn với người dùng của bạn. Token này có tuổi thọ dài và là thứ bạn sử dụng cho mọi cuộc gọi trong tương lai.

Bước 4: Gọi các endpoint sản phẩm

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

Các endpoint sản phẩm bạn nên biết

Kiểm thử API Plaid với Apidog

Kiểm thử Plaid từ đầu đến cuối rất khó khăn vì bước Link xảy ra trong trình duyệt. Bạn vẫn cần một cách đáng tin cậy để truy cập các endpoint phía máy chủ với các payload hợp lệ, xem cách lỗi xuất hiện và chia sẻ các yêu cầu đang hoạt động với đồng đội. Apidog xử lý điều đó tốt hơn hầu hết các công cụ.

Nhập đặc tả OpenAPI của Plaid vào Apidog và bạn sẽ nhận được mọi endpoint được cấu hình sẵn với các kiểu dữ liệu, các body ví dụ và các tiêu đề xác thực phù hợp. Bạn có thể tạo một bộ biến môi trường sandbox (client_id, secret, access_token) và chuyển sang production chỉ với một cú nhấp chuột. Các yêu cầu theo chuỗi cho phép bạn chạy linkTokenCreate → sandboxPublicTokenCreate → itemPublicTokenExchange → accountsGet trong một luồng duy nhất, để bạn có thể xác minh toàn bộ quá trình bắt tay mà không cần trình duyệt.

Máy chủ mock của Apidog hữu ích khi đội ngũ frontend của bạn cần phản hồi /accounts/get trước khi tích hợp backend của bạn hoàn tất. Nếu bạn đang chuyển từ một công cụ khác, hướng dẫn của chúng tôi về kiểm thử API mà không cần Postman vào năm 2026 bao gồm chi tiết quá trình di chuyển. Tải xuống Apidog và trỏ nó vào đặc tả của Plaid để bắt đầu.

Các lỗi thường gặp và giới hạn tỷ lệ

Các lỗi của Plaid trả về với error_type, error_code và error_message dễ đọc. Xử lý bốn lỗi này trong môi trường production:

Webhooks

Truyền một URL webhook khi bạn tạo link_token và Plaid sẽ POST các bản cập nhật đến đó. Ba loại bạn không thể bỏ qua là SYNC_UPDATES_AVAILABLE (giao dịch mới), ITEM: LOGIN_REQUIRED (cần xác thực lại) và ITEM: ERROR (lỗi vĩnh viễn). Xác minh chữ ký JWT trên mọi webhook trước khi thực hiện hành động.

Giới hạn tỷ lệ

Plaid thực thi giới hạn tỷ lệ trên mỗi Item và mỗi endpoint. Ví dụ, /accounts/balance/get được giới hạn khoảng 5 cuộc gọi mỗi phút cho mỗi Item trong môi trường production. Các giới hạn tổng hợp cấp độ máy khách cũng áp dụng cho các endpoint có tải cao. Quy tắc thực tế: thăm dò webhook, lưu trữ số dư trong vài phút và không bao giờ gọi Plaid từ một đường dẫn yêu cầu hướng người dùng.

Giá của Plaid

Plaid sử dụng mô hình giá bậc thang trả tiền theo mỗi cuộc gọi API trong môi trường production. Khoảng giá:

Plaid đàm phán giá tùy chỉnh trên một số lượng nhất định, vì vậy bảng giá công khai chỉ là điểm khởi đầu. Kiểm tra trang sản phẩm của Plaid để biết các con số hiện tại.

Câu hỏi thường gặp

access_token tồn tại trong bao lâu?Vô thời hạn, cho đến khi người dùng thu hồi quyền truy cập hoặc ngân hàng hủy phiên. Lưu trữ nó được mã hóa và không hết hạn ở phía bạn.

Tôi có thể sử dụng Plaid chỉ để xác minh danh tính không?Bạn có thể sử dụng Plaid Identity, nhưng nếu nhu cầu chính của bạn là KYC, bạn có thể được phục vụ tốt hơn bởi một sản phẩm xác minh chuyên dụng. Chúng tôi đề cập đến các đánh đổi trong hướng dẫn của chúng tôi về cách sử dụng Stripe Identity API.

Plaid có hỗ trợ các quốc gia ngoài Hoa Kỳ không?Có. Plaid bao gồm Hoa Kỳ, Canada, Vương quốc Anh và hầu hết EU. Hỗ trợ quốc gia khác nhau tùy theo sản phẩm; kiểm tra tham số mã quốc gia trong cuộc gọi /link/token/create.

Điều gì xảy ra nếu người dùng thay đổi mật khẩu ngân hàng của họ?Item chuyển sang trạng thái ITEM_LOGIN_REQUIRED và bạn nhận được một webhook. Kích hoạt Plaid Link ở chế độ cập nhật và người dùng xác thực lại mà không làm mất access_token của họ.

Tôi có thể kiểm thử quy trình Link mà không cần trình duyệt thực không?Có. Endpoint /sandbox/public_token/create bỏ qua hoàn toàn Link và trả về một public_token mà bạn có thể đổi. Sử dụng nó cho các bài kiểm thử tích hợp tự động.

Làm cách nào để xử lý Plaid trong quá trình phát triển cục bộ?Giữ một secret của sandbox trong tệp .env của bạn và kết nối môi trường dev của bạn với PlaidEnvironments.sandbox. Sử dụng tunneling (ngrok, Cloudflare Tunnel) để nhận webhook cục bộ.

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API

Đăng ký miễn phíTải xuống