README

Pilipay 是 Pilibaba 支付的简称。此库提供了 Pilipay 的 API（PHP 版本）。

API 参考

首先请快速浏览一下 HTTP API 参考，以熟悉基本业务逻辑。

在 PHP 中使用，非常简单

检查需求

首先，您应该通过 PilipayConfig::check() 检查需求。如果需求未满足，则使用此库时会出现一些错误。示例代码

// check requirements:
if (!PilipayConfig::check($errors)) {
	// prompt errors to the merchant or administractor
	echo "Error: Pilipay requirements is not satisfied: \n";
	echo implode("\n", $errors);
}

目前需要检查以下需求

1. curl 或 fsockopen 来发送请求
2. openssl 来发送 HTTPS 请求

提交订单

1. 需要引入 autoload.php 以自动加载 pilipay 中的类。
2. 通过 $order = new PilipayOrder() 创建订单。
3. 在订单中填写必要字段。
4. 通过 $good = new PilipayGood() 创建商品。
5. 在商品中填写必要字段。
6. 通过 $order->addGood($good); 将商品添加到订单中。
7. 如果有更多商品，重复 4、5 和 6。
8. 通过 echo $order->renderSubmitForm(); die; 提交订单

示例代码

// autoload
require 'path/to/pilipay/autoload.php';

// create an order
$order = new PilipayOrder();
$order->merchantNo = '1231312';  // a number for a merchant from pilibaba
$order->appSecret = 'abcdefg'; // the secret key from pilibaba
$order->currencyType = 'USD'; // indicates the unit of the following orderAmount, shipper, tax and price
$order->orderNo = '1231231231';
$order->orderAmount = '1.23';
$order->pageUrl = 'https://www.example-shop.com/path/to/some/product';
$order->serverUrl = 'https://www.example-shop.com/path/to/paid/callback';
$order->shipper = '1.23';
$order->tax = '1.23';

// create a good 
$good = new PilipayGood();
$good->name = 'Product Name';
$good->pictureUrl = 'https://www.example-shop.com/path/to/product/picture';
$good->price = '1.23';
$good->productUrl = 'https://www.example-shop.com/path/to/product';
$good->productId = '123123';
$good->quantity = 1;
$good->weight = 1.23;
$good->weightUnit = 'kg';

// add the good to order
$order->addGood($good);

// if there are more goods, please add...
//$good  = new PilipayGood();
//...
//$order->addGood($good);

// render submit form, which would auto submit
echo $order->renderSubmitForm();
die;

获取条形码

1. 需要引入 autoload.php 以自动加载 pilipay 中的类。
2. 通过 $order = new PilipayOrder(); 创建订单。
3. 将必要字段填写到订单中。
4. 通过 $barcodePicUrl = $order->getBarcodePicUrl(); 获取条形码图片 URL。

示例代码

// autoload
require 'path/to/pilipay/autoload.php';

// create an order
$order = new PilipayOrder();

// orderNo and merchantNo must be provided:
$order->orderNo = '123123';
$order->merchantNo = '123123';

// get the barcode's picture URL:
$barcodePicUrl = $order->getBarcodePicUrl();

// do whatever you want to with the barcode

更新跟踪号码

1. 需要引入 autoload.php 以自动加载 pilipay 中的类。
2. 通过 $order = new PilipayOrder(); 创建订单。
3. 将必要字段填写到订单中。
4. 通过 $order->updateTrackNo($trackNo); 调用更新。

示例代码

// autoload
require 'path/to/pilipay/autoload.php';

// create an order
$order = new PilipayOrder();

// orderNo and merchantNo must be provided:
$order->orderNo = '123123';
$order->merchantNo = '123123';

// update
$order->updateTrackNo($trackNo); // $trackNo must be the same with the track number on the package when shipping.

处理支付结果

客户付款后，会向 $order->serverUrl 发送请求。为了正确处理此请求，可以使用 PilipayPayResult。它非常简单。所以只需展示示例代码

// autoload
require 'path/to/pilipay/autoload.php';

// create an instance from the request
$payResult = PilipayPayResult::fromRequest();

// verify whether the request is valid:
if (!$payResult->verify($appSecret)){ // $appSecret is exactly the same with $order->appSecret
	// error handling...
	die('Invalid request');
}

// judge whether payment is successfully completed:
if (!$payResult->isSuccess()){
	// deal failure
} else {
	// deal success
}

处理错误

当设置订单或商品的字段、提交订单和更新跟踪号码时，如果遇到错误，将抛出 PilipayError。因此，应使用 try ... catch 块来处理错误。示例代码

try{
	// submit order, update track number...
} catch (PilipayError $e) {
	// deal the error
	// $e->getMessage() will be detailed reason.
}

记录日志

PilipayLogger 提供了可扩展的日志记录。可以使用 PilipayLogger::setHandler() 注入日志处理器。例如，记录到文件

PilipayLogger::instance()->setHandler(function($level, $msg){
	file_put_contents('path/to/pilipay/log/file', sprintf('%s %s: %s'.PHP_EOL, date('Y-m-d H:i:s'), $level, $msg));
});

配置

有一些有用的配置

1. useHttps 定义是否使用 HTTPS - 虽然默认推荐使用 HTTPS，但在某些情况下您可能想要使用 HTTP。
2. useProductionEnv 定义是否使用生产环境。默认值是 true。但在测试时，建议将 useProductionEnv 设置为 false。之后，您不需要实际支付来完成订单。订单将模拟为已付款。

示例代码

// Not recommended: use HTTP interface - maybe openssl on the server cannot work.
PilipayConfig::setUseHttps(false);

// When testing, do not use production environment:
PilipayConfig::setUseProductionEnv(false);

支持

1. 在 github 上提交问题
2. 我们的官方 API 网站
3. 发送电子邮件：developers(AT)pilibaba.com