OAuth

配置 OAuth 流程

用户在 Wealth Reader 完成认证后，带着 code 返回您的 redirect_uri，您用它换取与 iframe callback 相同的 JSON。

如果无法嵌入 iframe（原生应用或重定向流程），请使用此路径。如果您的 Web 应用可以承载 iframe，请改用 iframe frontend。

快速路径

使用 access_type=oauth 授权域名。
生成 nonce、state 和 code_verifier。计算 challenge_code。将 wr_conf 编码为十六进制。保存 nonce 和 code_verifier。
带着这些参数将用户重定向到 https://oauth.wealthreader.com/oauth2/。
在 redirect_uri 上接收带有 nonce 和 code 的 GET。
向 https://oauth.wealthreader.com/token/ 发送 POST 并获取银行 payload。

1. 授权域名

domain 必须是您将用作 redirect_uri 和 url_callback 的同一 URL。

curl --location 'https://api.wealthreader.com/domains/' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'method=add' \
  --data-urlencode 'api_key=YOUR_API_KEY' \
  --data-urlencode 'domain=https://example.com/oauth/success.php' \
  --data-urlencode 'url_callback=https://example.com/oauth/success.php' \
  --data-urlencode 'access_type=oauth' \
  --data-urlencode 'tokenize=1'

也可以在客户中心选择 OAuth 集成来注册域名。

2. 生成挑战值

生成三个随机的 41 个字符的字母数字字符串（A-Za-z0-9），并转换为十六进制（bin2hex）。每个十六进制值为 82 个字符。

值	如何获得	发送位置
`redirect_uri`	返回 URL，与已授权的 URL 相同	query 和 `POST /token/`
`nonce`	41 个字符 → hex	query；在 `GET` 中返回
`state`	41 个字符 → hex	query
`code_verifier`	41 个字符 → hex	仅 `POST /token/`（不在 query 中）
`challenge_code`	`code_verifier` 的 SHA-256（hex digest）	query，作为 `challenge_code`
`wr_conf`	选择器配置 JSON → hex	query

wr_conf 接受与 iframe frontend 相同的字段。转换为十六进制之前的示例：

{
  "operation_id": "op_a1b2c3d4e5f6",
  "entities_to_display": [],
  "wait_full_response": true
}

该 JSON 的十六进制：

7b226f7065726174696f6e5f6964223a226f705f613162326333643465356636222c22656e7469746965735f746f5f646973706c6179223a5b5d2c22776169745f66756c6c5f726573706f6e7365223a747275657d

将 wr_conf 转换为十六进制不会生成 nonce、state 或 code_verifier。这三个值需单独创建，并必须持久化（以 nonce 为键）直到 POST /token/。

与我们内部使用等效的 PHP 示例：

function randomAlnum($length)
{
    $alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
    $value = '';
    for ($i = 0; $i < $length; $i++) {
        $value .= $alphabet[random_int(0, strlen($alphabet) - 1)];
    }
    return $value;
}

$nonce = bin2hex(randomAlnum(41));
$state = bin2hex(randomAlnum(41));
$code_verifier = bin2hex(randomAlnum(41));
$challenge_code = hash('sha256', $code_verifier);

$wr_conf = bin2hex(json_encode([
    'operation_id' => 'op_a1b2c3d4e5f6',
    'entities_to_display' => [],
    'wait_full_response' => true,
]));

3. 重定向用户

构建 query 并重定向。以下示例中的值彼此对应：

https://oauth.wealthreader.com/oauth2/?challenge_code=c725133644f703a5f069a09583fa981eb5b8820071a4450f8d47ff8b1c6a879a
&code_challenge_method=S256
&redirect_uri=https://example.com/oauth/success.php
&response_type=code
&state=73684148464b3778795873626d724e62734749724336685a7a687854336c317934524f516831316a45
&nonce=696d6a716d4a47746d714e52656562496f61786468765a30335a4b4a646d6c546c5339654e42586573
&wr_conf=7b226f7065726174696f6e5f6964223a226f705f613162326333643465356636222c22656e7469746965735f746f5f646973706c6179223a5b5d2c22776169745f66756c6c5f726573706f6e7365223a747275657d

用户会看到银行选择器并完成认证；结束后 Wealth Reader 将其送回您的 redirect_uri。

4. 在 `redirect_uri` 接收 GET

https://example.com/oauth/success.php?nonce=696d6a716d4a47746d714e52656562496f61786468765a30335a4b4a646d6c546c5339654e42586573
&code=1234567890abcdef1234567890abcdef1234567890a

使用 nonce 取回您在第 2 步保存的 code_verifier。如果 nonce 不是您签发的，请丢弃该请求。

5. 完成挑战

curl --location --request POST 'https://oauth.wealthreader.com/token/' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'redirect_uri=https://example.com/oauth/success.php' \
  --data-urlencode 'code=1234567890abcdef1234567890abcdef1234567890a' \
  --data-urlencode 'code_verifier=6634413364504337675230375a624671644f644d42414241303037737374684f494877477649723433'

字段	值
`grant_type`	`authorization_code`
`redirect_uri`	与第 3 步完全相同
`code`	来自 `GET` 的值
`code_verifier`	您在第 2 步生成的十六进制值

如果这些值匹配，响应即为银行 JSON（与 iframe callback 相同的架构）：success、payload 和 statistics（operation_id、token、code）。

如果之后要用 POST https://api.wealthreader.com/entities/ 刷新，请保存 token 和 code。

示例代码

有一个 Java 示例（JBang / Java 17）用于生成参数并完成挑战：

下载 Java 示例（ZIP）

如果需要其他语言的同一流程，请写信至 support@wealthreader.com。

最后更新于 2026-08-15