OAuth

配置 OAuth 流程

用户在 Wealth Reader 完成认证后返回您的 redirect_uri，并携带 code。您的后端将其兑换为与 iframe callback 相同的 JSON。

无法嵌入 iframe 时（原生应用或重定向流程），请使用此方式。如果 Web 应用可以嵌入 iframe，请使用 iframe 前端。

快速流程

使用 access_type=oauth 授权域名。
生成 nonce、state 和 code_verifier。计算 challenge_code。将 wr_conf 编码为十六进制。保存 nonce 和 code_verifier。
携带这些参数将用户重定向到 https://oauth.wealthreader.com/oauth2/。
接收 GET 请求，地址为 redirect_uri，其中包含 nonce 和 code。
通过 POST 请求 https://oauth.wealthreader.com/token/，获取银行 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=TU_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. 生成挑战参数

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

值	生成方式	发送位置
`redirect_uri`	与已授权 URL 相同的返回地址	查询参数和 `POST /token/`
`nonce`	41 个字符 → 十六进制	查询参数；在 `GET` 中返回
`state`	41 个字符 → 十六进制	查询参数
`code_verifier`	41 个字符 → 十六进制	仅 `POST /token/`（不放入查询参数）
`challenge_code`	`code_verifier` 的 SHA-256（十六进制摘要）	查询参数 `challenge_code`
`wr_conf`	选择器配置 JSON → 十六进制	查询参数

wr_conf 支持与 iframe 前端相同的字段。转换为十六进制之前的示例：

{
  "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. 重定向用户

构建查询参数并重定向。以下示例中的值彼此一致：

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）。

如果后续需要刷新数据，请保存 token 和 code，并使用 POST https://api.wealthreader.com/entities/。

示例代码

提供一个生成参数并完成挑战的 Java 示例（JBang / Java 17）：

下载 Java 示例（ZIP）

如需其他语言的相同流程，请联系 support@wealthreader.com。

最后更新于 2026-09-10