Rihpig

Posted on Apr 23 • Originally published at apidog.com

플래드 API 사용법 (2026 개발자 가이드)

핀테크 앱 개발은 이제 직접 은행 연동을 구현하는 대신, Plaid 같은 중간 API를 활용해 더 빠르고 안전하게 시작할 수 있습니다. 사용자는 Plaid를 통해 본인의 은행 계좌를 앱에 연결하고, Plaid는 인증 정보와 데이터를 표준화된 JSON으로 제공합니다. 이 글에서는 개발자가 Plaid API를 실제로 적용하는 데 필요한 모든 과정을 다룹니다: 키 발급, Link 토큰 플로우, 주요 엔드포인트, 오류 처리, 그리고 Apidog를 활용한 테스트 자동화까지 실무 중심으로 설명합니다. 공식 문서와 병행해 읽을 것을 추천합니다. 공급업체 비교가 필요하다면 오픈 뱅킹 API 비교 도 참고하세요. 이 글은 Plaid 사용과 배포 준비가 된 개발자를 대상으로 합니다. 지금 Apidog 체험하기

요약 (TL;DR)

Plaid는 12,000개 이상의 미국/캐나다/유럽 은행에 앱을 연결하는 금융 데이터 애그리게이터입니다.
세 가지 환경: 샌드박스(무료·가짜 데이터), 개발(100개 무료 라이브 Item), 프로덕션(호출당 과금).
핵심 연결 과정: ① link_token 생성(서버), ② Plaid Link 오픈(클라이언트), ③ public_token→access_token 교환(서버), ④ 제품 엔드포인트 호출.
주요 제품: Auth, Balance, Transactions, Identity, Investments, Liabilities, Income. Item 단위로 활성화.
대표적인 오류: ITEM_LOGIN_REQUIRED, INVALID_CREDENTIALS. 웹훅으로 Item 상태 확인.
속도 제한은 Item별/클라이언트별로 적용. 폴링 대신 웹훅 활용, 읽기는 일괄 처리 권장.

Plaid란?

Plaid는 앱과 은행 사이에서 인증·데이터 표준화·보안을 담당하는 핀테크 인프라입니다. 사용자가 Plaid Link에서 은행 정보를 입력하면, Plaid가 해당 은행(공식 오픈 뱅킹 API 또는 역설계 방식)과 통신해 표준화된 JSON 데이터를 제공합니다. 인증정보는 저장·노출되지 않으며, 연결은 Item(은행+인증정보+계좌묶음) 단위로 관리되고, 서버는 access_token을 통해 접근합니다.

Plaid는 예금·저축·신용카드·대출·투자·급여 데이터 등을 지원하지만, 직접 결제 기능은 없습니다. ACH 이체 등 결제에는 Plaid Auth와 별도의 결제 API를 연동해야 하며, ACH 결제 API 비교 글도 참고하세요.

인증 및 설정

1단계: Plaid 개발자 계정 생성

plaid.com에서 계정을 만들고, 이메일 인증을 완료합니다. 대시보드에는 세 가지 환경이 자동 제공됩니다:

샌드박스: 테스트용 가짜 은행, 무제한 무료, user_good/pass_good 계정 사용.
개발: 실제 은행과 연결, 100개 라이브 Item에 무료 제공.
프로덕션: 실제 연결 및 무제한 사용, 호출당 과금.

2단계: API 키 발급

대시보드 → Team Settings > Keys 메뉴에서 아래 두 값을 확인:

client_id: 모든 환경 공통 사용
secret: 환경별로 다름(샌드박스/개발/프로덕션 별도)

이 값은 반드시 환경 변수로 보관하고, 절대 코드 저장소에 커밋하지 마세요.

3단계: Node.js SDK 설치

npm install plaid

4단계: SDK 클라이언트 초기화

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

운영 환경 전환 시 PlaidEnvironments.sandbox를 .development 또는 .production으로 변경하세요.

핵심 엔드포인트 및 플로우

Link 토큰 핸드셰이크

Plaid 연동은 아래 4단계로 구성됩니다. 1, 3, 4단계는 서버에서, 2단계는 프런트(모바일/웹)에서 실행합니다.

1단계: 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;

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"
  }'

2단계: 클라이언트에서 Plaid Link 실행

위에서 받은 link_token을 프런트엔드로 전달, Plaid Link SDK에 연결하세요. 사용자가 은행 로그인 후 public_token을 onSuccess 콜백으로 반환받습니다.

3단계: public_token → access_token 교환 (서버)

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

accessToken은 서버에 안전하게 저장, 이후 모든 Plaid 호출에서 사용합니다.

4단계: 엔드포인트 호출

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

주요 제품 엔드포인트 요약

Auth: 계좌/라우팅 번호 반환 (/auth/get)
Balance: 실시간 잔액 조회 (/accounts/balance/get)
Transactions: 24개월 거래 내역 (/transactions/sync)
Identity: 소유자 정보 (이름/이메일/전화/주소) (/identity/get) KYC 전용 비교는 KYC API 요약 참고
Investments: 투자 내역 및 보유 자산 (/investments/holdings/get)
Liabilities: 학자금, 카드, 모기지 정보 (/liabilities/get)
Income: 급여 데이터 (/credit/payroll_income/get)

Apidog로 Plaid API 테스트하기

Plaid 연동을 개발/테스트할 때 Link 단계가 브라우저에서 처리되기 때문에, 백엔드 엔드포인트를 시뮬레이션하거나 오류 케이스를 반복적으로 확인하기 어렵습니다. Apidog는 OpenAPI 스펙 불러오기로 모든 엔드포인트/파라미터/인증헤더를 자동 세팅하고, 환경변수(client_id, secret, access_token)로 샌드박스/운영 전환이 쉽습니다.

체인 요청 기능을 활용하면 linkTokenCreate → sandboxPublicTokenCreate → itemPublicTokenExchange → accountsGet 순서로 전체 핸드셰이크를 브라우저 없이 테스트할 수 있습니다. 프런트엔드 개발자는 /accounts/get 응답 모킹으로 UI 개발을 병렬로 진행할 수 있습니다. Postman 등에서 Apidog로 전환하려면 Postman 없이 API 테스트하기에서 마이그레이션 방법을 참고하세요. Apidog 다운로드 후 Plaid 스펙을 불러와 바로 시작할 수 있습니다.

실무 오류 처리 및 속도 제한

Plaid는 모든 오류에 error_type, error_code, error_message를 반환합니다. 프로덕션에서는 아래 4가지 케이스를 반드시 처리하세요:

INVALID_CREDENTIALS: 은행 비밀번호 오류. Link 업데이트 모드로 재인증 유도.
ITEM_LOGIN_REQUIRED: 세션 만료(비밀번호 변경/MFA 등), 웹훅 수신 후 Link 업데이트 필요.
RATE_LIMIT_EXCEEDED: 쿼터 초과, 지터(jitter) 적용 후 재시도.
PRODUCT_NOT_READY: 데이터 수집 중, INITIAL_UPDATE 웹훅 도착 후 재시도.

웹훅 활용

link_token 생성시 webhook URL을 지정하면, Plaid가 업데이트 이벤트를 POST로 전달합니다. 반드시 실시간 대응해야 하는 3가지: SYNC_UPDATES_AVAILABLE(새 트랜잭션), ITEM: LOGIN_REQUIRED(재인증 필요), ITEM: ERROR(영구 실패)입니다. 모든 웹훅은 JWT 서명 검증 후 처리하세요.

속도 제한

Plaid는 엔드포인트별·Item별 속도 제한이 있습니다. 예시: /accounts/balance/get은 프로덕션에서 Item당 분당 약 5회. 트래픽이 많은 경우 클라이언트 수준 제한도 존재합니다. 실전 규칙: 폴링은 자제, 웹훅으로 데이터 동기화, 잔액 등은 캐싱하고, 사용자 대면 경로에서 직접 Plaid 호출하지 마세요.

Plaid 가격 정책

Plaid는 프로덕션 단계에서 호출당 과금이 적용됩니다. 주요 기준은 다음과 같습니다:

샌드박스: 무제한 무료
개발: 100개 라이브 Item까지 무료
프로덕션:
- Auth: 계좌당 약 $1.50 (1회성)
- Balance: 호출당
- Transactions: Item별 월 $0.30 내외
- Identity: 호출당
- Investments/Liabilities/Income: 별도 요금

대량 이용 시 맞춤 가격 협상 가능. 최신 가격은 Plaid 제품 페이지에서 확인하세요.

자주 묻는 질문 (FAQ)

Q. access_token은 얼마나 유효한가요?
A. 사용자가 접근 권한 회수 또는 은행 세션 만료까지 무기한. 암호화 저장, 사용자 측 만료 금지.

Q. 신원 확인 목적으로만 Plaid를 사용할 수 있나요?
A. Plaid Identity로 가능하나, KYC가 주목적이면 Stripe Identity 등 전문 API와 비교 권장.

Q. 미국 이외 국가도 지원하나요?
A. 미국, 캐나다, 영국, EU 대부분 지원. 단, 제품별로 국가 지원 범위 다르므로 /link/token/create의 국가 코드 확인 필수.

Q. 사용자가 은행 비밀번호를 변경하면?
A. Item이 ITEM_LOGIN_REQUIRED 상태로 전환, 웹훅 수신. Link 업데이트 모드로 재인증 유도, access_token 유지.

Q. 실제 브라우저 없이 Link 플로우 테스트 가능?
A. 가능. /sandbox/public_token/create 엔드포인트로 public_token을 받아 자동화된 통합 테스트에 활용.

Q. 로컬 개발 환경에서 Plaid 연동은?
A. 샌드박스 secret을 .env에 저장하고, PlaidEnvironments.sandbox 사용. 웹훅은 ngrok/Cloudflare Tunnel 등으로 로컬 수신.

DEV Community