# 你好现在支付对接 Skills 使用指引

# 你好现在支付对接 Skills 使用指引

本文面向接入 iPayNow/你好现在支付的开发人员与 Agent，说明如何安装 `ipaynow-payment` Skills，并辅助完成支付接口开发。

接口字段、版本、错误码、SDK API 生产环境，以[你好现在官方文档](https://ipaynowdoc.apifox.cn/)为准；Skills 用于对齐接口报文、签名验签、回调幂等和工程实践，不替代官方文档。

## 一、Skills 技能包下载

当前工作区提供：

[下载 ipaynow-payment.zip](https://drive.weixin.qq.com/s?k=AAkADweDAAcuI7JOxw)

## 二、目录说明

```text
ipaynow-payment/
├── SKILL.md                    # 主规则与任务路由
├── references/
│   ├── reference.md            # 参考资料索引
│   ├── protocol.md             # 公共协议、环境和网关
│   ├── payment.md              # 下单和查单
│   ├── callbacks.md            # 支付/退款回调
│   ├── signing.md              # 签名与验签
│   ├── scenarios.md            # 渠道和场景参数
│   ├── refund.md               # 退款和撤销
│   ├── errors.md               # 状态码和排错
│   ├── sdk.md                 # SDK 使用说明
│   └── reconciliation.md      # 对账
└── scripts/validate.rb         # 结构与敏感信息校验
```

将完整的 `ipaynow-payment` 目录加入 Codex、Cursor 等 Agent 工具的 Skills 目录；不要只复制 `SKILL.md`。

例如 Codex：

```bash
mkdir -p ~/.agents/skills
unzip -q ipaynow-payment.zip -d ~/.agents/skills
ruby ~/.agents/skills/ipaynow-payment/scripts/validate.rb
```

## 三、如何使用

安装后直接用自然语言描述需求，例如：

- 对接你好现在公众号支付；
- 使用官方 SDK 实现 WP001 下单和 N001 回调；
- 排查支付回调验签失败；
- 增加 MQ002 查单兜底。

Agent 应先确认支付场景、接口范围、`outputType`、开发语言/框架、SDK 版本和当前环境，再读取 `references/reference.md` 及相关主题文件。

官方 SDK 优先；只有 SDK 不可用、不兼容或未覆盖接口时，才使用原生 HTTP。Node.js 官方包为 `ipaynow-nodejs-sdk`，其他语言按官方当前文档选择对应 SDK。

## 四、安全约束

- 未明确确认前，只做分析、离线构造、签名校验和 mock，不发送真实支付/退款请求。
- 不在对话、代码、命令行或日志中暴露 `appKey`、RSA 私钥和生产凭证。
- 回调必须验签，并校验应用、订单号、金额和状态；重复通知必须幂等。
- N002 只能用于前端展示，不能单独驱动支付成功、发货或入账。
- `tn` 必须验签后使用；退款必须校验权限、订单归属、可退余额和幂等。
- 真实请求前，Agent 必须展示环境、网关、订单号、金额、接口和外部副作用，等待明确确认。

## 五、官方资料

- [你好现在官方文档](https://ipaynowdoc.apifox.cn/)
- [官方全文索引](https://ipaynowdoc.apifox.cn/llms.txt)
- [服务端 SDK 文档](https://ipaynowdoc.apifox.cn/9135585m0)
- [商户平台](https://mch.ipaynow.cn/login)