Fintechアプリがゼロから開発されることは、今やほとんどありません。ユーザーが当社のアプリに当座預金口座をリンクする際、Plaidがその間に介在し、銀行のログイン情報をバックエンドで使用できるクリーンなJSONに変換する可能性が高いです。Plaid APIは、Venmo、Robinhood、Chimeを含む何千ものアプリで、口座連携、残高確認、取引履歴、本人確認を可能にしています。
このガイドでは、開発者の視点からPlaid APIを詳しく説明します。具体的には、APIキーの取得方法、Linkトークンフローの全体的な仕組み、知っておくべきプロダクト、そして本番環境で問題が発生した場合の一般的なエラーの意味について解説します。Apidogを使って各ステップをテストする方法も紹介するため、リクエストペイロードについて推測する必要がなくなります。信頼できる最新情報が必要な場合は、読み進めながらPlaid公式ドキュメントを別のタブで開いておくと良いでしょう。
オープンバンキングは競争の激しい分野であり、Plaidはその選択肢の一つに過ぎません。ベンダーを比較検討中であれば、最適なオープンバンキングAPIに関する当社の概要が役立つでしょう。この記事では、Plaidを選び、すぐに導入する準備ができていると仮定します。
要約
- Plaidは、米国、カナダ、ヨーロッパの12,000以上の銀行とアプリを接続する金融データアグリゲーターです。
- サンドボックス（無料、ダミーデータ）、開発（100個の無料ライブアイテム）、本番（APIコールごとに課金）の3つの環境がすぐに利用できます。
- 連携フローは4段階のハンドシェイクです。サーバー側で
link_tokenを作成し、クライアント側でPlaid Linkを開き、public_tokenをaccess_tokenと交換し、その後プロダクトエンドポイントを呼び出します。 - コアプロダクトは、Auth、Balance、Transactions、Identity、Investments、Liabilities、Incomeです。これらはアイテムごとに有効にします。
- 最も一般的な本番環境エラーは
ITEM_LOGIN_REQUIREDとINVALID_CREDENTIALSです。ウェブフックは、アイテムに注意が必要な場合に通知します。 - レート制限はアイテムごと、クライアントごとに設定されています。ポーリングの代わりにバッチで読み込み、ウェブフックを利用してください。
Plaidとは？
Plaidは、米国を拠点とするフィンテックインフラ企業で、アプリとユーザーの銀行の間に位置します。ユーザーが銀行の認証情報をPlaid Linkに入力すると、Plaidは銀行に接続し（利用可能な場合は公式のオープンバンキングAPIを介して、利用できない場合はリバースエンジニアリングされた銀行のウェブサイトを介して）、要求されたデータを取得し、正規化して、どの銀行から来たかにかかわらず一貫したJSONレスポンスを返します。
ユーザーの銀行認証情報を見ることも保存することもありません。Plaidがその接続（これを「アイテム」と呼びます）を保持し、そのアイテムを照会する許可を表すaccess_tokenをあなたに付与します。1つのアイテムは1つの金融機関での1組の認証情報に相当し、複数の口座（当座預金、普通預金、クレジットカード）を含むことができます。
Plaidは、個人の当座預金口座と普通預金口座、クレジットカード、ローン、投資口座、給与データに対応しています。それ自体でお金を移動させることはありません。ACH送金の場合、通常はPlaid Authと別の支払い処理業者を組み合わせて使用します。最適なACH決済APIに関する当社の記事では、この組み合わせがどのように機能するかを説明しています。
認証とセットアップ
ステップ1：Plaid開発者アカウントの作成
plaid.comでサインアップし、メールアドレスを確認してください。Plaidダッシュボードにアクセスすると、すでに3つの環境がプロビジョニングされています。
-
サンドボックス: 架空の金融機関、架空のユーザー、無料。
user_good/pass_goodでログインできます。 - 開発: 実際の銀行接続、最大100個のライブアイテムに制限、無料。
- 本番: 実際の接続、無制限、従量課金制。
ステップ2：キーの取得
ダッシュボードから、チーム設定 > キーに移動します。次の2つの値を取得してください。
-
client_id: 全環境で同じです。 -
secret: 環境（サンドボックス、開発、本番）ごとに異なります。
これらは必ず環境変数として保存し、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に切り替えてください。
コアエンドポイント
Linkトークンのフロー
すべてのPlaid統合は、同じ4段階のプロセスに従います。サーバー側でステップ1と3、クライアント側でステップ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の交換
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 });
知っておくべきプロダクトエンドポイント
-
Auth: ACHの口座番号とルーティング番号を返します（
/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ステップがブラウザで行われるため難しいですが、APIリクエストのペイロードやレスポンスを正確にテストし、エラーや成功例を再現したい場合は、Apidogの活用が最適です。
PlaidのOpenAPI仕様をApidogにインポートすることで、型や例のボディ、認証ヘッダーがセットされた全エンドポイントが手に入ります。サンドボックス用の環境変数セット（client_id、secret、access_token）を用意し、ワンクリックで本番環境へ切り替え可能です。チェーンドリクエスト機能を使えば、linkTokenCreate→sandboxPublicTokenCreate→itemPublicTokenExchange→accountsGetの一連のフローをブラウザなしで検証できます。
モックサーバー機能により、バックエンド未完成でもフロントエンドが/accounts/getのレスポンスを受け取って開発できます。他ツールからの移行を検討中の方は、Postman不要のAPIテストも参考にしてください。Apidogをダウンロードし、PlaidのOpenAPI仕様をインポートしてすぐに始められます。
一般的なエラーとレート制限
Plaidのエラーはerror_type、error_code、error_messageとして返されます。本番環境で頻出するエラーは以下の4つです。
-
INVALID_CREDENTIALS: ユーザーが銀行でパスワードを間違えた場合。Linkの更新モードで再認証を促してください。 -
ITEM_LOGIN_REQUIRED: 銀行側でセッションが無効化された場合（パスワード変更、MFA更新など）。Linkの更新モードで再認証を行わせます。このエラーは失敗したAPI呼び出しだけでなく、ウェブフックでも通知されます。 -
RATE_LIMIT_EXCEEDED: アイテムやエンドポイントごとに設定されたレート制限を超過した場合。一時的にリトライを停止し、ジッターを加えて再試行してください。 -
PRODUCT_NOT_READY: 取引データがまだ取得中。INITIAL_UPDATEウェブフックが発火した後に再度取得してください。
ウェブフック
link_token作成時にwebhook URLを指定すると、Plaidは更新情報をPOSTします。特に無視できないウェブフックは次の3つです。
-
SYNC_UPDATES_AVAILABLE: 新しい取引データが利用可能 -
ITEM: LOGIN_REQUIRED: 再認証が必要 -
ITEM: ERROR: 永続的な失敗
各ウェブフックの処理前に、JWT署名を必ず検証してください。
レート制限
Plaidは、アイテム単位・エンドポイント単位でレート制限をかけています。例：/accounts/balance/getは本番環境でアイテムあたり毎分5回程度。クライアント単位の集計制限もあります。実装時は「ウェブフックでの更新検知」「数分間のキャッシュ」「ユーザーリクエスト毎に直接Plaidを呼ばない」などを徹底しましょう。
Plaidの料金
Plaidは本番環境で階層型従量課金制です。大まかな料金例：
- サンドボックス: 無料・無制限
- 開発: アイテム100個まで無料
-
本番:
- Auth: 口座1つあたり約$1.50（一回限り）
- Balance: 呼び出しごとに課金
- Transactions: アイテムごと月額約$0.30
- Identity: 呼び出しごと課金
- Investments / Liabilities / Income: アイテムごと個別料金
一定量を超えるとカスタムプライシングもあるため、最新の料金はPlaidの製品ページを参照してください。
よくある質問
access_tokenはどのくらい有効ですか？
ユーザーがアクセスを取り消すか銀行がセッションを無効にするまで無期限です。暗号化して保存し、意図的に期限切れにしないでください。
Plaidを本人確認のみに使用できますか？
Plaid Identityで本人確認は可能ですが、KYCが主目的の場合は専用サービスの検討も推奨します。Stripe Identity APIの利用方法ガイドもご覧ください。
Plaidは米国以外の国に対応していますか？
はい。米国、カナダ、英国、EUほとんどの国に対応。国ごとのサポート範囲はプロダクトによって異なります。/link/token/createで国コードパラメータを設定しましょう。
ユーザーが銀行のパスワードを変更した場合どうなりますか？
アイテムはITEM_LOGIN_REQUIREDとなり、ウェブフックで通知されます。Plaid Linkを更新モードで起動し、ユーザーはaccess_tokenを失わずに再認証できます。
実際のブラウザなしでLinkフローをテストできますか？
はい。/sandbox/public_token/createエンドポイントで、Linkをスキップして交換可能なpublic_tokenを取得でき、自動統合テストに活用できます。
ローカル開発でPlaidをどのように処理しますか？
.envにサンドボックスsecretを格納し、PlaidEnvironments.sandboxで開発します。ngrokやCloudflare Tunnel等を使えばウェブフックもローカルで受信可能です。
Top comments (0)