ApiDoc.md · 隐形的稻草人/WechatPayV3

# 本SDK的使用Demo以及回调Demo都在./test目录中，请进行查看
# 此SDK是商户直连版本，不支持服务商模式支付

# 目录解析
    - bin #下载平台证书命令行脚本目录
        - CertificateDownloader.php #下载命令行脚本
        - README.md #命令行脚本使用文档
    - test #测试、案例目录
        - index.php #测试文件
        - config.php #配置文件
        - notify.php #异步回调文件
        - notify_response_demo.php #异步回调文件demo
    - src # 源码
        - Crypto #加密相关文件夹
            - AesEcb.php # AES-256-ECB加解密文件
            - AesGcm.php # AES-256-GCM加解密文件
            - AesInterface.php # AES加解密接口规范
            - Hash.php # Hash加密文件
            - Rsa.php # Rsa加解密问价
        - Exception #异常文件夹
            - InvalidArgymentException.php # Http请求库异常
            - WeChatPayException.php # 微信支付异常
        - Request # 接口请求定义文件夹
            - AbstractBaseRequest.php # 接口定位规范
        - Util # 辅助工具
            - MediaUtil.php # 媒体工具
            - PemUtil.php # 证书管理工具
    - Builder.php # 工厂类,生成Client客户端(对GuzzleHttp\Client的二次封装)
    - BuilderChainable.php # `GuzzleHttp\Client` 接口规范
    - BuilderTrait.php # 工厂类扩展方法
    - ClientDecorator.php # Client客户端类
    - ClientDecoratorInterface.php # Client接口规范
    - ClientJsonTrait.php # 微信响应JSON格式返回值
    - ClientXmlTrait.php # 微信响应JSON格式返回值
    - CommonFunction.php # 全局函数
    - config.php # 配置文件模板
    - Formatter.php # 格式化数据文件
    - Transformer.php # XML格式化数据文件
    - WeChatSdk.php # SDK 入口
    - WeChatTradeService.php # SDK 核心处理服务
    
# WeChatSdk SDK核心类详解
## 接口中的某些参数涉及到多层参数，文档并未展示出，需要的请在官方查看，参数名与官网一致：https://pay.weixin.qq.com/wiki/doc/apiv3/apis/index.shtml
```php
/**
 * WeChatSdk constructor.
 * @param array $config
 */
WeChatPay\WeChatSdk::__construct($config=[]);

/**
 * 设置当前SDK的配置
 * @param array $config
 * @return $this
 */
WeChatPay\WeChatSdk::setConfig(array $config);

/**
 * 扫码支付
 * @param string $outTradeNo 商户订单号
 * @param string $description 商品描述
 * @param array $amount 订单金额 ['total'=>1, 'currency'=>'CNY']
 * @param array $otherParams 其余参数 key为参数名称,value为参数值。剩余参数列表['time_expire','attach','goods_tag','detail','scene_info','settle_info']
 * @return array
 * @throws \Exception
 */
WeChatPay\WeChatSdk::nativePay(string $outTradeNo, string $description, array $amount, array $otherParams = []);

/**
 * JSAPI支付 (小程序、公众号支付)
 * @param string $outTradeNo 商户订单号
 * @param array $payer 支付者信息 ['openid]=>'']
 * @param string $description 商品描述
 * @param array $amount 订单金额 ['total'=>1, 'currency'=>'CNY']
 * @param array $otherParams 其余参数 key为参数名称,value为参数值。剩余参数列表['time_expire','attach','goods_tag','detail','scene_info','settle_info']
 * @return array
 * @throws \Exception
 */
WeChatPay\WeChatSdk::jsapiPay(string $outTradeNo, array $payer, string $description, array $amount, array $otherParams = []);

/**
 * H5支付(WAP支付)
 * @param string $outTradeNo 商户订单号
 * @param string $description 商品描述
 * @param array $amount 订单金额 ['total'=>1, 'currency'=>'CNY']
 * @param array $sceneInfo 场景信息 ['h5_info'=>[], 'store_info'=>[]]
 * @param array $otherParams 其余参数 key为参数名称,value为参数值。剩余参数列表['time_expire','attach','goods_tag','detail','scene_info','settle_info']
 * @return array
 * @throws \Exception
 */
WeChatPay\WeChatSdk::h5Pay(string $outTradeNo, string $description, array $amount, array $sceneInfo, array $otherParams = []);

/**
 * APP支付
 * @param string $outTradeNo 商户订单号
 * @param string $description 商品描述
 * @param array $amount 订单金额 ['total'=>1, 'currency'=>'CNY']
 * @param array $otherParams 其余参数 key为参数名称,value为参数值。剩余参数列表['time_expire','attach','goods_tag','detail','scene_info','settle_info']
 * @return array
 * @throws \Exception
 */
WeChatPay\WeChatSdk::appPay(string $outTradeNo, string $description, array $amount, array $otherParams = []);

/**
 * 微信支付订单号查询
 * @param string $transactionId 微信支付订单号
 * @return array
 */
WeChatPay\WeChatSdk::transactionIdQuery(string $transactionId);

/**
 * 商户订单号查询
 * @param string $outTradeNo 商户订单号
 * @return array
 */
WeChatPay\WeChatSdk::outTradeNoQuery(string $outTradeNo);

/**
 * 关闭订单API
 * @param string $outTradeNo 商户订单号
 * @return array
 */
WeChatPay\WeChatSdk::outTradeNoClose(string $outTradeNo);

/**
 * 申请退款API (微信支付订单号进行退款)
 * @param string $transactionId 微信支付订单号
 * @param string $outRefundNo 商户退款单号
 * @param array $amount 金额信息 ['refund'=>1, 'from'=>[], 'total'=>1, 'currency'=>'CNY']
 * @param array $otherParams 其余参数 key为参数名称,value为参数值。剩余参数列表['reason','funds_account','goods_detail']
 * @return array
 */
WeChatPay\WeChatSdk::transactionIdRefund(string $transactionId, string $outRefundNo, array $amount, array $otherParams = []);

/**
 * 申请退款API (商户订单号进行退款)
 * @param string $outTradeNo 商户订单号
 * @param string $outRefundNo 商户退款单号
 * @param array $amount 金额信息 ['refund'=>1, 'from'=>[], 'total'=>1, 'currency'=>'CNY']
 * @param array $otherParams 其余参数 key为参数名称,value为参数值。剩余参数列表['reason','funds_account','goods_detail']
 * @return array
 */
WeChatPay\WeChatSdk::outTradeNoRefund(string $outTradeNo, string $outRefundNo, array $amount, array $otherParams = []);

/**
 * 查询单笔退款API
 * @param string $outRefundNo 商户退款单号
 * @return array
 */
WeChatPay\WeChatSdk::outRefundNoRefundQuery(string $outRefundNo);

/**
 * 申请交易账单API
 * @param string $billDate 账单日期
 * @return array
 */
WeChatPay\WeChatSdk::tradeBill(string $billDate);

/**
 * 申请资金账单API
 * @param string $billDate 账单日期
 * @return array
 */
WeChatPay\WeChatSdk::fundFlowBill(string $billDate);

/**
 * 下载账单
 * @param string $apiUrl 账单下载地址
 * @return array
 */
WeChatPay\WeChatSdk::downloadBill(string $apiUrl);

/**
 * 生成服务器端API请求签名
 * @param $url 请求地址URL
 * @param $requestType 请求方法GET/POST
 * @param $requestBody 请求体BODY内容，json字符串
 * @param string $timestamp 时间戳
 * @param string $nonce 随机字符串
 * @return array
 */
WeChatPay\WeChatSdk::serviceSign($url, $requestType, $requestBody, $timestamp = "", $nonce = "");

/**
 * 创建客户端调起微信支付签名(小程序、APP支付)
 * @param $prepayId 支付参数
 * @return array
 */
WeChatPay\WeChatSdk::clientOpenWxSign($prepayId);

/**
 * 异步回调验签
 * @param string $body 响应内容体
 * @param string $nonce 随机字符串
 * @param string $serial 平台证书序列号
 * @param string $timestamp 时间戳
 * @param string $signature 签名字符串
 * @return array
 */
WeChatPay\WeChatSdk::notifyVerify(string $body, string $nonce, string $serial, string $timestamp, string $signature);
```

---
## Config.php
```php
<?php
//证书文件根目录
$configCertBasePath = realpath(__DIR__ . '/../cert');
/**
 * This file is pay config,you should
 */
return [
    //商户号
    'mchid' =>  '8888888888',
    //商户证书序列号
    'serial'    =>  'SH88888888888888888888888888888',
    //商户私钥
    'privateKey'    =>  \WeChatPay\Util\PemUtil::loadPrivateKey($configCertBasePath . '/apiclient_key.pem') ,
    //[$serial => $certificate] 注意这里是平台证书，可以有多个
    'certs'     =>  [
        'PT88888888888888888888888888888'  => \WeChatPay\Util\PemUtil::loadCertificate($configCertBasePath . '/wechatpay_PT88888888888888888888888888888.pem')
    ],
    //ApiV3Key 平台API V3 秘钥
    'apiV3Key'  =>  '',
    //微信分配的公众账号ID（企业号corpid即为此appId）必填
    'app_id' =>  '',
    //异步回调地址
    'notify_url'	=>	'',
    //退款通知地址
    'refund_notify_url'	=>	'',
    //网站地址
    'wap_url'		=>	'',
    //网站名称
    'wap_name'		=>	'',
];
```

## Demo
```php
<?php
require_once "../vendor/autoload.php";
$config = require_once "./config.php";

$sdk = new \WeChatPay\WeChatSdk($config);
//扫码支付
$info = $sdk->nativePay('native20220315171122', 'Scarecrow测试商品', ['total'=>1], ['attach'=>'12345678987654321']);
var_dump($info);

//JSAPI支付
$openId = 'oUfEI0YgmswunUTYXZ50ElzDm7sg';
$info = $sdk->jsapiPay('native20220315171114', ['openid'=>$openId],'Scarecrow 小程序测试商品', ['total'=>1], ['attach'=>'987654321']);
var_dump($info);
$prepay_id = json_decode($info['data'], true)['prepay_id'];

//H5支付
$info = $sdk->h5Pay('native20220315171115','Scarecrow H5测试商品',['total'=>1],[
    'payer_client_ip'   =>  '14.108.212.144',
    'h5_info'           =>  [
        'type'          =>  'Wap',
        'app_name'      =>  '稻草人的应用',
        'app_url'       =>  'http://www.scarecrow.top'
    ]
], ['attach'=>'987654321']);
var_dump($info);

//APP支付
$info = $sdk->appPay('native20220315171117', 'Scarecrow APP测试商品', ['total'=>1], ['attach'=>'987654321']);
var_dump($info);

//微信支付订单号查询
$info = $sdk->transactionIdQuery('4200001314202203158581938526');
var_dump($info);

//商户订单号查询
$info = $sdk->outTradeNoQuery('native20220315171111');
var_dump($info);

//关闭订单API
$info = $sdk->outTradeNoClose('native20220315171107');
var_dump($info);

//申请退款API 微信支付订单号
$transactionId = '4200001303202203171607847522';
$outRefundNo = 'TK20220317170001';
$info = $sdk->transactionIdRefund($transactionId, $outRefundNo, ['refund'=>1, 'total'=>1, 'currency'=>'CNY'], ['reason'=>'Scarecrow 测试退款']);
var_dump($info);

//申请退款API 商户订单号
$outRefundNo = '20220317170015';
$info = $sdk->outTradeNoRefund('native20220315171122',$outRefundNo, ['refund'=>1, 'total'=>1, 'currency'=>'CNY'], ['reason'=>'Scarecrow 测试退款']);
var_dump($info);

//查询单笔退款AP
$outRefundNo = 'TK20220317170001';
$info = $sdk->OutRefundNoRefundQuery($outRefundNo);
var_dump($info);

//申请下载账单
$info = $sdk->tradeBill("2022-03-17");
if ($info['code'] == WX_RETURN_SUCCESS) {
    $downloadFile = json_decode($info['data'], true)['download_url'];
    $info = $sdk->downloadBill($downloadFile);
    if ($info['code'] == WX_RETURN_SUCCESS) {
        file_put_contents('./bill.csv', $info['data']);
    }
    var_dump("Download success.");
} else {
    var_dump("Download fail." . $info['msg']);
}

//申请资金账单下载
$info = $sdk->fundFlowBill("2022-03-17");
if ($info['code'] == WX_RETURN_SUCCESS) {
    $downloadFile = json_decode($info['data'], true)['download_url'];
    $info = $sdk->downloadBill($downloadFile);
    if ($info['code'] == WX_RETURN_SUCCESS) {
        file_put_contents('./bill.csv', $info['data']);
    }
    var_dump("Download success.");
} else {
    var_dump("Download fail." . $info['msg']);
}

//小程序调起签名
$prepay_id = 'wx21122808210882415bfc9d32b7f47d0000';
$sign = $sdk->miniPaySign($prepay_id);
var_dump($sign);

//异步回调签名验证
$info = $sdk->notifyVerify('12312', '3123123','461892B4971829C59C1A7CA44F4064B771532E5F', '1647849555', '312313123');
var_dump($info);

```

## 异步回调基础模板
```php
<?php
use WeChatPay\Crypto\Rsa;
use WeChatPay\Crypto\AesGcm;
use WeChatPay\Formatter;
require_once "../vendor/autoload.php";
$config = require_once "./config.php";

$headerInfo = getallheaders();
$inWechatpaySignature = $headerInfo['Wechatpay-Signature'] ?? "";// 请求头中的Wechatpay-Signature
$inWechatpayTimestamp = $headerInfo['Wechatpay-Timestamp'] ?? "";// 请求头中的Wechatpay-Timestamp
$inWechatpaySerial = $headerInfo['Wechatpay-Serial'] ?? "";// 请求头中的Wechatpay-Serial
$inWechatpayNonce = $headerInfo['Wechatpay-Nonce'] ?? "";// 请求头中的Wechatpay-Nonce
$inBody = file_get_contents('php://input');// 请根据实际情况获取，例如: file_get_contents('php://input');
$inBodyArray = (array)json_decode($inBody, true);

//\WeChatPay\AddLog(['Signature'=>$inWechatpaySignature, 'Timestamp'=>$inWechatpayTimestamp, 'Serial'=>$inWechatpaySerial, 'Nonce'=>$inWechatpayNonce, 'body'=>$inBodyArray]);

// 检查通知时间偏移量，允许5分钟之内的偏移
$timeOffsetStatus = 300 >= abs(Formatter::timestamp() - (int)$inWechatpayTimestamp);
$verifiedStatus = (new \WeChatPay\WeChatSdk($config))->notifyVerify($inBody, $inWechatpayNonce, $inWechatpaySerial, $inWechatpayTimestamp, $inWechatpaySignature);

if ($timeOffsetStatus && $verifiedStatus['code'] == WX_RETURN_SUCCESS) {
    // 转换通知的JSON文本消息为PHP Array数组
    try {
        if (isset($inBodyArray['resource']['ciphertext'])) {
            // 使用PHP7的数据解构语法，从Array中解构并赋值变量
            $ciphertext = $inBodyArray['resource']['ciphertext'];
            $nonce = $inBodyArray['resource']['nonce'];
            $aad = $inBodyArray['resource']['associated_data'];
            // 加密文本消息解密
            $inBodyResource = AesGcm::decrypt($ciphertext, $config['apiV3Key'], $nonce, $aad);
            // 把解密后的文本转换为PHP Array数组
            $inBodyResourceArray = (array)json_decode($inBodyResource, true);
//            \WeChatPay\AddLog(['Resource'=>$inBodyResourceArray]);
        }
    } catch (\Throwable $e) {
//        \WeChatPay\AddLog(['code'=>'FAIL', 'message'=>$e->getMessage()]);
        echo json_encode(['code'=>'FAIL', 'message'=>'失败'], 256);
        die();
    }

// TODO:在这里进行你得数据回调数据处理
//    \WeChatPay\AddLog(['code'=>'SUCCESS', 'message'=>'成功']);

// TODO: 通知应答
    echo json_encode(['code'=>'SUCCESS', 'message'=>'成功'], 256);
    die();
} else {
    //TODO: 应答通知
//    \WeChatPay\AddLog(['code'=>'FAIL', 'message'=>'验签失败']);
    echo json_encode(['code'=>'FAIL', 'message'=>'失败'], 256);
    die();
}
```

隐形的稻草人/WechatPayV3

简介

发行版

贡献者

近期动态