README

星驿付支付中转接口 PHP SDK，支持微信、支付宝、云闪付等多种支付方式。

目录

• 安装
• 快速开始
• 配置说明
• 方法说明
  • 订单支付
  • 订单查询
  • 订单退款
  • 退款查询
• 参数说明
• 响应说明
• 异常处理
• 完整示例

安装

Composer 安装

composer require oyta/xyfpay

手动安装

将 src 目录复制到您的项目中，并配置自动加载：

{
    "autoload": {
        "psr-4": {
            "Oyta\\Xyfpay\\": "src/"
        }
    }
}

快速开始

<?php
require_once 'vendor/autoload.php';

use Oyta\Xyfpay\Client;

// 初始化客户端
$client = new Client([
    'UseChannel' => 'XYF',        // 星驿付通道
    'PayTerminal' => 'mp',        // 小程序终端
    'PayChannel' => 'WXPAY',      // 微信支付
    'MchId' => 'your_mch_id',     // 商户号
    'AppId' => 'your_app_id',     // 小程序AppId
    'NotifyUrl' => 'https://your-domain.com/notify'  // 异步通知地址
]);

// 发起支付
$response = $client->orderPay([
    'InternalNo' => 'ORDER_' . time(),
    'Amount' => 100.00,
    'OpenId' => 'user_openid',
    'Subject' => '商品标题',
    'Body' => '商品描述'
]);

if ($response->isSuccess()) {
    echo "支付成功！流水号: " . $response->getExternalNo();
}

配置说明

全局配置

可以在初始化时设置全局配置，避免每次调用都传递相同参数：

$client = new Client([
    'UseChannel' => 'XYF',        // 使用通道
    'PayTerminal' => 'mp',        // 支付终端
    'PayChannel' => 'WXPAY',      // 支付方式
    'MchId' => 'your_mch_id',     // 商户号
    'MchKey' => 'your_mch_key',   // 商户密钥
    'AppId' => 'your_app_id',     // AppId
    'AppKey' => 'your_app_key',   // App密钥
    'MchTermNo' => 'term_no',     // 商户终端号
    'NotifyUrl' => 'https://your-domain.com/notify'  // 异步通知地址
]);

通道说明

终端说明

支付方式说明

方法说明

订单支付 (orderPay)

发起支付请求，支持小程序支付、APP支付、付款码支付等多种方式。

调用方法:

$response = $client->orderPay([
    'InternalNo' => 'ORDER_123456',  // 商户订单号（必填）
    'Amount' => 100.00,               // 支付金额（必填）
    'OpenId' => 'user_openid',        // 用户OpenId（JSAPI支付必填）
    'Subject' => '商品标题',
    'Body' => '商品描述',
    'Goods' => '商品明细',
    'Goods_Tag' => '优惠说明',
    'Attach' => '附加信息'
]);

付款码支付示例:

$response = $client->orderPay([
    'PayTerminal' => 'Scan',          // 付款码支付
    'InternalNo' => 'ORDER_123456',
    'Amount' => 100.00,
    'AuthCode' => '134567890123456789',  // 付款码（必填）
    'Latitude' => '22.546',           // 纬度
    'Longitude' => '114.085'          // 经度
]);

订单查询 (orderQuery)

查询订单支付状态。

调用方法:

// 通过商户订单号查询
$response = $client->orderQuery([
    'InternalNo' => 'ORDER_123456'
]);

// 通过支付通道订单号查询
$response = $client->orderQuery([
    'InternalNo' => 'ORDER_123456',
    'ExternalNo' => 'external_order_no'
]);

订单退款 (orderRefund)

对已支付的订单发起退款。

调用方法:

$response = $client->orderRefund([
    'RefundNo' => 'REFUND_123456',     // 退款订单号（必填）
    'RefundAmount' => 50.00,           // 退款金额（必填）
    'InternalNo' => 'ORDER_123456',    // 原支付订单号（必填）
    'ExternalNo' => 'external_order_no', // 原支付流水号（必填）
    'RefundDesc' => '退款原因',        // 退款描述
    'NotifyUrl' => 'https://your-domain.com/refund_notify'  // 退款通知地址
]);

退款查询 (refundQuery)

查询退款状态。

调用方法:

$response = $client->refundQuery([
    'InternalNo' => 'ORDER_123456'  // 商户订单号
]);

参数说明

公共参数

订单支付参数

订单查询参数

订单退款参数

退款查询参数

响应说明

响应字段

响应方法

// 判断交易是否成功
$response->isSuccess();        // State == 1

// 判断交易是否进行中
$response->isProcessing();     // State == 2

// 判断交易是否失败
$response->isFailed();         // State == 0

// 判断是否系统异常
$response->isSystemError();    // State == -1

// 获取响应数据
$response->getState();         // 获取交易状态
$response->getCode();          // 获取状态码
$response->getDesc();          // 获取状态描述
$response->getOpenNo();        // 获取买家账号
$response->getInternalNo();    // 获取商户订单号
$response->getExternalNo();    // 获取支付流水号
$response->getAmount();        // 获取金额
$response->getData();          // 获取完整响应数据

交易状态说明

异常处理

SDK 使用异常机制处理错误，建议使用 try-catch 捕获异常：

use Oyta\Xyfpay\Exception\XyfpayException;

try {
    $response = $client->orderPay([
        'InternalNo' => 'ORDER_123456',
        'Amount' => 100.00
    ]);
    
    if ($response->isSuccess()) {
        // 支付成功处理
        echo "支付成功！";
    } else {
        // 支付失败处理
        echo "支付失败: " . $response->getDesc();
    }
    
} catch (XyfpayException $e) {
    // SDK异常处理
    echo "异常信息: " . $e->getMessage();
    echo "状态码: " . $e->getCode();
    echo "交易状态: " . $e->getState();
    
} catch (\Exception $e) {
    // 其他异常处理
    echo "系统异常: " . $e->getMessage();
}

完整示例

小程序支付示例

<?php
require_once 'vendor/autoload.php';

use Oyta\Xyfpay\Client;
use Oyta\Xyfpay\Exception\XyfpayException;

// 初始化客户端
$client = new Client([
    'UseChannel' => 'XYF',
    'PayTerminal' => 'mp',
    'PayChannel' => 'WXPAY',
    'MchId' => '123456789',
    'AppId' => 'wx1234567890abcdef',
    'NotifyUrl' => 'https://your-domain.com/notify'
]);

try {
    // 发起支付
    $response = $client->orderPay([
        'InternalNo' => 'ORDER_' . time(),
        'Amount' => 0.01,
        'OpenId' => 'oUpF8uMuAJO_M2pxb1QqzN5weqFo',
        'Subject' => '测试商品',
        'Body' => '测试商品描述'
    ]);
    
    if ($response->isSuccess()) {
        $result = [
            'status' => 'success',
            'external_no' => $response->getExternalNo(),
            'amount' => $response->getAmount()
        ];
    } else {
        $result = [
            'status' => 'failed',
            'desc' => $response->getDesc()
        ];
    }
    
    echo json_encode($result, JSON_UNESCAPED_UNICODE);
    
} catch (XyfpayException $e) {
    echo json_encode([
        'status' => 'error',
        'message' => $e->getMessage()
    ], JSON_UNESCAPED_UNICODE);
}

付款码支付示例

<?php
require_once 'vendor/autoload.php';

use Oyta\Xyfpay\Client;

$client = new Client([
    'UseChannel' => 'XYF',
    'PayTerminal' => 'Scan',
    'PayChannel' => 'WXPAY',
    'MchId' => '123456789'
]);

try {
    $response = $client->orderPay([
        'InternalNo' => 'SCAN_' . time(),
        'Amount' => 100.00,
        'AuthCode' => '134567890123456789',  // 用户付款码
        'Latitude' => '22.546',
        'Longitude' => '114.085',
        'Subject' => '扫码支付测试'
    ]);
    
    if ($response->isSuccess()) {
        echo "付款成功！金额: " . $response->getAmount();
    } elseif ($response->isProcessing()) {
        echo "支付处理中，请等待用户输入密码";
    } else {
        echo "付款失败: " . $response->getDesc();
    }
    
} catch (\Exception $e) {
    echo "异常: " . $e->getMessage();
}

订单查询示例

<?php
require_once 'vendor/autoload.php';

use Oyta\Xyfpay\Client;

$client = new Client([
    'UseChannel' => 'XYF',
    'PayTerminal' => 'mp',
    'PayChannel' => 'WXPAY',
    'MchId' => '123456789'
]);

try {
    $response = $client->orderQuery([
        'InternalNo' => 'ORDER_123456'
    ]);
    
    if ($response->isSuccess()) {
        echo "订单已支付";
        echo "流水号: " . $response->getExternalNo();
        echo "金额: " . $response->getAmount();
    } else {
        echo "订单状态: " . $response->getDesc();
    }
    
} catch (\Exception $e) {
    echo "查询失败: " . $e->getMessage();
}

退款示例

<?php
require_once 'vendor/autoload.php';

use Oyta\Xyfpay\Client;

$client = new Client([
    'UseChannel' => 'XYF',
    'PayTerminal' => 'mp',
    'PayChannel' => 'WXPAY',
    'MchId' => '123456789'
]);

try {
    $response = $client->orderRefund([
        'RefundNo' => 'REFUND_' . time(),
        'RefundAmount' => 50.00,
        'InternalNo' => 'ORDER_123456',
        'ExternalNo' => '2020010123456789',
        'RefundDesc' => '用户申请退款'
    ]);
    
    if ($response->isSuccess()) {
        echo "退款成功！";
    } else {
        echo "退款失败: " . $response->getDesc();
    }
    
} catch (\Exception $e) {
    echo "退款异常: " . $e->getMessage();
}

异步通知处理

支付成功后，支付通道会向 NotifyUrl 发送异步通知。以下是处理通知的示例：

<?php
// notify.php - 异步通知处理

// 获取通知数据
$notifyData = file_get_contents('php://input');
$data = json_decode($notifyData, true);

// 验证签名（根据实际需求添加签名验证逻辑）

// 处理业务逻辑
if (isset($data['State']) && $data['State'] == 1) {
    $internalNo = $data['InternalNo'];  // 商户订单号
    $externalNo = $data['ExternalNo'];  // 支付流水号
    $amount = $data['Amount'];          // 支付金额
    
    // 更新订单状态等业务逻辑
    // ...
    
    // 返回成功响应
    echo 'success';
} else {
    echo 'fail';
}

注意事项

1. 金额单位：所有金额单位均为元，支持小数点后两位
2. 订单号唯一：商户订单号（InternalNo）必须唯一，不能重复
3. 退款金额：退款金额不能超过原支付金额
4. 异步通知：建议使用异步通知处理支付结果，不要仅依赖同步返回
5. 安全性：生产环境建议使用 HTTPS，并验证异步通知的签名
6. 超时设置：SDK 默认超时时间为 30 秒，可根据需要修改

技术支持

如有问题，请联系技术支持或查看官方文档。

License

MIT License