> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 配置商户公钥

> 在 Waffo Dashboard 上传生产商户公钥、完成加签验证并查看审核状态。

生产环境使用 RSA 双向签名保护 API 通信。你需要在 Waffo Dashboard（Merchant Portal）上传商户公钥，并用配对的私钥完成验证。

| 密钥       | 持有方   | 用途                    |
| -------- | ----- | --------------------- |
| 商户私钥     | 商户    | 签名 API 请求和 Webhook 响应 |
| 商户公钥     | Waffo | 验证商户签名                |
| Waffo 私钥 | Waffo | 签名 API 响应和 Webhook    |
| Waffo 公钥 | 商户    | 验证 Waffo 签名           |

## 前提条件

* 你已激活生产账号。
* 你的角色为 **Super Admin**、**Admin** 或 **Dev**。
* 你已生成仅用于生产环境的 RSA 密钥对。
* 你可以安全访问商户私钥。私钥不能上传到 Dashboard 或发送给 Waffo。

## 公钥要求

| 项目      | 要求                             |
| ------- | ------------------------------ |
| 密钥长度    | 2048 位                         |
| 签名算法    | `SHA256WithRSA`                |
| 公钥格式    | X.509/SPKI Base64，单行且不含 PEM 头尾 |
| 公钥字符串长度 | 392 个字符                        |

## 生成生产密钥对

```bash theme={null}
openssl genpkey -algorithm RSA \
  -pkeyopt rsa_keygen_bits:2048 \
  -out merchant_private_key.pem

openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt \
  -in merchant_private_key.pem \
  | grep -v '^-----' \
  | tr -d '\n' > merchant_private_key.base64

openssl rsa -in merchant_private_key.pem -pubout \
  | grep -v '^-----' \
  | tr -d '\n' > merchant_public_key.base64
```

上传 `merchant_public_key.base64` 的内容。将 `merchant_private_key.pem` 和 `merchant_private_key.base64` 保存在服务端密钥管理系统中。

## 配置步骤

<Steps>
  <Step title="登录 Dashboard">
    打开 [Waffo Dashboard](https://dashboard.waffo.com/auth/login)，进入 **Settings → Integration**。
  </Step>

  <Step title="开始配置">
    在 **Merchant Sign Configuration Details** 中点击 **Configure**，将 **API Operation Type** 设为 **Payin**。
  </Step>

  <Step title="上传公钥">
    将完整的商户公钥粘贴到公钥输入框。
  </Step>

  <Step title="生成验证签名">
    复制系统为当前 Merchant 生成的验证字符串。使用配对的商户私钥，以 `SHA256WithRSA` 对验证字符串签名。

    ```bash theme={null}
    echo -n "WAFFO_VERIFY_XXXXXXXXXX" | \
      openssl dgst -sha256 -sign merchant_private_key.pem | \
      base64 | tr -d '\n'
    ```

    将 `WAFFO_VERIFY_XXXXXXXXXX` 替换为 Dashboard 显示的完整验证字符串。
  </Step>

  <Step title="提交审核">
    将单行 Base64 签名结果粘贴到验证输入框。点击 **Confirm**，并在确认弹窗中再次点击 **Confirm**。
  </Step>
</Steps>

## 查看审核状态

提交成功后，公钥状态首先显示为 **Pending**。Waffo 通常在 1 个工作日内完成审核，并通过邮件发送结果。

| 状态           | 说明                |
| ------------ | ----------------- |
| **Pending**  | 已提交，等待 Waffo 审核   |
| **Active**   | 已激活，可以用于生产 API 请求 |
| **Rejected** | 审核未通过，请查看原因并重新提交  |

<Warning>
  在公钥变为 **Active** 前，不要使用该密钥发送生产交易。
</Warning>

## 更换或新增公钥

提交新公钥时，现有 **Active** 公钥继续有效。新公钥审核通过后，再按计划切换生产私钥。

如果新公钥与当前 **Active** 公钥完全相同，Dashboard 会返回 `public key already exists`。请生成新的密钥对后重新提交。

## 驳回后重新提交

1. 进入 **Settings → Integration**。
2. 在 **Historical Versions** 中查看该版本的 **Reject Reason**。
3. 根据原因重新生成或修正密钥。
4. 再次完成公钥配置和加签验证。

驳回后可以重新提交。每次提交都会生成新的历史版本，不影响已有的 **Active** 公钥。

## 常见错误

| 错误                               | 原因                                              | 处理方法                        |
| -------------------------------- | ----------------------------------------------- | --------------------------- |
| `signature verification failed`  | 私钥与公钥不配对，或签名结果包含换行、空格或缺失内容                      | 确认密钥配对，并重新生成完整的单行 Base64 签名 |
| `public key count exceeds limit` | 当前 **API Operation Type** 的 **Active** 公钥数量达到上限 | 联系 Waffo 技术支持停用不再使用的旧公钥     |
| `public key record not found`    | 目标公钥记录不存在                                       | 刷新历史版本；问题持续时提供截图并联系技术支持     |
| `public key already exists`      | 提交内容与已有 **Active** 公钥相同                         | 生成全新的公私钥对                   |

下一步：返回[生产上线](/docs/zh/developer-docs/getting-started/go-live)完成生产订单验证。