# USNpay 支付宝/微信/PayPal 收款 · 商家接入指南

USNpay 支持你用**自己的支付宝、微信、PayPal 官方商户号**收款。买家付款后，**钱直接进入你自己的账户**，USNpay 不经手任何资金，只负责帮你生成支付订单、接收官方支付结果通知、对账。

> **重要**：此功能要求你拥有**正规申请的支付宝/微信商户资质或 PayPal 商家账户**。这是合规收款的前提。请勿使用个人收款码或他人账户从事经营性收款。

---

## 一、整体流程

```
买家 → 打开收银台 → 选支付宝/微信/PayPal → 扫码或跳转付款
                                      ↓
                          钱进入你自己的商户账户
                                      ↓
        支付宝/微信官方通知 USNpay → 平台标记订单已支付
                                      ↓
              从你的平台余额扣手续费 → 通知你的系统（可选）
```

**关键点**：
- 钱直达你的账户，平台碰不到
- 每笔成功收款的**手续费从你的 USNpay 平台余额中扣除**，请保持余额充足，**余额不足时无法发起收款**
- 支付结果由支付宝/微信**官方异步通知**，真实可靠

---

## 二、手续费说明

- 费率默认 **0.6%**（以平台实际配置为准）
- 手续费在**买家付款成功后**，从你的 USNpay **平台余额**中扣除（按当时汇率从 USD 余额折算）
- 请先在「账户余额」中充值，保持余额充足
- 在「支付宝/微信收款 → 收款订单」里可看到每笔的手续费与你的实得金额，以及累计统计

---

## 三、支付宝接入

### 1. 申请支付宝商户资质
1. 登录[支付宝开放平台](https://open.alipay.com/)
2. 创建一个「网页&移动应用」，完成企业认证、签约「当面付」或「手机网站支付」产品
3. 拿到应用的 **App ID**

### 2. 生成密钥
1. 用支付宝官方的「密钥生成工具」生成一对 **RSA2 密钥**（应用私钥 + 应用公钥）
2. 把**应用公钥**上传到支付宝开放平台，平台会给你一个**支付宝公钥**
3. 你需要准备两样：
   - **应用私钥**（你自己保管的那个）
   - **支付宝公钥**（平台给你的那个）

### 3. 在 USNpay 填写
进入会员中心 →「支付宝/微信收款」→ 支付宝收款，填写：

| 字段 | 填什么 |
|------|--------|
| App ID | 你的支付宝应用 ID |
| 商户应用私钥 | 上一步的「应用私钥」（PKCS8 格式，去掉头尾，只留中间 base64） |
| 支付宝公钥 | 平台给你的「支付宝公钥」 |

### 4. 配置回调地址
把页面上显示的**回调地址**（形如 `https://你的域名/fiat/notify/alipay`）填到支付宝开放平台的应用「异步通知地址」中。

---

## 四、微信接入

微信比支付宝多几项凭据，请按官方流程申请。

### 1. 申请微信支付商户号
1. 登录[微信支付商户平台](https://pay.weixin.qq.com/)
2. 完成商户入驻，开通 **Native 支付**（扫码）和/或 **H5 支付**（手机网页）
3. 把你的微信公众号 / 小程序 / 服务商与该商户号关联，拿到 **AppID**

### 2. 准备 API 凭据
在微信商户平台「API 安全」中：
1. 设置 **APIv3 密钥**（32 位字符，自己设定并牢记）
2. 申请**商户 API 证书**，下载证书压缩包，里面有：
   - `apiclient_key.pem`（商户私钥）
   - 证书序列号（在证书详情里可看到，或用工具读取）

### 3. 在 USNpay 填写
进入会员中心 →「支付宝/微信收款」→ 微信收款，填写：

| 字段 | 填什么 |
|------|--------|
| AppID | 关联的公众号/小程序/服务商 appid（wx 开头） |
| 商户号 mch_id | 你的微信支付商户号 |
| APIv3 密钥 | 你在「API 安全」设置的 32 位密钥 |
| 商户证书序列号 | 商户 API 证书的序列号 |
| 商户私钥 | `apiclient_key.pem` 文件的内容（整段粘贴） |

### 4. 配置回调地址
把页面上显示的**回调地址**（形如 `https://你的域名/fiat/notify/wechat`）填到微信商户平台的回调配置中。系统下单时会自动在地址后附加商户标识，无需你手动加。

> **H5 支付额外要求**：微信 H5 支付需要在微信商户平台「产品中心 → H5 支付」里配置**授权域名**，否则手机端支付会报错。

---

## 五、PayPal 接入

PayPal 适合海外 / 跨境收款，按 **USD 美元**结算，流程比支付宝/微信简单（无需证书）。

### 1. 创建 PayPal 应用
1. 登录 [PayPal 开发者后台](https://developer.paypal.com/)
2. 进入「Apps & Credentials」，创建一个 App
3. 拿到该 App 的 **Client ID** 和 **Secret**

> 后台分 **Sandbox（沙箱测试）** 和 **Live（正式）** 两套环境，凭据各自独立。建议先用沙箱测试。

### 2. 在 USNpay 填写
进入会员中心 →「支付宝/微信收款」→ PayPal 收款，填写：

| 字段 | 填什么 |
|------|--------|
| Client ID | PayPal 应用的 Client ID |
| Secret | PayPal 应用的 Secret |
| 沙箱环境 | 测试阶段勾选（用沙箱凭据 + 沙箱买家账户测试）；正式收款时取消勾选 |

### 3. 收款说明
- PayPal 按 **USD 美元**收款，收银台金额请按**美元**填写
- 手续费从你的 USNpay **平台余额**扣除（本就是 USD，无需汇率换算）
- PayPal 采用「**跳转付款 → 付款后回跳确认**」模式：买家在 PayPal 完成付款后会自动跳回，平台此时确认收款。**买家付款后需回到页面**，收款才会确认成功

---

## 五之二、手动收款（无需商户资质，最快上手）

**没有支付宝/微信官方商户号也能收款**：用你**自己的**支付宝/微信收款码（个人码也行），
买家扫码转账，你在后台确认到账即可。钱直接进你的账户，平台不经手。

### 1. 开启（3 步，无需任何资质审核）
1. 会员中心 →「手动收款」→ 打开总开关
2. 上传收款码截图（支付宝、微信可各传多个）
3. 填写**收款人姓名**和**收款账号**（支付宝手机/邮箱，或微信号）——买家转账前会看到，用于核对身份

### 2. 它怎么工作（唯一金额机制）
个人收款码收款有个天然难题：**钱到账了，但不知道是哪笔订单付的**。系统的解法是给每笔订单分配一个**唯一金额**：

- 订单原价 ¥99 → 系统分配应付 **¥99.37**（尾数 .37 是这笔订单的"身份证"）
- 买家必须**按这个精确金额**转账，页面会明确提示
- 你在待确认队列里看到「¥99.37」，就知道对应的是哪笔订单
- 金额**绝不会低于原价**（若尾数组合后低于原价则整数元进一位），买家最多多付不到 1 元

### 3. 收款流程
1. 买家下单 → 看到你的收款码 + 唯一应付金额 + 15 分钟付款倒计时
2. 买家扫码转账 → 点「我已付款」
3. **你的后台**「手动收款 → 待确认订单」出现该笔（有角标提醒），显示应付金额、手续费、剩余确认时间
4. 你打开支付宝/微信核对是否收到**这个精确金额** → 点「确认到账」（没收到就点「驳回」）
5. 确认后：系统自动发货、通知买家页面跳转、推送回调给你的系统

### 4. 手续费
在你点「**确认到账**」时才扣（不是下单时），从平台余额按当时汇率折 USD 扣除。
队列里每笔都显示手续费和净得金额。

### 5. 对接方式（给开发者）
走**法币下单接口**，传 `pay_mode=manual`：

```json
POST /v1/fiat/orders
{
  "pay_mode": "manual",
  "amount": "99.00",
  "subject": "订单 #10086",
  "out_trade_no": "10086",
  "notify_url": "https://yourstore.com/notify",
  "return_url": "https://yourstore.com/thank-you"
}
```

- **不要传 `asset`**：`asset`（USDT 等）是**加密订单**的参数。手动收款是法币收款，不涉及加密货币，传了无效。
- `provider` **可不填**（买家在收款页自选支付宝/微信）；想预选就传 `type: "alipay"` 或 `"wechat"`——返回的 `manual_url` 会**自动带上** `&type=`，直接跳转即可，买家落地直接出对应码（商户无该类型可用码时自动回退自选）。
- `amount` **默认按人民币计**。你的系统若按美元定价，务必加 `"source_fiat": "USD"`，否则 `99.00` 会当 ¥99 收（少收钱）。
- 返回 `scene=manual` + `manual_url` → 把买家跳过去即可。
- 成功回调格式与普通法币**完全一致**（`out_trade_no`/`amount`/`fee`/`net_amount`/`status=paid`），回调代码无需为手动收款改动。

> 用通用 PHP 插件的话已封装好：`pay.php?action=create&pay_type=manual&amount=99.00&order=10086`

### 6. 注意事项
- 个人收款码有单日/单月限额（支付宝/微信各自规定），大额收款建议仍用官方商户号
- 到账靠**人工确认**，请及时处理待确认队列（买家在等你确认才能拿到货）
- 买家超时未付会自动取消并释放金额；你也可主动驳回

---

## 六、收银台用法

给买家的收款页面地址格式如下，把参数换成你的实际值即可：

```
https://你的域名/fiatpay?member=商户ID&amount=金额&subject=商品名&out_trade_no=你的订单号&notify_url=你的回调地址&return_url=付款后跳转地址
```

| 参数 | 必填 | 说明 |
|------|------|------|
| member | 是 | 你的商户 ID |
| amount | 是 | 收款金额（支付宝/微信按人民币元，PayPal 按美元，如 `99.00`） |
| subject | 否 | 商品名称 / 订单备注 |
| out_trade_no | 否 | 你系统里的订单号，用于幂等和对账 |
| notify_url | 否 | 付款成功后，平台通知你系统的地址 |
| return_url | 否 | 买家付款成功后自动跳转的地址 |

**买家体验**：
- 电脑打开 → 支付宝/微信显示二维码扫码付款，页面自动检测到账
- 手机打开 → 支付宝/微信直接跳转完成付款
- 选 PayPal → 跳转到 PayPal 页面付款，付款后自动跳回

---

## 七、付款结果通知（给开发者）

如果你填了 `notify_url`，付款成功后平台会向该地址 **POST** 一段 JSON，并在请求头带签名 `X-ChainPay-Signature`：

```json
{
  "order_no": "FO-20260531-A1B2C3D4",
  "out_trade_no": "你的订单号",
  "provider": "alipay",
  "status": "paid",
  "fiat": "CNY",
  "amount": "99.00",
  "fee": "0.59",
  "net_amount": "98.41",
  "channel_trade_no": "支付宝/微信交易号",
  "paid_at": "2026-05-31 16:00:00",
  "timestamp": 1730000000
}
```

**验签**：用你的 Webhook 密钥（会员中心 API 密钥页可见）对原始请求体做 `HMAC-SHA256`，与请求头 `X-ChainPay-Signature` 比对，一致才视为合法。处理完成后请返回 `success`（纯文本）。

---

## 八、常见问题

**Q：钱会进 USNpay 吗？**
A：不会。钱直接进你自己的支付宝/微信商户账户。USNpay 只帮你下单、接收支付结果、对账，并按比例从你的平台余额收手续费。

**Q：为什么提示余额不足无法收款？**
A：手续费从你的平台余额扣。请到「账户余额」充值后再收款。

**Q：买家付了款，但订单还显示待支付？**
A：通常是回调地址没配好，或服务器没收到官方通知。请检查支付宝/微信后台的回调地址是否填对、服务器是否能被外网访问。

**Q：私钥安全吗？**
A：所有密钥在数据库中**加密存储**，页面保存后不再回显。但请你也妥善保管原始密钥文件。

**Q：必须有营业执照/商户资质吗？**
A：是的。支付宝、微信的商户号都需要企业或个体工商户资质申请。PayPal 也需要注册商家账户。这是合规收款的前提。

---

*本文档随产品更新，以实际页面显示为准。*