決済

Wealth Reader の決済

Wealth Reader では、バックエンドで変更不能な決済指示を作成し、専用の安全なウィジェットで銀行の承認を完了できます（PSD2 / PIS - Payment Initiation Services）。API 認証情報、機密性の高い受取人口座、接続内部の詳細をブラウザーに渡すことはありません。

決定論的なサンドボックスでは実際の資金を動かさずに連携できますが、パラメーターで有効にするものではありません。独自のベース URL と認証情報を持つ別のデプロイ環境を、Wealth Reader が依頼に応じて提供します（セキュリティとテストを参照）。サンドボックスでは profile-institutions はシミュレーション用の金融機関を 1 件返します。expected_mode は環境を切り替えません。想定する環境を呼んでいるかだけを確認し、一致しなければ 409 payment_mode_mismatch を返します。

データ集約に対応する銀行が、決済開始にも同様に対応するとは限りません。本番環境の Wealth Reader 金融機関カタログは、スペインおよび欧州全域を対象としています。

2 段階のアーキテクチャ

決済連携では、2 段階で責任を厳密に分離します。

sequenceDiagram
autonumber
actor Usuario as ユーザー
participant Front as フロントエンド（加盟店）
participant Back as バックエンド（加盟店）
participant API as Wealth Reader API
participant Widget as 決済ウィジェット
participant Banco as 銀行（SCA）
Note over Back,API: 事前手順（管理対象プロファイルのみ）
Back->>API: POST /payments/?action=profile-institutions
API-->>Back: プロファイルのカタログ（institution_code）
Note over Back,API: 手順1：変更不能な決済インテントの作成（Server-to-Server）
Back->>API: POST /payments/?action=create（X-API-KeyとIdempotency-Keyを使用）
API-->>Back: 201とpayment.id + 短寿命のpayment.widget.token
Note over Front,Widget: 手順2：ウィジェットの読み込みと承認（ブラウザー）
Back->>Front: payment.idとpayment.widget.tokenを渡す
Front->>Widget: WealthReaderPayments.mount(...)またはload-payments.js
Widget->>Usuario: 変更不能な金融機関・金額・振込内容を表示
Usuario->>Widget: 決済を承認
Widget->>Banco: リダイレクト / App to App（SCA）
Banco->>API: Wealth ReaderのcallbackへSCAから戻る
API-->>Widget: 承認の技術的確認
Note over Back,API: 照合と資金決済の確認
loop 最終状態になるまで
Back->>API: POST /payments/?action=status
API-->>Back: payment_status: not_initiated | pending | settled | ...
end

手順 1（安全なバックエンド）: サーバーが決済インテントを作成します（POST /payments/?action=create）。X-API-Key、Idempotency-Key、Content-Type: application/json を指定します。この呼び出しで金額（amount_minor、セント単位）、通貨（currency、現在は EUR のみ）、受取人（beneficiary.name と beneficiary.iban）、銀行明細の振込内容（reference）、内部参照（customer_reference）、許可する Web オリジン（allowed_origin）を変更不能な値として固定します。この 6 項目は必須です。本文は厳密な許可リスト方式であり、未知のフィールドは 422 invalid_request になります。
応答: 201 と {"success": true, "payment": {…}} を返します。冪等な再送の場合は 200 です。インテントの識別子は payment.id、ウィジェットの短寿命トークンは payment.widget.token に入ります。
手順 2（加盟店のフロントエンド）: ブラウザーは公式スクリプト load-payments.js または WealthReaderPayments.mount() でウィジェットを読み込み、payment.id と payment.widget.token のみを渡します。ユーザーは銀行を選択し（インテントで事前選択されていない場合）、銀行の画面で強力な顧客認証（SCA）を完了します。
資金決済の確認: バックエンドは POST /payments/?action=status で状態を照会します。本文は厳密に {"payment_intent_id": "<id>"} です。Webhook はありません。最終状態になるまで定期的に照会します。

2 つの入金モデル

Wealth Reader は業務要件に応じて 2 つのモデルを提供します。

加盟店向け標準連携（受取人を自社で指定）:
- 加盟店が受取人の名前と IBAN、金額、通貨（EUR）、振込内容、注文参照を自由に指定します。
- allowed_institution_codes でユーザーが選べる銀行を制限するか、カタログ全体を許可できます。
管理対象プロファイル（cruz_roja_demo など）:
- 寄付や公開デモ向けです。
- サーバーが公式の送金先口座を固定し、資金が慈善団体にのみ送られるようにします（例: スペイン赤十字、金額は 0,01 EUR から 1,00 EUR に制限）。

統合銀行ディレクトリ

Wealth Reader は、PSD2 による決済開始に対応する欧州金融機関の統合カタログを次のエンドポイントで提供します。

GET https://api.wealthreader.com/payments/entities/?country=ES

銀行の標準化された名称、ロゴ、対応する送金方法、技術的要件（支払人から引落口座の IBAN を取得する必要性など）を取得できます。country、search（別名 q）、code、payment_method、limit、offset で絞り込めます。

このエンドポイントは公開されており、X-API-Key は不要です。送信しても利点はなく、認証情報の呼び出し枠を 1 回消費します。

コードは必ず code に返されたとおりに使用してください。インテント作成時に検証されるのは allowed_institution_codes の形式だけで、カタログ内の存在は確認されません。コードを誤記しても作成時にはエラーにならず、後で銀行選択画面が空になります。

interaction_status: completed は画面上の技術的な操作の完了のみを意味します。決済が確定したとみなせるのは payment_status が settled の場合だけです。payment_status の値は not_initiated、pending、settled、rejected、cancelled、expired、failed、unknown です。詳細は状態、ポーリング、照合を参照してください。

責任の分離

決済用認証情報（X-API-Key）はサーバー間通信のみで使用します。フロントエンドや公開リポジトリに含めてはいけません。
ブラウザーが受け取るのはインテント識別子と、HTTPS オリジンに紐付いた短寿命トークンのみです。
ウィジェットは金額、通貨、受取人、振込内容、許可済み金融機関を変更できません。
モーダルやウィジェットを閉じても、バックエンドでの資金決済状態の照会を省略できません。
決済機能は、Wealth Reader の銀行データ集約製品と認証情報、トークン、callback を共有しません。

認証情報と呼び出し枠

決済用認証情報では PAYMENTS 製品が有効である必要があります。無効なら API は 403 payments_not_allowed を返します。認証情報がない、または形式が誤っている場合は 401 invalid_api_key です。

認証付き呼び出しは、毎回 API キーの累積カウンターを 1 消費します。 これは利用期間全体のカウンターで、時間枠や自動補充はありません。使い切ると、上限が引き上げられるまで、すべての決済呼び出しが継続的に 429 api_limit_reached を返します。待機や再試行では解決しません。大量の呼び出しや公開デモ（ページ読み込みごとに 1 回消費）を予定する場合は、公開前に Wealth Reader と上限を合意してください。

次の手順

連携とウィジェットに進んでください。

最終更新 2026-09-10