README

Yooer 支付系统的官方 PHP SDK，提供安全便捷的接口接入。本 SDK 封装了签名验证、请求构造及返回值校验等功能，可以帮助开发者快速集成支付能力。

环境要求

• PHP >= 7.2
• guzzlehttp/guzzle ^7.0
• JSON 扩展

安装

使用 Composer 在您的项目中安装此 SDK：

composer require yooer/payment

快速开始

1. 初始化配置与客户端

在使用交易或回调服务前，需先使用您的商户号（merchantId）和密钥（secretKey）初始化配置及客户端。

use Yooer\Payment\Config;
use Yooer\Payment\Client;

// 替换为您在 Yooer 支付后台申请的商户 ID 和 Secret Key
$merchantId = 10000; 
$secretKey = 'your_merchant_secret_key';

$config = new Config($merchantId, $secretKey);

// （可选）自定义请求超时与连接超时时间（单位：秒）
$config->setTimeout(5, 3);

// 创建底层通信客户端，自动处理请求签名及响应验签
$client = new Client($config);

2. 交易服务 (Trade)

Trade 提供了主要的交易接口操作，如创单、交易查询和退款等。

use Yooer\Payment\Services\Trade;
use Yooer\Payment\Exceptions\PaymentException;

$tradeService = new Trade($client);

// =======================
// 2.1 创建订单 (Create)
// =======================
try {
    $createParams = [
        'amount'   => 1000,       // [必选] 订单金额（通常以分为单位）
        'currency' => 'usd',      // [必选] 货币类型，支持: cny, usd, eur, gbp
        'account'  => 'user_888', // [必选] 买家账户标识
        
        // --- 以下为可选参数 ---
        // 'platform' => 'Stripe',// [可选] 支付平台，支持: Stripe 或 UPay（默认 Stripe）
        // 'description'=> 'VIP', // [可选] 订单描述信息
        
        // 当 platform 为 Stripe 时，可使用 method 指定收款方式:
        // (数组格式，支持的所有通道详见官方文档: https://docs.stripe.com/payments/payment-methods)
        // 常用如：
        // ['card']         - 国际主流信用卡/借记卡 (此选项在前端会自动同时支持 Apple Pay 和 Google Pay)
        // ['paypal']       - PayPal (需在 Stripe 后台启用)
        // ['alipay']       - 支付宝国际
        // ['wechat_pay']   - 微信支付国际版
        // ['bancontact']   - 比利时 Bancontact
        // ['klarna']       - 欧洲 Klarna 先买后付 等...
        // 'method'   => ['card', 'paypal', 'alipay', 'wechat_pay'], 
        
        // 当 platform 为 UPay 时，可使用 type 指定加密货币提款网络 (字符串格式，严格区分大小写)，支持：
        // 'USDT-TRC20'       - 基于波场 (Tron) 网络的 USDT
        // 'USDT-ERC20'       - 基于以太坊 (Ethereum) 网络的 USDT
        // 'USDT-Polygon'     - 基于马蹄网络 (Polygon) 的 USDT
        // 'USDT-BSC'         - 基于币安智能链 (BNB Smart Chain) 的 USDT
        // 'USDT-ArbitrumOne' - 基于 Arbitrum One 二层网络的 USDT
        // 'type'     => 'USDT-TRC20',
    ];
    
    $result = $tradeService->create($createParams);
    
    // 打印创单结果（包含会话ID或支付链接等）
    print_r($result);
} catch (PaymentException $e) {
    echo "创单失败: " . $e->getMessage();
}

// =======================
// 2.2 查询订单 (Query)
// =======================
try {
    $queryParams = [
        'tradeId' => 'TR1234567890', // [必选] 创建订单时返回或业务系统产生的交易ID
    ];
    
    $result = $tradeService->query($queryParams);
    print_r($result);
} catch (PaymentException $e) {
    echo "查询订单失败: " . $e->getMessage();
}

// =======================
// 2.3 申请退款 (Refund)
// =======================
try {
    $refundParams = [
        'tradeId' => 'TR1234567890', // [必选] 需退款的交易ID
    ];
    
    $result = $tradeService->refund($refundParams);
    print_r($result);
} catch (PaymentException $e) {
    echo "申请退款失败: " . $e->getMessage();
}

3. 处理异步回调 (Callback)

支付系统在支付成功后会发送异步通知。您可以使用 Callback 服务便捷地进行数据合法性校验防止伪造请求。

use Yooer\Payment\Config;
use Yooer\Payment\Services\Callback;

$config = new Config($merchantId, $secretKey);
$callbackService = new Callback($config);

// 假设 $callbackData 是接收到的异步通知 POST 数据或 JSON 体
$callbackData = [
    'tradeId'   => 'TR1234567890',
    'status'    => 'paid',
    'amount'    => 1000,
    // ...
    'signature' => 'xxx...', // 用于被验证的签名数据
];

if ($callbackService->verifyCallback($callbackData)) {
    // 验证成功，执行发货或其他业务逻辑
    echo "SUCCESS";
} else {
    // 签名异常，拒绝处理
    echo "FAIL";
}

异常捕获

接口请求若发生网络不通、响应签名验证失败（Signature verify failed）或 HTTP 服务端异常时，都将抛出 Yooer\Payment\Exceptions\PaymentException 异常。你可以捕获该异常来获取更多信息。

try {
    // ... 发起请求
} catch (\Yooer\Payment\Exceptions\PaymentException $e) {
    // 错误信息
    echo $e->getMessage();
    
    // 如有需要可获取被拒绝的具体响应体数据
    // $e->getResponseData(); 
}

许可协议

该 SDK 遵守 MIT 开源协议。