API docs by Redocly

Wealth Reader (8.1.12)

Download OpenAPI specification:

E-mail: info@wealthreader.com

PSD2に基づく規制APIは、銀行口座残高や取引などの特定の金融情報へのアクセスを提供します。ただし、これらのAPIではアクセスできない他の富情報源が存在します。Wealth Reader APIは、規制APIが提供する情報を拡張し、世界中のあらゆるエンティティにおける追加の富源へのリアルタイムアクセスを提供します。Wealth Reader APIの統合に役立つ他の2つの関連ドキュメントがあります。1つはJavascriptウィジェット統合ガイド：https://docs-en.wealthreader.com/ で、もう1つはこのドキュメントに基づくPostmanコレクションです。 非常に重要：このAPI定義は、Widget経由で統合するクライアント向けに適応されているため、このタイプの統合に必要のない一部のパラメータ（銀行認証パラメータなど）が省略されており、トークンが使用されます。

Core

標準統合に必要なコアAPI

金融資産とその構成詳細を取得します

株式またはファンドで構成された投資ポートフォリオ、クレジットカード、保険、融資を含む金融資産とその構成詳細を取得します。各資産の所有権情報とデータ処理を容易にする一意の識別子が含まれます。Mockデータを取得することが可能です。技術チームに方法を確認してください。

Request Body schema: application/x-www-form-urlencoded
api_key
string

サービス内のクライアントを識別します

code
string

エンティティの名前。完全なリストはGETで取得できます

例: caixabank

token
string

保管された資格情報を識別します。トークンが取得されたフローは「ウィジェット統合ガイド」文書に記載されています。次のMockユーザーが利用可能です：MOCKDATA、OK応答；MOCKOTP、OTPチャレンジ付き応答；MOCKLOGINKO、ログインエラー応答

例: MOCKDATA

product_types
string
Enum: "accounts" "portfolios" "cards" "receipts" "loans" "factoring" "confirming" "properties" "invoices" "files" "deposits" "leases" "insurances"

情報を取得する製品タイプのリスト。カンマで区切られた複数の値を受け入れます。

例: accounts,portfolios

only_balances
boolean
Default: false

利用可能なすべての情報ではなく、製品の残高のみを取得するかどうかを示します。デフォルト値：false。

例: false

fetch_transaction_details
boolean
Default: false

エンティティのコネクタが対応している場合に、取引の拡張詳細を取得するかどうかを示します。重要：有効にすると、返される情報を充実させるために取引ごとに1回以上の追加ナビゲーションを実行します。これにより実行時間が必然的かつ大幅に増加します。追加ナビゲーションの数は取引量に応じて増加します。デフォルトで返される詳細レベルを超える詳細が必要であると確信できる場合にのみ有効にすることをお勧めします。取得した詳細は各取引レベルの additional_info キーに挿入されます。このパラメータの使用には専用環境が必要です。

例: false

date_from
string <date>

トランザクションが要求される日付、YYYY-MM-DD形式。今日より前の日付である必要があります。

例: 2024-01-01

date_to
string <date>

これはローンおよびコンファーミング製品の将来の日付による制限にのみ適用されます。YYYY-MM-DD形式。日付は今日より後でなければなりません

例: 2025-12-31

required_products_schema
string

必要な製品スキーマ。データが必要なアカウントまたはカードを、追加の設定とともに示します。

例: 

{
  "ACCOUNTS": {
    "0ae4d722b1c82feeafb4b36b2893230444071335": {
      "only_balances": false,
      "add_pdf_from_uuids": [
        "90763109952d4f2ebece8dceca8254078c5384a0"
      ],
      "date_from": "2024-04-03"
    }
  },
  "CARDS": {
    "957e6f63546f3fecacce80192b6f7436496dc057": {}
  }
}
add_pdf_from_uuids
string

カンマで区切られたトランザクションuuidを受け入れます。product_typesがALLまたはaccountsを含む場合にのみ考慮されるパラメータ。要求された各銀行取引に関連付けられたPDFドキュメントを追加します。

例: 

20966426721d0885ef9d4b95535e1d3198936f16,8772d6c978d37d7af83094abf380b8b703e94105,e59296b79e7f80cec26679d2c65883025fd59295
otp_method
string

APIがエラーコード2017または20171（複数のOTP方式）を返したときに、どの第二要素配信チャネルを使うかを指定します。その応答と同じセッション識別子で再呼び出しし、statistics.otpMethods内のいずれかのオブジェクトのotp_methodフィールドの文字列を完全一致で設定します（配列インデックス不可）。初回のクレデンシャル要求では省略可能。ユーザー選択後に送信。下の例は参考用です。常にstatistics.otpMethodsで返された文字列をそのまま使用してください。

例: OTP_SMS ****1234

Responses

Request samples

Content type
application/x-www-form-urlencoded
api_key=a1b2c3d4e5f6g7h8i9j0&code=caixabank&token=1234Asdf&product_types=accounts%2Cportfolios&only_balances=false&date_from=2024-01-01&date_to=2025-12-31&required_products_schema=%7B%22ACCOUNTS%22%3A%7B%220ae4d722b1c82feeafb4b36b2893230444071335%22%3A%7B%22only_balances%22%3Afalse%2C%22add_pdf_from_uuids%22%3A%5B%2290763109952d4f2ebece8dceca8254078c5384a0%22%5D%2C%22date_from%22%3A%222024-04-03%22%7D%7D%2C%22CARDS%22%3A%7B%22957e6f63546f3fecacce80192b6f7436496dc057%22%3A%7B%7D%7D%7D&add_pdf_from_uuids=20966426721d0885ef9d4b95535e1d3198936f16%2C8772d6c978d37d7af83094abf380b8b703e94105

Response samples

Content type
application/json
[
  • {
    }
]

取引タイプのリスト

query Parameters
lang
string
Default: "es"
Enum: "es" "en"

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

api_keyに関連付けられたトークンを照会する

この方法を使用して、特定の api_key にリンクされたトークンを照会します。結果はページ単位で返されます。limit で1ページあたりのトークン数（最大500）を指定し、page で返すページを選択します。api_key、method、limit は必須です。いずれかが欠けているか無効な場合、APIは HTTP 400 とエラーコード 2 を返します。

Request Body schema: application/x-www-form-urlencoded
required
api_key
required
string^[a-z0-9]{8}$

サービス内のクライアントを識別するためのapi_key

method
required
string
Value: "get"

実行する操作。サポートされている値は get のみです。

例: get

limit
required
integer [ 1 .. 500 ]

1ページあたりのトークン数。最小 1、最大 500。

例: 100

page
integer >= 1
Default: 1

取得したいページ番号を指定します。各ページには最大 limit 個のトークンが含まれます。指定しない場合、デフォルト値は1です。

例: 1

code
string

トークンを絞り込むためのエンティティコード。省略した場合、すべてのエンティティのトークンが返されます。

例: bbva

sort_by
string
Default: "created_at"
Enum: "created_at" "accesed_at"

結果の並べ替えに使用するフィールド：created_at（作成日）または accesed_at（最終アクセス日）。デフォルトは created_at。

例: created_at

sort_order
string
Default: "DESC"
Enum: "ASC" "DESC"

並べ替えの方向：ASC（昇順）または DESC（降順）。デフォルトは DESC。

例: DESC

Responses

Request samples

Content type
application/x-www-form-urlencoded
api_key=a1b2c3d4&method=get&limit=100&page=1

Response samples

Content type
application/json
{
  • "success": true,
  • "payload": {
    },
  • "pagination": {
    },
  • "statistics": {
    }
}

トークンを取り消す

この方法により、既存のトークンを取り消して、将来のAPIアクセスリクエストの承認を解除できます。

Request Body schema: application/x-www-form-urlencoded
required
api_key
string

サービス内のクライアントを識別します

token
string

取り消すトークン。

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Token successfully revoked."
}

トークンを別のapi_keyに再割り当てする

このメソッドにより、トークンをあるapi_keyから別のapi_keyに再割り当てできます。両方のapi_keyが有効で同じ会社に属している必要があり、トークンはapi_key_sourceに属している必要があります。

Request Body schema: application/x-www-form-urlencoded
required
api_key_source
string

トークンを再割り当てする元のapi_key。

api_key_target
string

トークンを再割り当てする先のapi_key。

token
string

再割り当てするトークン。

例: FRJ0mHlaqZwLzu

Responses

Request samples

Content type
application/x-www-form-urlencoded
api_key_source=a1b2c3d4e5f6g7h8i9j0&api_key_target=b2c3d4e5f6g7h8i9j0k1&token=FRJ0mHlaqZwLzu

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Token successfully reassigned."
}

新しいドメインを追加する

ウィジェットをホストするドメインと宛先Webhookの関連付けを追加します。ドメインの編集やテストには https://www.wealthreader.com/clients/ をご利用ください

Request Body schema: application/x-www-form-urlencoded
required
method
required
string

Method to execute.

例: add

api_key
required
string

User's API key.

domain
required
string

Domain to add.

例: http://desarrollo.cliente.es

url_callback
required
string

URL for callback.

例: https://desarrollo.cliente.es/hooks/wealthreader

tokenize
required
string
Enum: "1" "0"

ウィジェットがトークン化フローを開始するかを制御します：

  • 1 - ユーザーは金融機関で認証（ログイン、同意、必要に応じて2FA）を行い、再利用可能なトークンが返されます
  • 0 - トークン化は実行されません。以前取得したトークンの値をリクエストに含める必要があります

例: 1

Responses

Request samples

Content type
application/x-www-form-urlencoded
method=add&api_key=a1b2c3d4e5f6g7h8i9j0&domain=https%3A%2F%2Fwww.cliente.com&url_callback=https%3A%2F%2Fwww.cliente.com%2Fwebhooks%2Fwealthreader&tokenize=1

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

エラーコードのリスト

エラーコードのリスト。すべてのエラーコードがアプリケーションで同じ扱いを受けるべきではないことに特に注意してください。パスワードが間違っているエラーの場合、同じパラメータで呼び出しを再試行すべきではありませんが、エンティティがメンテナンス中であることを示すエラーの場合は、再試行できます。エラー管理に関するご質問は、当社チームとの技術セッションをリクエストしてください。

query Parameters
lang
string
Default: "es"
Enum: "es" "en"

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

警告コードのリスト

警告コードのリスト。

query Parameters
lang
string
Default: "es"
Enum: "es" "en"

Response language

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Advanced

標準統合に必要のないオプションのエンドポイント。Wealth Reader が明示的に指示する場合にのみ使用してください。

サポートされているエンティティのリストを取得します

サポートされているエンティティのリストと、エンティティのログインフォームを描画するために必要な情報を取得します。

query Parameters
show_only_tested
integer
Default: 0
Enum: 0 1

Indicates whether to show only tested entities. Default value is 0. In production environments, always use 1.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

新規ユーザーを登録する

このエンドポイントはオプションであり、標準統合には必要ありません。Wealth Readerが明示的に指示した場合にのみ使用してください。 このエンドポイントにより、一意の識別子に基づいて、ポートフォリオ転送プラットフォームEasytransferまたはレポートツールAcumulasにユーザーを登録できます。

Request Body schema: application/x-www-form-urlencoded
required
api_key
required
string

Authentication key (8 alphanumeric characters)

user_id
required
string

User identification document.

例: 12345678A

service
required
string
Enum: "integra" "easy-transfer"

Service associated with the user. Determines the data flow.

例: easy-transfer

email
required
string <email>

User email, used according to service type.

例: sai_banker@singularbank.com

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "User registered successfully"
}

ユーザー登録状態を確認する

このエンドポイントはオプションであり、標準統合には必要ありません。Wealth Readerが明示的に指示した場合にのみ使用してください。 ユーザーがEasytransferまたはAcumulasシステムに登録されているかどうかを確認し、ユーザーの一意のアクセスリンクを返します。

Request Body schema: application/x-www-form-urlencoded
required
api_key
required
string

Authentication key

user_id
required
string

User identification document.

例: 12345678A

Responses

Response samples

Content type
application/json
{}

以前に登録したユーザーを取り消す

このエンドポイントはオプションであり、標準統合には必要ありません。Wealth Readerが明示的に指示した場合にのみ使用してください。 このエンドポイントにより、EasytransferまたはAcumulasプラットフォームサービスからユーザーの登録を解除できます。

Request Body schema: application/x-www-form-urlencoded
required
api_key
required
string

Authentication key (8 alphanumeric characters)

user_id
required
string

User identification document.

例: 12345678A

service
required
string
Enum: "integra" "easy-transfer" "all"

Service from which to unregister the user. 'all' for all services.

例: easy-transfer

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "User unregistered successfully"
}

バッチ接続読み込み

このエンドポイントはオプションであり、標準統合には必要ありません。Wealth Readerが明示的に指示した場合にのみ使用してください。 重要：Wealthreader側でバッチプロセス管理を使用するには、専用環境が必要です。このエンドポイントはapi.wealthreader.comでは利用できません。 "batch"タグの下にグループ化されたエンドポイントは、同期的な/entities/メソッドとは異なり、複数の銀行接続を非同期で処理できます。大量の接続を処理し、タイムアウトを回避するのに最適です。

Request Body schema: application/json
required
api_key
required
string

Identifies the client in the service

notification_url
required
string <uri>

Webhook URL. A notification is sent to this URL for each individual credential as soon as it completes processing, not only once all connections in the batch are done.

例: https://example.com/webhook/batch-complete

required
Array of objects (batch-connection) non-empty

List of connections to process

Responses

Callbacks

Request samples

Content type
application/json
{
  • "api_key": "a1b2c3d4e5f6g7h8i9j0",
  • "notification_url": "https://example.com/webhook/batch-complete",
  • "connections": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "batch_id": "batch_20250120_a1b2c3d4",
  • "total_connections": 5,
  • "estimated_completion_time": "2025-01-20T10:45:00Z"
}

Callback payload samples

Callback
POST: Webhook fired when a credential finishes processing
Content type
application/json
{
  • "batch_id": 10863151,
  • "credential_id": "cred_demo_002",
  • "status": "completed",
  • "timestamp": "2026-05-13T08:02:47+00:00"
}

バッチ接続の一般統計を取得する

このエンドポイントはオプションです。バッチ内のすべての接続の処理結果に関する一般的な統計を取得します。

Request Body schema: application/json
required
api_key
required
string

Identifies the client in the service

batch_id
required
string

Batch ID

Responses

Request samples

Content type
application/json
{
  • "api_key": "string",
  • "batch_id": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "batch_id": "batch_20250120_a1b2c3d4",
  • "status": "completed",
  • "statistics": {
    }
}

バッチ内の特定の接続の個別結果を取得する

このエンドポイントはオプションです。バッチから特定の接続の結果を取得します。

Request Body schema: application/json
required
api_key
required
string

Identifies the client in the service

batch_id
required
string

Batch ID

credential_id
required
string

Filter by specific credential_id

Responses

Request samples

Content type
application/json
{
  • "api_key": "string",
  • "batch_id": "string",
  • "credential_id": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "payload": {
    },
  • "statistics": {
    }
}

MyBankMatch

口座名義の確認：お客様のライセンスに紐付けられた銀行の SEPA 受取人確認（VoP）を利用して、IBAN が特定の名義人に属しているかどうかを確認します。ステップバイステップガイド：MyBankMatch。

IBAN が名義人に属していることを確認します（MyBankMatch）

お客様の WealthReader ライセンスに紐付けられたお客様ご自身の銀行の SEPA 受取人確認（VoP）を利用して、IBAN が指定された名義人に属しているかどうかを確認します。銀行の判定結果を返します。ローカルでの氏名類似度計算で置き換えることはなく、支払指図の作成、承認、実行も一切行いません。

最初の呼び出しの前に

  1. MY_BANK_MATCH 製品を含み、利用可能なクォータがある有効なライセンスをご用意ください。
  2. クライアント · MyBankMatch を開き、銀行を接続 をクリックして、WealthReader がホストするウィンドウで認証を完了してください。トークン化された接続はお客様の api_key に紐付けられます。銀行トークンがブラウザに渡されることはなく、クエリのパラメーターでもありません。

リクエスト：/entities/ と同様に、api_key、iban、name を含むフォームエンコードされた本文（application/x-www-form-urlencoded）。JSON は送信せず、X-API-Key ヘッダーも使用しません。api_key はお客様のバックエンドで保管してください。

レスポンス：HTTP 200 は製品の結果が得られたことを示すものであり、氏名が一致したことを示すものではありません。success を確認してから payload.result を確認してください。

payload.result 意味 追加フィールド 課金対象
MATCH 銀行は氏名が名義人と一致すると判断しています。 なし。 はい、0.10 EUR。
PARTIAL_MATCH 銀行が部分一致（CLOSE_MATCH）を返しています。 suggested_name。 はい、0.10 EUR。
NO_MATCH 銀行は氏名が一致しないと示しています。 なし。 はい、0.10 EUR。
NOT_CONFIGURED ライセンスにまだ銀行が紐付けられていません。 setup_url。 いいえ。
REAUTH_REQUIRED 銀行との接続に再認証が必要です。 setup_url、reason_code。 いいえ。
NOT_POSSIBLE 利用可能な判定結果を取得できませんでした。NO_MATCH と同じ意味ではありません。 reason。 いいえ。

クォータを消費するのは MATCH、PARTIAL_MATCH、NO_MATCH のみです。入力エラーや結論の出ない結果は課金されません。

冪等キーや無料の再試行はありません。 レスポンスを受け取れなかった場合（タイムアウト、ネットワーク障害、または解釈できない本文）、お客様のアプリケーションでは結果とクォータの消費状況が不明になることがあります。同じ照会を自動的に再送信しないでください。クライアントで履歴を確認し、statistics.SESSION を添えてサポートにお問い合わせください。

完全なガイド：MyBankMatch。

Request Body schema: application/x-www-form-urlencoded
required
api_key
required
string

MY_BANK_MATCH 製品を含み、利用可能なクォータがある有効なライセンスの 16 進数 8 文字のキー。お客様のバックエンドで保管してください。

iban
required
string

SEPA 加盟国の IBAN。空白を削除して大文字に変換し、その国の桁数と mod-97 のチェックディジットを検証します。

例: ES9321005707250200257112

name
required
string <= 140 characters

名義人の氏名。空でないこと、有効な UTF-8 であること、制御文字を含まないこと、140 文字以内であることが必要です。前後の空白は削除され、内部の連続する空白は 1 つにまとめられます。

例: Wealthreader S.L.

Responses

Request samples

Content type
application/x-www-form-urlencoded
api_key=a1b2c3d4&iban=ES9321005707250200257112&name=Wealthreader%20S.L.

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "payload": {
    },
  • "statistics": {
    }
}

Payments

支払人の銀行から開始される SEPA の口座間決済です。統合方法は 2 つあります。

  • Fast Track：POST /payments/?action=fast-track を 1 回呼び出すだけで決済 URL が返され、Wealth Reader がお客様の notification_url に OK または KO を通知します。Fast Track 決済 を参照してください。
  • ウィジェット：お客様のバックエンドが POST /payments/?action=create で変更不可の決済インテントを作成し、返されたトークンでウィジェットを開き、POST /payments/?action=status で結果を確認します。決済の概要 および ステータス、ポーリング、照合 を参照してください。

すべての /payments/?action=... 呼び出しに共通するルール

  • POST メソッドを使用し、Content-Type: application/json ヘッダーを付け、本文には JSON オブジェクトを指定します（最大 32768 バイト）。
  • 認証は、PAYMENTS 製品を含む有効なライセンスの X-API-Key ヘッダー（wr_live_ に続く 72 文字の英字または数字）のみで行います。本文で送信することはありません。認証済みの各呼び出しは、ライセンスの呼び出し上限にカウントされます。
  • 本文はホワイトリスト方式で検証されます。必須フィールドが欠落している場合や想定外のフィールドが含まれている場合は、422 invalid_request が返されます。
  • 唯一の肯定的な資金確認は payment_status: settled です。ウィジェットのイベント、SCA からの戻り、または interaction_status: completed は、決済が完了したことを意味するものではありません。

エラー形式：安定した error.code を含む application/json（problem+json ではありません）。error.message は参考情報であり、変更される可能性があります。

{"success": false, "error": {"code": "invalid_request", "message": "The request body has an invalid schema."}}
HTTP error.code 理由
400 invalid_json 本文が空、無効、または JSON オブジェクトではありません。
401 invalid_api_key X-API-Key が欠落している、形式が不正、不明、または無効です。
403 payments_not_allowed ライセンスに PAYMENTS 製品が含まれていません。
404 action_not_found 不明な action です。
405 method_not_allowed POST 以外のメソッドです。
413 request_too_large 本文が 32768 バイトを超えています。
415 json_required Content-Type が application/json ではありません。
422 invalid_request フィールドが欠落しているか、想定外のフィールドがあります。
429 api_limit_reached ライセンスの呼び出し上限に達しました。
500 internal_error 予期しないエラーです。
503 payments_disabled, payments_accept_new_disabled, payment_storage_unavailable, payment_state_unavailable サービスが一時的に利用できないか、新規決済の受付が一時停止されています。

Fast Track 決済の OK または KO 通知 Webhook

Wealth Reader は、Fast Track 決済のステータスを確認して最終ステータスにあることを検出すると、その決済の notification_url にこの POST を送信します。reconciliation_required は最終ステータスではないため通知されません。status で確認してください。

  • outcome が ok になるのは、銀行が決済を完了した（settled）場合のみです。rejected、cancelled、expired、failed の場合は ko が通知されます。
  • ステータスは、支払人が決済ページに留まっている間（ページは最終結果が出るか決済セッションが失効するまで照会を続けます）と、お客様が status を呼び出すたびに確認されます。別途スケジュールされた送信はありません。銀行が結論を出す前に支払人がページを離れた場合や、お客様のサーバーが 2xx を返さない場合は、次回の確認時に通知が送信されます。支払人をリダイレクトしてから数分経っても届かない場合は、payment_intent_id を指定して status を呼び出してください。この呼び出しにより、保留中の通知も送信されます。
  • 任意の 2xx で応答すると、配信済みとして扱われます。Wealth Reader はリダイレクトに従わず、最大 3 秒間待機します。
  • 同じ通知が複数回届く場合があります。customer_reference と outcome の組み合わせを冪等として扱ってください。
  • リクエストには署名がありません。価値の高い商品を引き渡す前に、お客様の X-API-Key と通知内の payment_intent_id を使用して、status で結果を確認してください。
header Parameters
User-Agent
required
string
Value: "WealthReader-Payments"
Request Body schema: application/json
required
outcome
required
string
Enum: "ok" "ko"

settled の場合のみ ok。

payment_status
required
string
Enum: "settled" "rejected" "cancelled" "expired" "failed"

最終的な資金面の結果。

customer_reference
required
string

決済の作成時に送信した Idempotency-Key。

payment_intent_id
required
string <uuid>

fast-track が返した識別子。status で結果を確認する際に使用してください。

Responses

Request samples

Content type
application/json
Example
{
  • "outcome": "ok",
  • "payment_status": "settled",
  • "customer_reference": "11111111-1111-4111-8111-111111111111",
  • "payment_intent_id": "3f2b8c1e-5d4a-4b6f-9e21-7c0d4a1b2e3f"
}

決済を作成し、その URL を取得します（Fast Track）

1 回の呼び出しで決済 URL を返します。支払人はその URL を開き、自身の銀行で承認します。決済が最終ステータスに達すると、Wealth Reader はお客様の notification_url に OK または KO を通知します（notification_url Webhook を参照）。内部では create と同じ変更不可のインテントが作成されます。金額、受取人、摘要はブラウザに届く前に確定されます。

Idempotency-Key ヘッダーは、お客様の加盟店参照番号（通知内の customer_reference）も兼ねます。本文では送信しません。同じキーを同じ本文で再送すると、同じ URL が返されます。異なるデータ（異なる logo を含む）で再利用すると、レスポンスは 409 idempotency_conflict になります。

この API では、即時振込に独自の上限はありません。銀行は受け付けられない振込を（金額を理由とするものも含めて）拒否し、その拒否は KO として届きます。

header Parameters
X-API-Key
required
string

PAYMENTS 製品を含むライセンスの API キー。お客様のバックエンドで保管してください。

Idempotency-Key
required
string [ 16 .. 128 ] characters

16〜128 文字。英字または数字で始まり、英字、数字、. _ : - のみを含む必要があります。UUID v4 を使用できます。通知で返される加盟店参照番号でもあります。

Request Body schema: application/json
required
amount
required
string

主通貨単位の金額を JSON 文字列で指定します。"15.50" は 15.50 EUR です。小数点のない整数（"15"）も使用できます。小数点以下は最大 2 桁のため、"15.5" と "15.50" は同じ金額です。最小値は 0.01 です。最大値は、各顧客が自身の銀行で設定している上限によって制限されます。

例: 15.50

currency
required
string
Value: "EUR"

ISO 4217 通貨コード。このバージョンでは EUR のみです。

例: EUR

required
object (payments-beneficiary)

振込の受取人。決済の作成後は変更できません。

reference
required
string [ 1 .. 140 ] characters

明細に表示される摘要。最大 140 文字。

例: Pedido 78901

priority
required
string
Enum: "normal" "instant"

normal（SEPA 振込）または instant（SEPA 即時振込）。

例: normal

notification_url
required
string <= 2000 characters

OK または KO の通知を受け取る公開 https URL。認証情報を含めず、ポートを指定する場合は 443 とし、プライベートアドレス、ローカルアドレス、メタデータアドレスは使用できません。

例: https://tienda.example.com/pagos/aviso

logo
string <= 2048 characters

任意。お客様の店舗の SVG 形式ロゴの公開 https URL（パスは .svg で終わる必要があります。クエリパラメーターは使用可能）。認証情報、フラグメント、プライベートアドレスを含めず、最大 2048 文字の ASCII。決済ページでは概要の上に表示されます。Wealth Reader はダウンロードせず、支払人のブラウザが読み込みます。それ以外の値の場合は 422 invalid_logo が返されます。

例: https://tienda.example.com/marca/logo.svg

Responses

Request samples

Content type
application/json
{}

Response samples

決済インテントを作成します（ウィジェット）

変更不可の決済インテントを作成し、支払人のブラウザでウィジェットを開くための短期間有効なトークンを返します。金額、受取人、摘要はバックエンドで確定され、ブラウザから変更することはできません。ウィジェットが閉じられた後、お客様のバックエンドから status で結果を確認してください。

本文には 2 つのバリエーションがあります。

  • 標準：お客様が amount_minor、currency、beneficiary、reference、customer_reference、allowed_origin を指定します。
  • 管理プロファイル（例：cruz_roja_demo）：Wealth Reader が受取人、摘要、上限を指定し、お客様は profile、institution_code、amount_minor、customer_reference、allowed_origin を送信します。銀行の一覧は profile-institutions で取得してください。

同じ Idempotency-Key を同じ本文で再送すると、同じインテントが返されます（200、idempotent_replay: true）。異なるデータで再利用すると、レスポンスは 409 idempotency_conflict になります。キーはお客様の会社ごとに固有です。

ガイド：インテントと冪等性 および ウィジェットとの統合。

header Parameters
X-API-Key
required
string

PAYMENTS 製品を含むライセンスの API キー。お客様のバックエンドで保管してください。

Idempotency-Key
required
string [ 16 .. 128 ] characters

16〜128 文字の可視 ASCII 文字。決済ごとに 1 つ生成し（UUID v4 を使用できます）、呼び出しを再試行する場合は同じキーを再利用してください。

Request Body schema: application/json
required
One of
amount_minor
required
integer >= 1

補助通貨単位（セント）の金額を JSON の整数で指定します。1500 は 15.00 EUR です。最大値は、各顧客が自身の銀行で設定している上限によって制限されます。

例: 1500

currency
required
string
Value: "EUR"
required
object (payments-beneficiary)

振込の受取人。決済の作成後は変更できません。

reference
required
string [ 1 .. 140 ] characters

明細に表示される摘要。最大 140 文字。

例: Pedido 78901

customer_reference
required
string <= 128 characters

お客様の社内用の決済参照番号。1〜128 文字。英字または数字で始まり、英字、数字、. _ : - のみを含みます。

例: order-78901

allowed_origin
required
string

ウィジェットを開くページのオリジン（https://host[:puerto]; パス、クエリ、フラグメントは含めません）。ウィジェットはこのオリジンからのみ動作します。

例: https://tienda.example.com

locale
string
Value: "es"

任意。ウィジェットの言語。このバージョンでは es のみです。

expected_mode
string
Enum: "mock" "live"

任意。環境と一致しない場合、決済を作成する代わりに 409 payment_mode_mismatch が返されます。

allowed_institution_codes
Array of strings <= 2500 items

任意。支払人が選択できる、重複のない銀行コード（/payments/entities/ を参照）の空でないリスト。

例: 

[
  "bbva-es",
  "santander-es"
]
logo
string or null

任意。お客様の SVG 形式ロゴの公開 https URL（パスは .svg で終わること）。認証情報、フラグメント、プライベートアドレスを含めず、最大 2048 文字。

Responses

Request samples

Content type
application/json
Example
{
  • "amount_minor": 1500,
  • "currency": "EUR",
  • "beneficiary": {
    },
  • "reference": "Pedido 78901",
  • "customer_reference": "order-78901",
  • "allowed_origin": "https://tienda.example.com"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "payment": {
    }
}

決済のステータスを照会します

銀行による結論が得られるまで、サーバー間で決済のステータスを照会します。コールバック、SCA からの戻り、またはウィジェットが閉じられたことは資金確認ではありません。資金確認となるのは payment_status: settled のみです。

Wealth Reader はインテントごとの外部照会回数を制限しています。お客様のバックエンドでもバックオフを適用し、結果が曖昧な間は新しいインテントを作成しないでください。

曖昧な結果：開始リクエストの送信後にネットワーク障害、タイムアウト、または認識できないレスポンスが発生すると、インテントは payment_status: unknown の reconciliation_required に変わり、レスポンスには reconciliation が含まれます。開始処理が自動的に繰り返されることはありません。識別子と冪等キーを保持し、新しいインテントの作成や再承認は行わず、automatic_recovery が false の場合はポーリングを停止して、reconciliation.reference を添えてサポートにエスカレーションしてください。

Fast Track 決済では、決済が最終ステータスに達している場合、この照会によって保留中の OK/KO 通知も notification_url に送信されます。

ガイド：ステータス、ポーリング、照合。

header Parameters
X-API-Key
required
string

決済を作成したライセンスの API キー。

Request Body schema: application/json
required
payment_intent_id
required
string <uuid>

create が返した payment.id（Fast Track の場合は fast-track が返した payment_intent_id）。

例: 3f2b8c1e-5d4a-4b6f-9e21-7c0d4a1b2e3f

refresh
boolean
Default: true

任意。true は必要に応じて銀行に最新のステータスを照会します。false は保存済みのステータスを返します。

Responses

Request samples

Content type
application/json
{
  • "payment_intent_id": "3f2b8c1e-5d4a-4b6f-9e21-7c0d4a1b2e3f",
  • "refresh": true
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "payment": {
    }
}

管理プロファイルの銀行と条件を一覧表示します

お客様の会社で有効化されている管理プロファイルの条件（受取人、摘要、金額の上限）と、支払人が選択できる銀行を返します。選択された code を create の institution_code として使用してください。

header Parameters
X-API-Key
required
string

PAYMENTS 製品を含むライセンスの API キー。

Request Body schema: application/json
required
profile
required
string

管理プロファイルのコード。

例: cruz_roja_demo

Responses

Request samples

Content type
application/json
{
  • "profile": "cruz_roja_demo"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "profile": {
    }
}

決済に利用できる銀行を一覧表示します

決済を開始できる銀行のカタログで、各銀行のロゴと対応する決済方法を含みます。X-API-Key は任意です。送信した場合は検証され、呼び出しとしてカウントされます。同じフィルターを JSON 本文で指定する POST、および X-API-Key が必須の POST /payments/?action=entities にも対応しています。

不明なフィルターは無視され、検証エラーになることはありません。

query Parameters
country
string
Example: country=ES

ISO 3166-1 alpha-2 の国コード。ALL または空の場合はフィルターなしを意味します。

例: ES

search
string

名称またはコードに含まれるテキスト。大文字と小文字は区別されません（エイリアス q）。

code
string
Example: code=santander-es

銀行の正確なコード。大文字と小文字は区別されません。

例: santander-es

payment_method
string
Enum: "sepa_credit_transfer" "instant_sepa_credit_transfer"

この決済方法に対応している銀行のみ。

limit
integer [ 1 .. 2000 ]

ページサイズ（1〜2000）。

offset
integer >= 0

スキップする結果の件数。

header Parameters
X-API-Key
string

任意。送信した場合は検証され、呼び出しとしてカウントされます。

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "total": 1,
  • "entities": [
    ]
}

Cards (real time)

Real-time card expense synchronization from the Open Sync mobile app: per-customer employee pre-registration, signed webhooks (card_transaction.created / card_enrollment.confirmed), and REST query / backfill.

Register or rotate the real-time cards webhook

Creates or updates the webhook URL of the customer for the card_transaction.created and card_enrollment.confirmed events (see the cards-webhook-delivery schema for the delivery format and signature). On first setup, or when rotate_secret is true, a new webhook_secret (64 hex characters) is generated and returned once; in any other case webhook_secret comes back as null in the response and cannot be retrieved again. webhook_url must always be https:// and must resolve to a publicly routable host: localhost, private, loopback, link-local (including the cloud metadata address), CGNAT, multicast and reserved addresses are rejected, in any notation (hexadecimal, decimal, octal, short dotted or IPv4-mapped IPv6), and so is a hostname that does not resolve at all. The same check runs again right before every delivery, not only at registration: if the host is repointed at an internal address afterwards (DNS rebinding) the delivery is closed as failed with response_excerpt "blocked_host". Sending null in webhook_url disables webhooks for that customer; omitting the field leaves the stored URL untouched, which is how the secret is rotated without changing the URL.

Request Body schema: application/json
required
api_key
required
string

API key of the customer.

webhook_url
string or null

https:// URL that will receive the events, on a publicly routable host that resolves in DNS. null disables webhooks; omitting the field leaves the stored URL unchanged.

例: https://cliente.example.com/webhooks/wealthreader-cards

rotate_secret
boolean
Default: false

When true, generates and returns a new webhook_secret.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Pre-register the email of an employee

Creates an enrollment request in pending status with a short expiry (ttl_minutes, 20 by default, between 1 and 60) for the employee to confirm by opening the mobile app and entering that email (POST /user-sync-validation/, no contract change for the app). It is idempotent: repeating the call for the same (api_key, email) while it is still pending and not expired returns the same request. If the email is already linked to the calling customer, it returns status "active" directly. If it is already linked to a different customer, it returns 409. Rate limit: at most 60 calls to this endpoint per api_key every 60 seconds, counting every attempt and not only the ones that create a row, checked before anything else so the answers that create nothing (200 already active, 409 linked to another customer, 400) cannot be walked as an enumeration oracle. Exceeding it returns 429 with code rate_limited.

Request Body schema: application/json
required
api_key
required
string

API key of the customer.

email
required
string <email>

Email of the employee to pre-register.

例: empleado@cliente.com

ttl_minutes
integer [ 1 .. 60 ]
Default: 20

Minutes the request stays valid before expiring.

Responses

Request samples

Content type
application/json
{
  • "api_key": "a1b2c3d4",
  • "email": "empleado@cliente.com",
  • "ttl_minutes": 20
}

Response samples

Content type
application/json
{
  • "success": true,
  • "payload": {
    }
}

Check the status of an enrollment

Read-only status of an enrollment request. It has no side effects on card users, unlike POST /user-sync-validation/, which does confirm. The only write allowed is lazily marking a pending enrollment whose expiry date has already passed as expired.

query Parameters
api_key
required
string
Example: api_key=a1b2c3d4

API key of the customer. Note it travels in the query string, so it ends up in access logs and intermediary proxies.

例: a1b2c3d4

enrollment_id
required
string
Example: enrollment_id=0f3a9c7b1d2e4f5a6b7c8d9e0f1a2b3c

Identifier returned by POST /cards/enrollments/.

例: 0f3a9c7b1d2e4f5a6b7c8d9e0f1a2b3c

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "payload": {
    }
}

Query / backfill real-time card transactions

Returns the real-time card transactions received for the employees linked to this api_key, ordered by ascending id. Meant both for periodic backfill (poll with date_from/date_to and paginate with since_id) and for one-off queries. This is the same transaction object carried by the card_transaction.created webhook.

query Parameters
api_key
required
string
Example: api_key=a1b2c3d4

API key of the customer. Note it travels in the query string, so it ends up in access logs and intermediary proxies.

例: a1b2c3d4

date_from
string <date>
Example: date_from=2026-07-01

YYYY-MM-DD, on the operation date. Default: today minus 3 days.

例: 2026-07-01

date_to
string <date>
Example: date_to=2026-07-11

YYYY-MM-DD, on the operation date. Default: today.

例: 2026-07-11

email
string <email>
Example: email=empleado@cliente.com

Filters by the email of the employee.

例: empleado@cliente.com

since_id
integer
Example: since_id=216

Exclusive cursor on the transaction id, for pagination.

例: 216

limit
integer <= 1000
Default: 500
Example: limit=500

Maximum number of transactions to return (500 by default, 1000 max).

例: 500

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "payload": {
    }
}