Blog

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

Ashley Innocent

Ashley Innocent

23 April 2026

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

Apidog 엔터프라이즈

온프레미스 배포

SSO & RBAC

SOC 2 준수

Apidog Enterprise 살펴보기

핀테크 앱은 이제 거의 처음부터 시작하지 않습니다. 사용자가 앱에 당좌 계좌를 연결할 때, Plaid가 중간에서 은행 로그인 정보를 백엔드에서 사용할 수 있는 깔끔한 JSON으로 번역해 줄 것입니다. Plaid API는 Venmo, Robinhood, Chime을 포함한 수천 개의 앱에서 계좌 연결, 잔액 확인, 거래 내역 및 신원 확인 기능을 제공합니다.

이 가이드는 개발자 관점에서 Plaid API를 안내합니다: 키를 얻는 방법, Link 토큰 흐름이 처음부터 끝까지 어떻게 작동하는지, 알아야 할 제품, 그리고 프로덕션에서 문제가 발생했을 때 일반적인 오류가 무엇을 의미하는지. 또한 Apidog를 사용하여 모든 단계를 테스트하는 방법을 배우고, 요청 페이로드를 추측하는 일을 멈출 수 있습니다. 원본의 정확한 정보를 원한다면, 이 글을 읽는 동안 두 번째 탭에 공식 Plaid 문서를 열어두세요.

오픈 뱅킹은 경쟁이 치열한 분야이며, Plaid는 여러 옵션 중 하나입니다. 여전히 공급업체를 비교 중이라면, 최고의 오픈 뱅킹 API에 대한 저희의 요약 정보가 유용한 자료가 될 것입니다. 이 글에서는 Plaid를 선택했으며 출시할 준비가 되었다고 가정합니다.

버튼

요약 (TL;DR)

Plaid란 무엇인가요?

Plaid는 앱과 사용자 은행 사이에 위치하는 미국 기반의 핀테크 인프라 회사입니다. 사용자가 Plaid Link에 은행 인증 정보를 입력하면, Plaid는 은행에 연결하여 (가능한 경우 공식 오픈 뱅킹 API를 통해, 불가능한 경우 역설계된 은행 웹사이트를 통해) 요청된 데이터를 가져와 정규화하고, 어떤 은행에서 왔는지에 관계없이 일관된 JSON 응답을 제공합니다.

사용자의 은행 인증 정보는 절대 보거나 저장하지 않습니다. Plaid는 Item이라고 부르는 연결을 유지하고, 해당 Item을 쿼리할 권한을 나타내는 access_token을 제공합니다. 하나의 Item은 하나의 금융 기관에서 하나의 인증 정보 세트와 같으며, 여러 계좌(당좌 예금, 저축 예금, 신용 카드)를 포함할 수 있습니다.

Plaid는 소비자 당좌 예금 및 저축 계좌, 신용 카드, 대출, 투자 계좌 및 급여 데이터를 다룹니다. 자체적으로 돈을 이동시키지는 않습니다. ACH 이체를 위해서는 일반적으로 Plaid Auth를 별도의 결제 처리기와 연결합니다. 최고의 ACH 결제 API에 대한 저희 글은 해당 연결이 일반적으로 어떻게 이루어지는지 설명합니다.

인증 및 설정

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

plaid.com에서 가입하고 이메일을 인증하세요. Plaid 대시보드에 세 가지 환경이 이미 프로비저닝되어 있습니다:

2단계: 키 가져오기

대시보드에서 팀 설정(Team Settings) > 키(Keys)로 이동합니다. 다음 두 가지 값이 필요합니다:

이 값들을 환경 변수에 저장하세요. 절대로 git에 커밋하지 마세요.

3단계: SDK 설치

공식 Node.js SDK는 github.com/plaid/plaid-node에 있습니다.

npm install plaid

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

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으로 바꾸세요.

핵심 엔드포인트

모든 Plaid 통합은 동일한 4단계 프로세스를 따릅니다. 1단계와 3단계는 서버 측에서 수행하고, Plaid Link는 사용자 브라우저 또는 모바일 앱에서 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에 전달하세요. 사용자가 은행을 선택하고 로그인하면, Plaid는 public_token을 onSuccess 콜백으로 반환합니다.

3단계: public_token 교환

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

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

accessToken을 사용자에게 연결하여 서버 측에 저장하세요. 이 토큰은 장기적으로 유효하며, 향후 모든 호출에 사용됩니다.

4단계: 제품 엔드포인트 호출

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

알아두어야 할 제품 엔드포인트

Apidog로 Plaid API 테스트하기

Plaid의 엔드투엔드 테스트는 Link 단계가 브라우저에서 발생하기 때문에 까다롭습니다. 유효한 페이로드로 서버 측 엔드포인트를 호출하고, 오류가 어떻게 발생하는지 확인하며, 작동하는 요청을 팀원들과 공유하는 신뢰할 수 있는 방법이 여전히 필요합니다. Apidog는 대부분의 도구보다 이를 잘 처리합니다.

Plaid의 OpenAPI 사양을 Apidog로 가져오면 유형, 예시 본문, 올바른 인증 헤더로 미리 구성된 모든 엔드포인트를 얻을 수 있습니다. 샌드박스 환경 변수 세트(client_id, secret, access_token)를 생성하고 클릭 한 번으로 프로덕션으로 전환할 수 있습니다. 체인 요청을 통해 linkTokenCreate → sandboxPublicTokenCreate → itemPublicTokenExchange → accountsGet을 단일 흐름으로 실행할 수 있으므로 브라우저 없이 전체 핸드셰이크를 확인할 수 있습니다.

백엔드 통합이 완료되기 전에 프런트엔드 팀이 /accounts/get 응답을 필요로 할 때 Apidog의 모의 서버가 유용합니다. 다른 도구에서 전환 중이라면, 2026년 Postman 없이 API 테스트하기에 대한 저희 가이드가 마이그레이션에 대해 자세히 설명합니다. Apidog를 다운로드하고 Plaid 사양으로 시작하세요.

일반적인 오류 및 속도 제한

Plaid 오류는 error_type, error_code, 그리고 사람이 읽을 수 있는 error_message와 함께 반환됩니다. 프로덕션에서는 다음 네 가지를 처리하세요:

웹훅

link_token을 생성할 때 webhook URL을 전달하면 Plaid가 해당 URL로 업데이트를 POST합니다. 무시할 수 없는 세 가지는 SYNC_UPDATES_AVAILABLE (새 거래), ITEM: LOGIN_REQUIRED (재인증 필요), ITEM: ERROR (영구적인 실패)입니다. 모든 웹훅에 대해 조치하기 전에 JWT 서명을 확인하세요.

속도 제한

Plaid는 Item당 엔드포인트별로 속도 제한을 적용합니다. 예를 들어, /accounts/balance/get은 프로덕션에서 Item당 분당 약 5회 호출로 제한됩니다. 트래픽이 많은 엔드포인트에는 집계된 클라이언트 수준 제한도 적용됩니다. 실용적인 규칙: 웹훅을 폴링하고, 잔액을 몇 분 동안 캐시하며, 사용자 대면 요청 경로에서 Plaid를 호출하지 마세요.

Plaid 가격

Plaid는 프로덕션에서 API 호출당 계층형 가격을 사용합니다. 대략적인 내용은 다음과 같습니다:

Plaid는 특정 볼륨 이상에서 맞춤 가격을 협상하므로, 공개 요금표는 시작점입니다. 현재 수치는 Plaid 제품 페이지에서 확인하세요.

자주 묻는 질문 (FAQ)

access_token은 얼마나 오래 지속되나요?사용자가 접근을 철회하거나 은행이 세션을 무효화할 때까지 무기한입니다. 암호화하여 저장하고 사용자 측에서 만료시키지 마세요.

Plaid를 신원 확인에만 사용할 수 있나요?Plaid Identity를 사용할 수 있지만, 주된 요구사항이 KYC라면 전용 확인 제품이 더 적합할 수 있습니다. Stripe Identity API 사용 방법 가이드에서 장단점을 다룹니다.

Plaid는 미국 이외의 국가를 지원하나요?네. Plaid는 미국, 캐나다, 영국, 그리고 대부분의 EU 국가를 지원합니다. 국가 지원은 제품별로 다르므로, /link/token/create 호출의 국가 코드 매개변수를 확인하세요.

사용자가 은행 비밀번호를 변경하면 어떻게 되나요?Item이 ITEM_LOGIN_REQUIRED 상태로 전환되고 웹훅을 받게 됩니다. 업데이트 모드에서 Plaid Link를 트리거하면 사용자는 access_token을 잃지 않고 다시 인증합니다.

실제 브라우저 없이 Link 흐름을 테스트할 수 있나요?네. /sandbox/public_token/create 엔드포인트는 Link를 완전히 건너뛰고 교환할 수 있는 public_token을 반환합니다. 자동화된 통합 테스트에 사용하세요.

로컬 개발 환경에서 Plaid를 어떻게 처리하나요?샌드박스 secret을 .env 파일에 보관하고 개발 환경을 PlaidEnvironments.sandbox에 연결하세요. 터널링(ngrok, Cloudflare Tunnel)을 사용하여 로컬에서 웹훅을 수신하세요.

Apidog에서 API 설계-첫 번째 연습

API를 더 쉽게 구축하고 사용하는 방법을 발견하세요

무료 회원가입다운로드