pilibaba / pilipay-php
Pilipay is short for Pilibaba's payment. This library provides pilipay's API (in PHP).
Installs: 19 628
Dependents: 0
Suggesters: 0
Security: 0
Stars: 1
Watchers: 3
Forks: 0
Open Issues: 2
Requires
- php: >=5.3.0
This package is not auto-updated.
Last update: 2024-09-14 19:42:07 UTC
README
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:
curl
orfsockopen
to make requestsopenssl
to make HTTPS requests
Submit an order
- require the
autoload.php
in order to auto load the classes in pilipay. - create an order by
$order = new PilipayOrder()
. - fill essential fields in the order.
- create a good by
$good = new PilipayGood()
. - fill essential fields in the good.
- add good to the order by
$order->addGood($good);
. - if there are more goods, repeate 4, 5, and 6.
- 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
- require the
autoload.php
in order to auto load the classes in pilipay. - create an order by
$order = new PilipayOrder();
. - fill essential fields into the order.
- 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
- require the
autoload.php
in order to auto load the classes in pilipay. - create an order by
$order = new PilipayOrder();
. - fill essential fields into the order.
- 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:
useHttps
defines whether to use HTTPS - although HTTPS is recommend by default, you might want to use HTTP in some circumstances.useProductionEnv
defines whether to use the production environment. It's default value istrue
. But when you are testing, it is recommend to setuseProductionEnv
tofalse
. 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
- Make an issue on github
- Our official API site
- Send an email: developers(AT)pilibaba.com