Download the PHP package yopay/yopay-php without Composer

YoPay PHP SDK

YoPay PHP SDK 是 Pay Open API 的商户侧 SDK。它负责 Open API 请求签名、POST 加密信封、POST 成功响应验签解密，以及 YoPay 向商户 notify_url 投递的通知验签解密。

SDK 运行于 PHP 8.1+；推荐商户生产环境使用仍在支持周期内的 PHP 8.3+。金额全部使用字符串，不能使用 float。

安装

YoPay PHP SDK 发布在 Packagist。在商户项目目录执行：

生产项目应锁定已验证版本并提交 composer.lock。Composer 会从发布版 dist ZIP 安装 SDK，不需要商户访问开发源码仓库。

配置与下单

BaseURL 只包含协议、域名和可选端口，不要包含 /api/v1/open；openApiPrefix 默认就是 /api/v1/open。

环境变量统一使用 YOPAY_ 前缀：

• YOPAY_BASE_URL
• YOPAY_MCH_ID
• YOPAY_SECRET_KEY
• YOPAY_PLATFORM_PUBLIC_KEY
• YOPAY_MERCHANT_PRIVATE_KEY
• YOPAY_NOTIFY_URL

SDK 只发送 X-Mch-Id、X-Timestamp、X-Nonce、X-Signature 与 X-Request-Id，不会发送 X-Access-Key 或 X-Secret-Key。

这些安全头使用固定七行签名：METHOD、PATH、MCH_ID、TIMESTAMP、NONCE、REQUEST_ID、PAYLOAD_DIGEST。POST 成功响应和商户通知都校验商户号、请求 ID、±5 分钟时间窗、nonce 防重放和签名；成功响应的 X-Request-Id 必须回显本次请求的值。

默认 replay cache 只覆盖当前 PHP 进程。多进程或多实例服务应在 Config 中注入实现 ReplayProtector 的共享原子缓存；协议 nonce 校验不能替代按 trade_no + notify_type 的业务幂等。

业务方法

• order(OrderRequest $request)：POST /pay/order
• refund(RefundRequest $request)：POST /pay/refund
• withdraw(WithdrawRequest $request)：POST /pay/payout
• closeOrder(CloseOrderRequest $request)：POST /pay/close
• queryOrder(QueryOrderRequest $request)：GET /pay/query
• queryWithdraw(QueryWithdrawRequest $request)：GET /pay/withdrawQuery
• bills(BillsRequest $request)：GET /bill/list

POST 会把业务 DTO 加密为仅含 encrypted_key 和 biz_content 的信封，再对信封签名；GET 只签名、不加密。所有公开 DTO 均不包含 provider_id 或内部钱包、路由、数据库 ID。

SDK 不自动重试支付类 POST。商户若要重试，必须围绕自身 merchant_order_no 的幂等语义，在业务层或所注入 HTTP client 层明确控制。

PSR-18、日志与协程

Config 的 httpClient、requestFactory、streamFactory 使用 PSR-18/17/7 接口，logger 使用 PSR-3。默认 HTTP client 是 Guzzle；商户可以注入自身的代理、链路追踪、连接池、熔断或协程客户端。

协程框架应注入其当前运行时已经配置好的 PSR-18 client。SDK 不创建事件循环、不使用全局可变请求状态，也不自行重试，因此每次调用自然运行在调用方的当前协程内。

Swoole 项目还可以显式使用内置适配器（SDK 不强依赖 ext-swoole）：

SwooleCoroutineClient 仅在显式调用时检查 ext-swoole 和当前协程上下文；未安装扩展的普通 PHP、FPM 和其他框架不受影响。

Debug 日志只包含 method、path、request ID、HTTP 状态和耗时，不包含密钥、私钥、完整公钥、业务 JSON、encrypted_key、biz_content 或支付身份字段。

商户通知

通知处理必须传入商户服务实际收到的 URL path 和原始 body，不能传 Open API path，也不能在验签前格式化 JSON。商户自行完成以 trade_no + notify_type 为键的本地幂等处理。

平台只认可 HTTP 200 OK 且 JSON 对象中数值 code 为 0 的回执。HTTP 204、其他 2xx、空 body、非 JSON、字符串 "0" 或非零 code 都会触发重试。

平台每次重试都会使用新的 X-Timestamp、X-Nonce、X-Request-Id 和 X-Signature，密文 body 可以保持不变。

异常

• ConfigException：配置、Base URL、path 或必需密钥无效。
• ApiException：HTTP 2xx 内的 YoPay 业务错误；包含业务 code 与 request ID。
• HttpException：网络异常、非 2xx 或响应体超过限制；包含有限长度 body 与 request ID。
• SignatureException：响应或通知缺失签名、验签失败。
• CryptoException：PEM、RSA-OAEP、AES-GCM、信封或解密 JSON 失败。
• CoroutineException：显式使用 Swoole 适配器但扩展/协程上下文不满足要求。

示例与本地检查

可使用 Docker 执行以下检查：