# Eapple 收款 API 0.1.0

当前仅支持 Test。Adyen 未配置时，付款及退款接口返回 503，订单和支付链接可正常创建。

请求头：`X-API-Key: <业务 API 密钥>`。创建订单与退款另需 `Idempotency-Key`（8–128 字符）。同一键和相同内容返回原记录，内容变化返回 409。

## 创建订单

POST https://api.eapple.vip/api/v1/orders

请求示例：

```json
{"order_no":"SHOP-1001","amount":1000,"currency":"USD","description":"商品说明","expires_in":3600}
```

金额使用币种最小单位：USD 1000 表示 10.00 USD；JPY 1000 表示 1000 JPY。第一版币种白名单为 USD/EUR/GBP/HKD/SGD/AUD/CAD/JPY/CNY；实际支付仍取决于 Adyen 开通范围。

响应含 `id`、`order_no`、`status` 和 `pay_url`。收款链接必须保持完整，链接中的随机令牌是访问凭据。

## 查询与退款

- GET /api/v1/orders/{订单号或内部订单 ID}
- POST /api/v1/orders/{订单号或内部订单 ID}/sync：主动查询渠道结果。
- POST /api/v1/orders/{订单号或内部订单 ID}/refunds，正文 `{"amount":100}`。
- GET /api/v1/refunds/{退款 ID}

退款并发请求会锁定订单，处理中退款也占用余额。渠道超时的退款保留为 pending，不自动重复提交；需核查原退款结果。

## 状态通知

服务器配置 BUSINESS_NOTIFY_URL 后发送 HTTPS POST；每次状态变化先写入数据库通知表，然后重试投递。

请求头：X-Notify-ID、X-Notify-Timestamp、X-Notify-Signature。

事件 `order.updated` 通知订单状态变化；`refund.updated` 通知退款结果。

签名为 HMAC-SHA256(NOTIFY_SECRET, timestamp + "." + 原始请求正文)，输出十六进制。接收方验证签名、时间窗口并按 X-Notify-ID 去重，成功持久化后返回 2xx。

`authorized` 仅表示授权，`paid` 表示渠道支付成功，不代表银行账户结算到账。