必要なもの
- サンドボックス用アプリケーションの、銀行データ権限を持つAPIキー。クイックスタートを参照してください。
bank.*イベントを受信するWebhookの送信先。銀行データのWebhookを参照してください。- 顧客ごとの接続ID、変更フィードのカーソル、同意の終了日を保存するデータベースのテーブル。
ステップ1: 継続的アクセス付きのリンクを作成する
access: ongoingは、同意が終了するまでアクセスを維持します。consent_daysはリクエストです。実際の日付は銀行が決め、接続情報に表示されます。history_fromは、指定した日付以降の履歴を要求します。たとえば年初からの履歴です。代わりにhistory_days(1〜365)を使うこともできますが、両方を同時に指定することはできません。銀行はこれより少ない履歴しか提供しない場合があります。各口座はhistory_coverageで提供範囲を報告します。ownership.compare: noneは口座名義人の照合をスキップするため、参照用の本人情報は不要です。Diditで確認済みの企業と名義人を照合するにはbusinessを使用します。end_user.referenceは、貴社がクライアントに付与するIDです。検索可能で、同じクライアントが同じ口座を再度接続した場合に、Diditがそれを認識できます。- クライアントをホスト型検証ページに案内し、リダイレクトURLで貴社のプロダクトに戻します。
idをクライアントとともに保存してください。
ステップ2: 接続の完了を待つ
クライアント側の手続きが完了すると、connection_id を含む bank.link.completed が届きます。
ブラウザーの結果は決して信頼しないため、次の方法でこれを確認してください:
connection_id を保存し、bank.connection.created を待ちます。これが届くと、口座、残高、直近の取引を読み取れます(sync.initial_status が succeeded または partial になります)。
過去分の取得が終わると、bank.connection.history_complete が届きます。
口座ごとに、history_coverage.oldest_booking_date で、銀行が実際に提供した履歴の最も古い計上日がわかります。
ステップ3: 最初のコピーを読み込む
空のカーソルを指定すると、現在のすべての取引がreset: true 付きの added として返されます。
ページを順に読み取り、カーソルは最後にのみ保存してください:
- 最初の読み取りは真のスナップショットです。読み取りの開始時点で接続が持っていたすべての取引を、現在の状態のまま、
addedとして1回ずつ返します。ページを読み取っている間に同期が実行されても、この点は変わりません。 - ページを読み取っている間に行われた変更は、
next_cursorからの次の読み取りで返されます。受け取り済みの取引はmodifiedとして再度返され、新しい取引はaddedとして返されます。 has_more: falseを含むレスポンスを受け取った後にのみ、next_cursorを保存してください。- ページの読み取りが途中で失敗した場合は、保存しておいたカーソルから読み取りをやり直してください。
- 残高は
GET /v3/bank/accounts/{account_id}/balances/で読み取ります。
ステップ4: すべてのWebhookで最新状態を維持する
Didit は、有効な継続中の接続をすべて、銀行によって異なりますが1日に1〜4回、自動で同期します(sync.frequency_per_day)。
同期で変更が保存されると、bank.data.updated がconnection_id、account_ids、件数とともに届きます。
保存済みのカーソルを使って変更フィードを呼び出します:
addedは新しい取引です。保留中の取引も含まれます。modifiedは変更された取引で、現在の状態で届きます。それぞれidを基準にアップサートしてください。既に保持している取引は更新し、まだ保持していない取引は追加します。removedにはreasonが付いています。手元にないidは無視してください。保留中の取引が計上されると、その取引はpending_bookedの理由付きでremovedに入り、計上された取引はaddedで届きます。
idをキーとして使用してください。読み取り、同期、更新をまたいでも変わりません。
identity_qualityを確認してください。値がderivedの場合、銀行による訂正がremoved1件とadded1件として表示されることがあります。
読み取りは課金されませんが、データが変わるのは同期が実行されたときだけです。そのため、Webhookごとに1回の読み取りで十分です。
より早く取得するには、Sync Nowを使用してください: オンデマンドで銀行データを更新
Step 5: リセットを処理する
再生可能期間より古いカーソルを使用すると、bootstrap: trueを含む 410 cursor_expired が返されます。
変更ログは90日間再生できるため、日次ジョブでこの状況が発生することは稀です。
空のカーソルから読み直し、既存のコピーは取得結果で置き換えてください。追加はしないでください。
空のカーソルからのすべての読み取りにはreset: trueが含まれます。そのため、新規接続と期限切れのカーソルを同じコードパスで処理できます。
ステップ6: 同意の終了を監視する
同意には有効期限があります:consent.expires_at。
Didit は、有効期限の14日前、7日前、1日前に bank.connection.consent_expiring を送信します。
更新したい場合は、renew_connectionを呼び出してください。残りが30日になるまでは、409 renewal_not_needed で応答します。
エンドユーザーが同意の更新を完了するページは、まだ提供されていません。
エンドユーザーが同意を失効させたままにした場合、接続は renewal_required になります。同期済みのデータは引き続き読み取れます。
詳細は銀行同意の更新をご覧ください。
ステップ7: アクセスを停止して削除する
- 顧客が貴社の製品の利用をやめた場合は、
revoke_connectionを呼び出して直ちにデータの読み取りを停止するか、delete_connectionを呼び出して読み取りを停止し、保存済みのデータを削除してください。 - 顧客が銀行側での共有を停止すると、
bank.connection.revokedイベントがended_by付きで届きます。その連携のフィードを停止してください。
料金
継続的アクセスは、有効な接続1件あたり月額で課金されます。 この料金には、接続内のすべての口座、残高、取引、銀行が提供する場合は最大365日分の履歴、自動同期、銀行の上限内でのライブ同期、更新、Webhook、およびすべての読み取りが含まれます。 誰も完了しなかったリンクは無料です。renewal_required、paused、revokedの接続も無料です。
詳しくは料金をご覧ください。
チェックリスト
- 顧客と銀行ごとに1つの連携を、そのカーソルと同意の終了日とともに保存する。
- Webhookハンドラーを冪等にし、イベントIDをキーにする。
-
reset: trueでは、お使いのコピーを置き換え、追記はしない。 -
removedを、その理由とともに処理する。 - 同意のリマインダーを、御社から顧客へ送る通知と連携させる。
-
bank.connection.revokedを受け取ったら、フィードを停止する。 - サンドボックスのプランのテストに合格する。