What Is Pilipay?

Pilipay is short for Pilibaba's payment. This library provides pilipay's API (in PHP).

API Reference

Firstly please take a quick look at the HTTP API reference to get familiar with the basic bussiness logics.

As how to use in PHP, it's pretty simple:

Checking Requirements

First of all, you should check the requirements via PilipayConfig::check(). If requirements is not satisfied, there would be some errors when using this library. Example Code:

// 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);
}

Currently, the following requirements are to be checked:

1. curl or fsockopen to make requests
2. openssl to make HTTPS requests

Submit an order

1. require the autoload.php in order to auto load the classes in pilipay.
2. create an order by $order = new PilipayOrder().
3. fill essential fields in the order.
4. create a good by $good = new PilipayGood().
5. fill essential fields in the good.
6. add good to the order by $order->addGood($good);.
7. if there are more goods, repeate 4, 5, and 6.
8. submit order by echo $order->renderSubmitForm(); die;

Sample code:

// 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;

Get the barcode

1. require the autoload.php in order to auto load the classes in pilipay.
2. create an order by $order = new PilipayOrder();.
3. fill essential fields into the order.
4. get the barcode's picture URL by $barcodePicUrl = $order->getBarcodePicUrl();.

Sample code:

// 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

Update tracking number

1. require the autoload.php in order to auto load the classes in pilipay.
2. create an order by $order = new PilipayOrder();.
3. fill essential fields into the order.
4. invoke update by $order->updateTrackNo($trackNo);.

Sample code:

// 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.

Deal the pay result

After the customer has paid, a request to $order->serverUrl would be sent. In order to properly deal this request, PilipayPayResult can be used. It's pretty simple. So just show the example code:

// 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
}

Handle errors

When setting fields of an order or a good, submiting the order, and updating track number, if an error is encountered, a PilipayError will be thrown. So a try ... catch block should be used to deal errors. Example code:

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

Record logs

PilipayLogger provides a extendable logging. PilipayLogger::setHandler() can be used to inject a logger handler. For example, logging to a file:

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));
});

Configurations

There are some helpful configurations:

1. useHttps defines whether to use HTTPS - although HTTPS is recommend by default, you might want to use HTTP in some circumstances.
2. useProductionEnv defines whether to use the production environment. It's default value is true. But when you are testing, it is recommend to set useProductionEnv to false. After that, you will not need to pay real money to complete an order. Orders will be simulated as if be paid.

Example code:

// 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);

Support

1. Make an issue on github
2. Our official API site
3. Send an email: developers(AT)pilibaba.com