README

现在支付 PHP SDK，封装统一下单（JSAPI/APP/H5/小程序/聚合码）、订单查询、退款、撤销、退款/撤销查询、回调验签和前端表单字段生成。

环境要求

• PHP 7.3+
• ext-curl（默认 CurlTransport 基于 cURL 扩展；也可以自行实现 HttpTransportInterface 替换）

安装方式

composer require ipaynow/ipaynow-php-sdk

也可以不使用 Composer，直接注册 PSR-4 自动加载：

spl_autoload_register(function ($class) {
    $prefix = 'Ipaynow\\';
    if (strpos($class, $prefix) !== 0) {
        return;
    }
    $relative = substr($class, strlen($prefix));
    require __DIR__ . '/src/' . str_replace('\\', '/', $relative) . '.php';
});

快速开始

<?php

require __DIR__ . '/vendor/autoload.php';

use Ipaynow\Domain\H5UnifiedOrderParams;
use Ipaynow\IpaynowClient;
use Ipaynow\IpaynowConfig;
use Ipaynow\Request\H5UnifiedOrderRequest;

$config = new IpaynowConfig('appId', 'appKey', 'https://pay.ipaynow.cn');
$client = new IpaynowClient($config);

$params = new H5UnifiedOrderParams(array(
    'mhtOrderNo' => 'ORDER202607030001',
    'mhtOrderName' => '测试订单',
    'mhtOrderDetail' => '测试订单',
    'mhtOrderAmt' => 1,
    'mhtOrderTimeOut' => 120,
    'mhtOrderStartTime' => '20260703120000',
    'notifyUrl' => 'https://example.com/notify',
    'frontNotifyUrl' => 'https://example.com/front',
    'payChannelType' => '12',
    'outputType' => '1',
    'consumerCreateIp' => '127.0.0.1',
));

$response = $client->execute(new H5UnifiedOrderRequest($params));
if ($response->isSuccess()) {
    $tn = $response->getTn();
}

Params 类构造函数接收关联数组：数组的 key 必须是类属性名（未在数组中出现的字段沿用类属性默认值）。

前端 Form 表单提交

需要让浏览器直接向现在支付网关提交表单时，使用 buildFormFields 生成完整请求字段。入参与 execute 一致，SDK 不发起 HTTP 请求。

$fields = $client->buildFormFields(new H5UnifiedOrderRequest($params));

返回字段包含业务参数、公共参数和签名字段，例如：

• funcode
• version
• appId
• mhtCharset
• mhtSignType 或 signType
• mhtSignature

表单提交地址由请求路径决定：

$action = $config->endpoint((new H5UnifiedOrderRequest($params))->path());

支持接口

退款、退款查询、撤销、撤销查询请求会分别 POST 到独立路径（/refund/refundOrder、/refund/cancelOrder），而不是统一下单和订单查询使用的根路径 /，路径由每个 Request 内部决定，调用方无需关心。

响应判断

IpaynowResponse::success() 是 isSuccess() 的别名，各操作按以下规则判断成功：

• 统一下单（JSAPI/APP/H5/小程序/聚合码）、订单查询：responseCode === 'A001'（继承自 IpaynowResponse 默认实现）。
• 退款、退款查询、撤销、撤销查询：responseCode === 'R000'（RefundResponse/RefundQueryResponse/ReverseResponse/ReverseQueryResponse 各自覆盖 isSuccess()）。
• 支付结果回调 PaymentNotifyResponse：transStatus === 'A001'。
• 退款结果回调 RefundNotifyResponse：tradeStatus === 'A001'。

也可以直接读取原始字段：

$code = $response->code();       // responseCode
$message = $response->message(); // responseMsg
$rawBody = $response->rawBody(); // 原始表单串
$fields = $response->fields();   // 全部字段
$value = $response->get('nowPayOrderNo');

统一下单响应（UnifiedOrderResponse 及其子类）额外提供：

$tn = $response->getTn();                    // 支付要素，兼容大写 TN 字段回退
$orderNo = $response->getNowPayOrderNo();    // 现在支付流水号

订单查询响应 OrderQueryResponse 额外提供 getTransStatus()、getNowPayOrderNo()、getPayTime()、getChannelOrderNo()。

扩展字段

参数对象构造时可传入 extraParams 数组，用于透传 SDK 未显式声明的业务字段：

$params = new H5UnifiedOrderParams(array(
    'mhtOrderNo' => 'O1',
    'mhtOrderAmt' => 1,
    'extraParams' => array('customField' => 'v1'),
));

extraParams 在命名字段之后合并进最终请求参数，但不能覆盖 SDK 保留字段，否则 toMap() 会抛出 InvalidArgumentException。保留字段：

• funcode
• version
• appId
• mhtCharset
• mhtSignType
• signType
• mhtSignature
• signature

回调验签

use Ipaynow\Notify\NotifyAck;
use Ipaynow\Notify\NotifyParser;

$notify = NotifyParser::parsePayment($body, $appKey);
if ($notify->isSuccess()) {
    echo NotifyAck::success(); // success=Y
} else {
    echo NotifyAck::fail();    // success=N
}

退款回调：

$notify = NotifyParser::parseRefund($body, $appKey);

验签失败时 NotifyParser::parsePayment / parseRefund 会抛出 IpaynowException（错误码 IpaynowErrorCode::SIGN_ERROR）。

错误处理

SDK 统一抛出 Ipaynow\IpaynowException，通过 getErrorCode() 区分具体失败类型，无需解析异常消息：

use Ipaynow\IpaynowErrorCode;
use Ipaynow\IpaynowException;

try {
    $response = $client->execute(new H5UnifiedOrderRequest($params));
} catch (IpaynowException $e) {
    switch ($e->getErrorCode()) {
        case IpaynowErrorCode::CONNECT_TIMEOUT:
            // 建连超时
            break;
        case IpaynowErrorCode::SOCKET_TIMEOUT:
            // 读超时
            break;
        case IpaynowErrorCode::HTTP_EXCEPTION:
            // 非 2xx 响应，消息中含状态码与响应体
            break;
        case IpaynowErrorCode::SIGN_ERROR:
            // 响应或回调验签失败
            break;
        case IpaynowErrorCode::SYSTEM_ERROR:
            // SDK 内部错误（如响应类定义不合法）
            break;
    }
}

错误码表：