Camera360 Paygw Server SDK For PHP

PGWireless Paygw Server SDK Library For PHP

需求背景

由于全平台的产品线丰富，各应用都有支付的需求，而支付涉及一系列敏感密钥和流程，如支付宝、微信密钥key，支付创建订单、退款、查询订单、转账、对账、财务统计等。为了统一管理支付的所有密钥，节约其他应用程序开发时间及成本，有必要在平台内建立和完善支付网关或者支付中心应用。

安装INSTALL SDK

编辑composer.json安装

    {
        "name": "项目名",
        "description": "项目描述",
        "keywords": [
            "paygw"
        ],
        "homepage": "your homepage",
        "type": "project",
        "license": "BSD-3-Clause",
        "minimum-stability": "stable",
        "repositories": {
            "0": {
                "type": "vcs",
                "url": "https://github.com/PGWireless/php-paygw-server-sdk"
            },
            "packagist": {
                "type": "composer",
                "url": "https://packagist.phpcomposer.com"
            }
        },
        "require": {
            "php": ">=5.4.0",
            "PGWireless/php-paygw-server-sdk": ">=v1.0.5"
        }
        // ...
    }

直接composer require

composer require "PGWireless/php-paygw-server-sdk:*"

SDK快速开始

创建支付订单示例

<?php
$pay = new \PG\paySDK\Pay(12, 'sandbox', 'RSA私钥');
$payLoad = [
    'biz_id'        => 1, // 商户ID
    'way'           => 101, // 支付方式
    'currency'      => 'CNY', // 货币类型
    'out_trade_no'  => '2016052523310222327', // 商户订单号
    'subject'       => 'Camera360商城订单', // 订单标题
    'body'          => '超级可爱的大白', // 订单正文
    'total_fee'     => 99900, // 总共的费用
    'expire_second' => 3600, // 支付的有效时间
    'user_id'       => '2323232', // 用户ID,可自定义,但不能为空
    'user_name'     => '长风', // 用户名,可自定义,但不能为空
    'client_ip'     => '129.33.56.21', // 用户支付的IP
];

var_dump($pay->create($payLoad));

输出:

array(2) {
  ["sdk"]=>
  array(1) {
    ["order_info"]=>
    string(567) "_input_charset="utf-8"&body="超级可爱的大白"&it_b_pay="60m"&notify_url="https%3A%2F%2Fpaygw-qa.camera360.com%2Fapi%2Fnotify%2Falipay-app-sdk-pay-async-callback"&out_trade_no="pp_12_2016052523310222327"&partner="xxx"&payment_type="1"&seller_id="xxx"&service="mobile.securitypay.pay"&subject="Camera360商城订单"&total_fee="999.00"&sign="m2FPk16N4ZKyYyes65IFOt9cInYjR6IoN3GRLUhIYk6PmM0djmI63i1HGt0ICyVyKAnEQhx%2FBaTFeTL7%2FE6bNqvLAXvGYLYm49gEpl0VKLpW8NZft7CacfGrxYoiwoEEOBBJ94zL112Fn0SfIHZSUqPSttx0yPNdqfAPXeaaYZo%3D"&sign_type="RSA""
  }
  ["trade"]=>
  array(10) {
    ["out_trade_no"]=>
    string(19) "2016052523310222327"
    ["way"]=>
    string(3) "101"
    ["total_fee"]=>
    int(99900)
    ["subject"]=>
    string(21) "Camera360商城订单"
    ["body"]=>
    string(21) "超级可爱的大白"
    ["expire_second"]=>
    int(3600)
    ["currency"]=>
    string(3) "CNY"
    ["create_time"]=>
    string(19) "2016-05-26 00:47:21"
    ["pp_sign"]=>
    string(172) "t7SrQJkMu87Ws33ebgEzQ/g5Bg+zkRff5fCvbF4lFIx9y2Ux4ukbYeXzAzUGnaR5r3dETOInbiGOOkvO8V7F5lVBsx9yYNS6wzteMe+vY0PfvcYNIs9ENlVS5VbZEFTajSUqeZs9EYqG8431BiNz8az767R+8LAogq2Fvcr5ZIg="
    ["pp_sign_type"]=>
    string(3) "RSA"
  }
}

查询订单支付状态示例

<?php
    $pay = new \PG\paySDK\Pay(12, 'sandbox', 'RSA私钥');
    $payLoad = [
        'way'           => 201, // 支付方式
        'out_trade_no'  => '20160406145992887952699803', // 商户订单号
    ];

    var_dump($pay->query($payLoad));

输出:

array(10) {
  ["trade_status"]=>
  int(201)
  ["refund_status"]=>
  int(801)
  ["way"]=>
  int(201)
  ["biz_id"]=>
  string(2) "12"
  ["out_trade_no"]=>
  string(26) "20160406145992887952699803"
  ["trade_no"]=>
  string(28) "4009662001201604064597093541"
  ["total_fee"]=>
  string(1) "1"
  ["currency"]=>
  string(3) "CNY"
  ["pp_sign"]=>
  string(172) "FfzJugWOuRmZGNQKo3ervbA7yKbjuTZUYlS+6zn7WM+B5SPdNh1R4Nqjj+i1kpQ+oa+m5TOEGjnxqjkcJYD3Ou7r2E+UjdlnrxwhyXpBZFWWmR4VoQ82Zi0wIKQMkzx7CMGDhViVISp4Vhjl5fXJW3E7yAH0q/XJSgzNGyVDavs="
  ["pp_sign_type"]=>
  string(3) "RSA"
}

订单退款示例

<?php
    $refund = new \PG\paySDK\Refund(12, 'sandbox', 'RSA私钥');
    $post = [
        'way'           => '101',
        'out_trade_no'  => '20160406145992887952699803',
        'out_refund_no' => '30160406145992887952699804',
        'reason'        => '颜色款式不喜欢',
        'total_fee'     => 100,
        'refund_fee'    => 80,
        'user_id'       => '2323232',
        'user_name'     => '长风',
    ];

    $refundParams = $refund->create($post);
    var_dump($refundParams);

处理支付异步通知示例

<?php
    $notify = new \PG\paySDK\Notify(12, 'sandbox', 'RSA私钥');
    $notify->setNotifyMessage($_POST);
    var_dump($notify->isPaySuccess());

处理退款异步通知示例

<?php
    $notify = new \PG\paySDK\Notify(12, 'sandbox', 'RSA私钥');
    $notify->setNotifyMessage($_POST);
    var_dump($notify->isRefundSuccess());

商户订单列表示例

<?php
    $pay = new \PG\paySDK\Pay(12, 'sandbox', 'RSA私钥');
    $payLoad = [
        'user_id' => 'xxxx', // 用户ID
        'num'     => 2, // 注意默认为20条
    ];

    var_dump($pay->lists($payLoad));

输出:

{
    "errno": 0,
    "message": "success",
    "data": {
        "list": [
            {
                "biz_id": "12",
                "way": 103,
                "out_trade_no": "146470730945898007",
                "subject": "Camera360的心意",
                "body": "Camera360支付中心",
                "currency": "CNY",
                "trade_no": null,
                "pay_time": null,
                "total_fee": "1",
                "trade_status": 101,
                "user_id": "12",
                "user_name": "12"
            },
            {
                "biz_id": "12",
                "way": 103,
                "out_trade_no": "146470728594944092",
                "subject": "Camera360的心意",
                "body": "Camera360支付中心",
                "currency": "CNY",
                "trade_no": null,
                "pay_time": null,
                "total_fee": "1",
                "trade_status": 101,
                "user_id": "12",
                "user_name": "12"
            }
        ],
        "page": 1,
        "num": 20,
        "total": "386",
        "pp_sign": "Rt6gXg8WRyKALW75TLgdkJvd6pndc9Mk5P7Rv3F6CpODkEK5UHqS0eZr49UXzZI2GdUdTbuTKxxDoeifnC3GxkP9nKKpjUZjmhPFUDEfussExrZmg60MYbScF65VOCweWZKgaHw0caPWd84+Dna4sbiMbDw2QwybJHZa12QxFlk=",
        "pp_sign_type": "RSA"
    }
}

整合Camera360支付交易流程

角色说明

app

业务产品客户端,是指待整合Camera360支付中心的产品app客户端

app server

业务产品服务器端,是指待整合Camera360支付中心的产品server端

paygw

Camera360支付中心服务器端

app pay sdk

Camera360支付中心客户端SDK,包括安卓和IOS

支付渠道

Camera360支付中心所支持的所有第三方支付渠道

app-server和paygw系统交互

协议

HTTPS POST

数据格式

JSON

签名

待签名数据集

待签名数据集是一个键值对集合

待签名字符串生成方式

由待签名数据集的键值对，按照key=value的形式拼接，然后按照字母序排序成一个字符串数组，用字符'&'来连接这个数组，得到的字符串作为待签名字符串。

RSA签名方式

签名方式：得到待签名字符串后，用私钥签名，得到的结果就是签名结果。

验签方式：得到待签名字符串后，用公钥验证给出的签名是否正确。

签名使用

应用场景	签名方	验签方	签名方式	待签名数据集	验证结果	签名数据	验签数据
api/pay/create请求参数防伪	其他应用	paygw	RSA	请求的POST参数中除pp_sign和pp_sign_type之外的所有参数	pp_sign	其他应用私钥	其他应用公钥
api/pay/create返回参数防伪	paygw	其他应用	RSA	返回数据中除pp_sign和pp_sign_type之外的所有参数	pp_sign	paygw支付私钥	paygw支付公钥
api/pay/query请求参数防伪	其他应用	paygw	RSA	请求的POST参数中除pp_sign和pp_sign_type之外的所有参数	pp_sign	其他应用私钥	其他应用公钥
api/pay/query返回参数防伪	paygw	其他应用	RSA	返回数据中除pp_sign和pp_sign_type之外的所有参数	pp_sign	paygw支付私钥	paygw支付公钥
api/refund/create请求参数防伪	其他应用	paygw	RSA	请求的POST参数中除pp_sign和pp_sign_type之外的所有参数	pp_sign	其他应用私钥	其他应用公钥
api/refund/create返回参数防伪	paygw	其他应用	RSA	返回数据中除pp_sign和pp_sign_type之外的所有参数	pp_sign	paygw支付私钥	paygw支付公钥
api/pay/notify返回参数防伪	paygw	其他应用	RSA	返回数据中除pp_sign和pp_sign_type之外的所有参数	pp_sign	paygw支付私钥	paygw支付公钥

Paygw公钥

生成公私钥

安装openssl

生成RSA私钥

$ genrsa -out rsa_private_key.pem 1024

生成RSA公钥

$ rsa -in rsa_private_key.pem -pubout -out rsa_public_key.pem

PHP语言签名示例代码

<?php
    /**
     * 验证RSA签名（防伪）
     *
     * @param array $data 请求传递的数据
     * @param string $paygwPublicKey Camera360支付网关公钥
     * @return boolean
     */
    function verifyRSASign(array $data, $paygwPublicKey)
    {
        if (empty($data['pp_sign'])) {
            return 0;
        }

        $sign = $data['pp_sign'];
        unset($data['pp_sign']);
        unset($data['pp_sign_type']);
        ksort($data);

        $message = '';
        foreach ($data as $key => $value) {
            $message .= $key . '=' . $value . '&';
        }
        $message     = substr($message, 0, -1);
        $publicKeyId = openssl_pkey_get_public($paygwPublicKey);
        $result      = openssl_verify($message, base64_decode($sign), $publicKeyId);
        openssl_free_key($publicKeyId);

        return $result;
    }

    /**
     * RSA签名数据
     *
     * @param array $data 待签名数据
     * @param string $bizPrivateKey 商户公钥
     * @return string
     */
    function RSASign(array $data, $bizPrivateKey)
    {
        ksort($data);

        $message = '';
        foreach ($data as $key => $value) {
            $message .= $key . '=' . $value . '&';
        }

        $message      = substr($message, 0, -1);
        $privateKeyId = openssl_pkey_get_private($bizPrivateKey);
        $signature    = '';
        openssl_sign($message, $signature, $privateKeyId);
        openssl_free_key($privateKeyId);

        return base64_encode($signature);
    }

Camera360支付中心API

支付方式（way）

方式	值	支持货币
支付宝移动快捷支付	101	CNY
支付宝手机网站Wap支付	102	CNY
微信APP支付	201	CNY
微信公众号	202	CNY
MOLPOINTS	301	THB,USD
PAYSYBUY	401	THB,USD
PAYPAL	501	CNY,USD,THB,JPY
VISA	601	CNY,USD,THB,JPY
MasterCard	701	CNY,USD,THB,JPY
APPLE STORE应用内支付	801	CNY,USD,THB,JPY
Google Play应用内支付	901	CNY,USD,THB,JPY
2c2p	1001	THB

货币类型（currency）

名称	值
人民币	CNY
美元	USD
泰铢	THB
日元	JPY

商户（biz_id）

通过在Paygw后台添加商户后获取

支付订单状态（trade_status）

状态	值
未支付	101
已支付	201
已支付不可退款	202
交易不存在（第三方支付系统中）	301
未知状态	901

退款订单状态（refund_status）

状态	值
待处理	101
已处理	201
退款失败	301
退款成功	401
有退款进行中	501
无退款	801
未知状态	901

注意：支付宝退款需要批量申请去支付宝执行，银行卡退款成功通知会很慢，1~3天左右，微信零钱支付的的退款结果在同步通知中已更新。

创建支付订单

历史

版本	日期	作者	内容
1	2015-09-12	徐典阳	新增

URL

https://paygw.camera360.com/api/pay/create

参数

字段	含义	说明	类型	是否为空	默认
biz_id	商户ID	见商户（biz_id）	int	否
way	支付方式	见支付方式（way）	int	否
currency	支付货币类型	见货币类型（currency）,如不传递为商户参数配置的值	string	是	CNY
out_trade_no	外部订单号	-	string	否
subject	订单标题	长度限制128字节，不超过42个汉字。	string	否
body	订单正文	长度限制255字节	string	否
total_fee	支付金额	大于0，单位为分	int	否
expire_second	订单过期时间	相对当前时间，单位秒	int	否
user_id	用户ID	-	string	否
user_name	用户名称	-	string	是
client_ip	实际支付IP	-	string	否
openid	微信openid	微信公众号支付时获取的openid，仅在微信公众号支付时传递	string	是
extra	额外参数	如果有渠道特殊参数包含多项json_encode之后传值	string	是
pp_sign	签名	由业务方用私钥加密生成	string	否
pp_sign_type	签名方式	暂时只能为RSA	string	否

其中extra在支付方式为501（paypal）时，可以传递的值为：

    json_encode([
        'shipping_address' => [
            'country_code' => 'TH',
            'province'  => 'ประจวบคีรีขันธ์',
            'city'      => '',
            'town'      => 'หัวหิน',
            'street'    => '',
            'post_code' => '32242',
            'detail'    => 'sfsfsdfsf',
            'phone'     => '028-6762837',
            'mobile'    => '18611423990',
            'receiver'  => '典阳 徐',
        ],
        'web_profile_id' => 'XP-PVD8-TYED-4Z4K-JSHV',
    ]);

其中extra在支付方式为1001（2c2p）时，可以传递的值为：

    json_encode([
        'payment_option' => 'A',
        'language' => 'th',
        'pay_category_id' => 'mall',
    ]);

其中extra在支付方式为301（MOLPOINTS）时，可以传递的值为：

    json_encode([
        'channel' => '12call', 
    ]);

channel可选项为：

Payment channel:

Cash Card

12call :AIS 12call Card
truemoney :Truemoney Card
dtachappy :Dtac Cash Card
molpoints :MOLPoints Card

EQwallet

mpay :mPAY wallet
linepay :LINE Pay
truewallet :Wallet by TrueMoney

Operator Billing

psms : Premium SMS

注意：The PIN or Serial on cash card will represent the price point. You do not need to pass value of parameters "for" and "price". So, the parameters "for" and "price" will be optional for channel=12call|truemoney|dtachappy|molpoints.

字段	含义	说明	类型	是否为空
errno	错误码	见错误码（errno）	int	否
message	错误描述	见错误描述（message）	int	否
data	业务数据	-	int	否

成功时data字段说明

字段	含义	说明	类型	是否为空	默认
sdk	调用支付sdk所需参数	微信包含appid，noncestr，package，partnerid，prepayid，timestamp，sign字段；支付宝移动快捷支付包含order_info，sign，sign_type	string	否
trade	交易相关信息	包含pp_sign，pp_sign_type等等	string	否

注意：支付宝移动快捷方式，服务端拿到返回结构需要将sign,sign_type放入order_info元素中，再返回给客户端唤起支付。

支付异步通知

整合微信/支付宝的等所有第三方的异步通知，合并成同构的异步通知转发给其他应用系统。其他应用系统需要为paygw提供一个处理异步通知的url。在校验过参数后并处理完关键逻辑后，返回success

历史

版本	日期	作者	内容
1	2015-09-12	徐典阳	新增

参数

paygw收到第三方异步通知后，参数都以POST方式传递，参数列表如下：

字段	含义	说明	类型	是否为空	默认
notify_id	通知ID	通知唯一标示	int	否
notify_type	通知类型	支付异步通知：trade_status_sync	string	否
notify_time	通知时间	格式为【yyyy-MM-dd HH:mm:ss】	string	否
biz_id	商户ID	见商户（biz_id）	int	否
way	支付方式	见支付方式（way）	int	否
currency	支付货币类型	见货币类型（currency）,如不传递为商户参数配置的值	string	是	CNY
trade_no	支付流水号	支付宝对应trade_no，微信对应transaction_id	string	是
trade_status	支付订单状态	见支付订单状（trade_status）	string	否
pay_time	支付时间	格式为【yyyy-MM-dd HH:mm:ss】	string	是
out_trade_no	外部订单号	-	string	否
total_fee	支付金额	大于0，单位为分	int	否
user_id	用户ID	-	string	否
user_name	用户名称	-	string	是
pp_sign	签名	由业务方用私钥加密生成	string	否
pp_sign_type	签名方式	暂时只能为RSA	string	否

退款

历史

版本	日期	作者	内容
1	2015-09-12	徐典阳	新增

URL

https://paygw.camera360.com/api/refund/create

参数

字段	含义	说明	类型	是否为空
way	支付方式	见支付方式（way）	int	否
biz_id	商户ID	见商户（biz_id）	int	否
out_trade_no	外部订单号	见支付方式（way）	int	否
out_refund_no	外部退款单号	-	string	否
reason	退款原因	长度限制255字节	string	否
total_fee	支付总金额	大于退款金额，单位为分	int	否
refund_fee	退款金额	大于0，单位为分	int	否
user_id	用户ID	-	string	否
user_name	用户名称	-	string	是
pp_sign	签名	由业务方用私钥加密生成	string	否
pp_sign_type	签名方式	暂时只能为RSA	string	否

字段	含义	说明	类型	是否为空
errno	错误码	见错误码（errno）	int	否
message	错误描述	见错误描述（message）	int	否
data	业务数据	-	int	否