README

欢迎使用 Alipay Easy SDK for PHP 。

Alipay Esay SDK for PHP让您不用复杂编程即可访支付宝开放平台开放的各项常用能力，SDK可以自动帮您满足能力调用过程中所需的证书校验、加签、验签、发送HTTP请求等非功能性要求。

下面向您介绍Alipay Easy SDK for PHP 的基本设计理念和使用方法。

CHANGELOG

2022-04-20 Version: 2.2.4

增加对小程序my.getPhoneNumber返回内容进行验签的方法

    if (!Factory::util()->generic()->verify($response)) {
        return ['code' => 40003, 'msg' => '验签失败'];
    }

设计理念

不同于原有的Alipay SDK通用而全面的设计理念，Alipay Easy SDK对开放能力的API进行了更加贴近高频场景的精心设计与裁剪，简化了服务端调用方式，让调用API像使用语言内置的函数一样简便。

Alipay Easy SDK提供了与能力地图相对应的代码组织结构，让开发者可以快速找到不同能力对应的API。

Alipay Easy SDK主要目标是提升开发者在服务端集成支付宝开放平台开放的各类核心能力的效率。

环境要求

Alipay Easy SDK for PHP 需要配合PHP 7.0或其以上版本。
使用 Alipay Easy SDK for PHP 之前，您需要先前往支付宝开发平台-开发者中心完成开发者接入的一些准备工作，包括创建应用、为应用添加功能包、设置应用的接口加签方式等。
准备工作完成后，注意保存如下信息，后续将作为使用SDK的输入。

加签模式为公钥证书模式时（推荐）

AppId、应用的私钥、应用公钥证书文件、支付宝公钥证书文件、支付宝根证书文件

加签模式为公钥模式时

AppId、应用的私钥、支付宝公钥

安装依赖

通过Composer在线安装依赖（推荐）

composer require evit/php-alipaysdk-easysdk

本地手动集成依赖（适用于自己修改源码后的本地重新打包安装）

本机安装配置Composer工具。
在本README.md所在目录下，执行composer install，下载SDK依赖。
依赖文件会下载到vendor目录下。

快速使用

以下这段代码示例向您展示了使用Alipay Easy SDK for PHP调用一个API的3个主要步骤：

设置参数（全局只需设置一次）。
发起API调用。
处理响应或异常。

<?php

require 'vendor/autoload.php';
use Alipay\EasySDK\Kernel\Factory;
use Alipay\EasySDK\Kernel\Util\ResponseChecker;
use Alipay\EasySDK\Kernel\Config;

//1. 设置参数（全局只需设置一次）
Factory::setOptions(getOptions());

try {
    //2. 发起API调用（以支付能力下的统一收单交易创建接口为例）
    $result = Factory::payment()->common()->create("iPhone6 16G", "20200326235526001", "88.88", "2088002656718920");
    $responseChecker = new ResponseChecker();
    //3. 处理响应或异常
    if ($responseChecker->success($result)) {
        echo "调用成功". PHP_EOL;
    } else {
        echo "调用失败，原因：". $result->msg."，".$result->subMsg.PHP_EOL;
    }
} catch (Exception $e) {
    echo "调用失败，". $e->getMessage(). PHP_EOL;;
}

function getOptions()
{
    $options = new Config();
    $options->protocol = 'https';
    $options->gatewayHost = 'openapi.alipay.com';
    $options->signType = 'RSA2';
    
    $options->appId = '<-- 请填写您的AppId，例如：2019022663440152 -->';
    
    // 为避免私钥随源码泄露，推荐从文件中读取私钥字符串而不是写入源码中
    $options->merchantPrivateKey = '<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->';
    
    $options->alipayCertPath = '<-- 请填写您的支付宝公钥证书文件路径，例如：/foo/alipayCertPublicKey_RSA2.crt -->';
    $options->alipayRootCertPath = '<-- 请填写您的支付宝根证书文件路径，例如：/foo/alipayRootCert.crt" -->';
    $options->merchantCertPath = '<-- 请填写您的应用公钥证书文件路径，例如：/foo/appCertPublicKey_2019051064521003.crt -->';
    
    //注：如果采用非证书模式，则无需赋值上面的三个证书路径，改为赋值如下的支付宝公钥字符串即可
    // $options->alipayPublicKey = '<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->';

    //可设置异步通知接收服务地址（可选）
    $options->notifyUrl = "<-- 请填写您的支付类接口异步通知接收服务地址，例如：https://www.test.com/callback -->";
    
    //可设置AES密钥，调用AES加解密相关接口时需要（可选）
    $options->encryptKey = "<-- 请填写您的AES密钥，例如：aa4BtZ4tspm2wnXLb1ThQA== -->";



    return $options;
}

扩展调用

ISV代调用

Factory::payment()->faceToFace()
    // 调用agent扩展方法，设置app_auth_token，完成ISV代调用
    ->agent("ca34ea491e7146cc87d25fca24c4cD11")
    ->preCreate("Apple iPhone11 128G", "2234567890", "5799.00");

设置独立的异步通知地址

Factory::payment()->faceToFace()
    // 调用asyncNotify扩展方法，可以为每此API调用，设置独立的异步通知地址
    // 此处设置的异步通知地址的优先级高于全局Config中配置的异步通知地址
    ->asyncNotify("https://www.test.com/callback")
    ->preCreate("Apple iPhone11 128G", "2234567890", "5799.00");

设置可选业务参数

$goodDetail = array(
            "goods_id" => "apple-01",
            "goods_name" => "iPhone6 16G",
            "quantity" => 1,
            "price" => "5799"
        );
        $goodsDetail[0] = $goodDetail;

Factory::payment()->faceToFace()
    // 调用optional扩展方法，完成可选业务参数（biz_content下的可选字段）的设置
    ->optional("seller_id", "2088102146225135")
    ->optional("discountable_amount", "8.88")
    ->optional("goods_detail", $goodsDetail)
    ->preCreate("Apple iPhone11 128G", "2234567890", "5799.00");


$optionalArgs = array(
            "timeout_express" => "10m",
            "body" => "Iphone6 16G"
        );

Factory::payment()->faceToFace()
    // 也可以调用batchOptional扩展方法，批量设置可选业务参数（biz_content下的可选字段）
    ->batchOptional($optionalArgs)
    ->preCreate("Apple iPhone11 128G", "2234567890", "5799.00");

多种扩展灵活组合

// 多种扩展方式可灵活组装（对扩展方法的调用顺序没有要求）
Factory::payment()->faceToFace()
    ->agent("ca34ea491e7146cc87d25fca24c4cD11")
    ->asyncNotify("https://www.test.com/callback")
    ->optional("seller_id", "2088102146225135")
    ->preCreate("Apple iPhone11 128G", "2234567890", "5799.00");

API组织规范

在Alipay Easy SDK中，API的引用路径与能力地图的组织层次一致，遵循如下规范

Factory::能力名称()->场景名称()->接口方法名称( ... )

比如，如果您想要使用能力地图中营销能力下的模板消息场景中的小程序发送模板消息，只需按如下形式编写调用代码即可（不同编程语言的连接符号可能不同）。

Factory::marketing()->templateMessage()->send( ... )

其中，接口方法名称通常是对其依赖的OpenAPI功能的一个最简概况，接口方法的出入参与OpenAPI中同名参数含义一致，可参照OpenAPI相关参数的使用说明。

Alipay Easy SDK将致力于保持良好的API命名，以符合开发者的编程直觉。

已支持的API列表

注：更多高频场景的API持续更新中，敬请期待。

文档

API Doc

Alipay Easy SDK

evit / php-alipaysdk-easysdk

Maintainers

Details