HTTP API Reference (V2.0.01)

Overview

The following diagram is the flow of a pilibaba’s order. This document mainly describes APIs in the colored steps (2, 4 and 5).

  1. A customer submits order on your store;
  2. Your store pushes the order’s detail to Pilibaba, which includes goods list, total weight, total price and so on;
  3. Pililbaba guides the customer to fillout personal information (address, phone, email…). And the customer pays for the order;
  4. Pilibaba pushes the payment data (paid amount, payment status, order ID, Pilibaba’s transaction ID, a barcode to be printed on the package…) to your store and the Warehouse;
  5. Your store pushes shipping detail (maily the tracking number) to Pilibaba;
  6. Pilibaba notifies the Warehouse of the shipping detail;
  7. Your store ships out the goods;
  8. Warehouse confirms receipt;
  9. Pilibaba pushes the receipt status to your store;
    Finally, the customer receives goods.

1 Submit Order Interface

Corresponding to 2. push order detail in the process diagram

Request Type: POST

URL: https://<pilibaba-domain>/pilipay/payreq
(production domain: www.pilibaba.com; testing domain: pre.pilibaba.com)

1.1 Parameters

M/O: Mandatory / Optional

Field M/O Type Max Length Description
version M String 20 The version of this API. Current value: “V2.0.01”;
merchantNo M String 50 Merchant number
currencyType M String 3 The currency code of your e-store. Currently we support: USD, EUR, GBP, AUD, CAD, JPY and so on.
orderNo M String 50 Order number, which is created by your e-store to identify the order.
orderAmount M Integer 20 The total amount of the order (including tax if any). Unit: cent
deductibleAmount O Integer 20 Can be deducted from orderAmount.Unit: cent
orderTime M String 20 Time when the order is submitted. Its format is like 2001-12-13 14:15:16
sendTime M String 20 Such as the 2001-12-13 14:15:16 send time format
pageUrl M String 255 The URL of checkout page.
serverUrl M String 255 The URL for payment result callback。After the order is paid, this URL will be requested. Please refer to Pay Result Callback Interface for more detail.
redirectUrl M String 255 The return page’s URL for customers after paid
notifyType M String 255 What type of code I return.The value:html、json.
async O String 10 If "notifyType = json" sets this value to "false"
shipper M Integer 20 The shipping fee from your store to Pilibaba’s warehouse (including tax if any). Unit: cent
tax M Integer 20 The additional tax if any. It depends on your country usual policy. Unit: cent
signType M String 3 The type of signing. Currently only “MD5” is supported
signMsg M String 50 The sign of the request. It is used to verify the request. It is generated by: md5(version + merchantNo + currencyType + orderNo + orderAmount + orderTime + pageUrl + serverUrl + redirectUrl + notifyType + shipper + tax + signType + appSecret)
goodsList M String 1000 The goods information. It is an URL-encoded JSON Array in which each item is a JSON object representing a good.

Good Information JSON Object Fields:

Field M/O Type Max Length Description
attr O Object 2000 Goods’ attributes. Such as color, size…
name M String 255 Name of the product.
pictureURL M string 255 URL of the product’s picture.
price M Integer 20 Price of the product(including tax if any). Unit: cent
productURL M String 255 URL of the product, which could be visited by a customer.
productId M String 50 The ID of the product.
quantity M Integer 20 How many this product is in the order.
weight M Integer 10 One product’s weight. Unit: gram

1.2 Response

If the request is valid, the response is a HTTP 302 Found to redirect the customer to pilibaba’s checkout page (or login page if not logged in).

If the request is invalid, an error page will be shown. A detailed error message along with error codes will be on the page.

1.3 Example

// REQUEST:
POST https://www.pilibaba.com/pilipay/payreq

// with form data: (decoded)
version:V2.0.01
merchantNo:0210000202
currencyType:CNY
orderNo:1930914372
orderAmount:4664
orderTime:2015-11-25 15:52:51
pageUrl:http://api.pilibaba.com/shopify_app/pilibaba/return_url.php
serverUrl:http://api.pilibaba.com/shopify_app/pilibaba/notify_url.php
redirectUrl:http://api.pilibaba.com/shopify_app/pilibaba/redirect_back.php?order=1930914372
notifyType:html
shipper:2000
tax:0
signType:MD5
signMsg:06b361046890cdad4f068b2a1fad3804
goodsList:%5B%7B%22name%22%3A%22Jeans+of+Julies%28Large+%5C%2F+Black%29%22%2C%22pictureURL%22%3A%22https%3A%5C%2F%5C%2Fcdn.shopify.com%5C%2Fs%5C%2Ffiles%5C%2F1%5C%2F1065%5C%2F1088%5C%2Fproducts%5C%2FIMG_0083.JPG%3Fv%3D1447840533%22%2C%22price%22%3A%22888%22%2C%22productURL%22%3A%22https%3A%5C%2F%5C%2Flocatar.myshopify.com%5C%2Fproducts%5C%2Fjeans-of-july%22%2C%22productId%22%3A%223668277764%22%2C%22quantity%22%3A%223%22%2C%22weight%22%3A%22650%22%2C%22attr%22%3A%22%22%2C%22category%22%3A%22%22%2C%22height%22%3A%220%22%2C%22length%22%3A%220%22%2C%22width%22%3A%220%22%7D%5D

// RESPONSE:
// headers:
HTTP/1.1 302 Found
Location: http://www.pilibaba.com/pilipay/checkout?orderId=606

// body:
// if there is an error, the error will be shown in html.

1.4 Return to merchant

Corresponding to 4. push payment status in the process diagram

This callback interface will be invoked after the order is successfully paid in Pilibaba. Order status should be updated when this callback interface is requested.

Note: If the order is not paid or payment is not successfully paid, this callback interface will not be invoked.

Request Type: GET

URL:serverUrl in Submit Order Interface

Field Type Description
merchantNo String Merchant number
orderNo String The order number, which is posted to Pilibaba via the Submit Order Interface
orderAmount String The total amount of the order. Unit: cent
dealId String Deal id.
signType String The type of signing. Currently only “MD5” is supported.
signMsg String The sign of the request. It is used to verify the request. And it is generated by: md5(merchantNO + orderNo + orderAmount + signType + fee + orderTime + customerMail + appSecret), in which + means string concatenation
fee String Charge for pilibaba by fee rate.
sendTime String The time when the message is sent. Its format is like 2001-12-13 14:15:16
orderTime String The time when the order is created. Its format is like 2001-12-13 14:15:16
customerMail String The email address of the customer. You should send the tracking information to this E-Mail after shipped the goods.

After the callback is dealed, a “OK” should be sent back in the response:
Example:

OK

If the response is not "OK", it is indicated that there are some errors. Pilibaba will try to send the request again.

1.5 Notify To Merchant

After customer pay for error.

Field Type Description
errorCode Integer
errorMessage String

If your notifyType is ‘html’,pilibaba will return these parameter to a html page .

If your notifyType is ‘json’,pilibaba will return these parameter to the merchant system.And now you can redirect the page yourself.

1.6 Error Code

Error Code Error Messages
800010001 merchantNo can not be null
800010002 merchantNo does not exist
800020001 merchantNo Key can not be null
800020002 merchantNo Key does not exist
800030001 currencyType can not be null
800030002 currencyType does not exist
800040001 orderNo can not be null
800040002 orderNo length is more than 50 characters
800050001 orderAmount can not be null
800050002 orderAmount length is more than 50 characters
800050003 orderAmount is not a numeric
800060001 orderTime can not be null
800060002 orderTime is not a correct format
800070001 sendTime can not be null
800070002 sendTime is not a correct format
800080001 pageURL can not be null
800080002 pageURL length is more than 255 characters
800090001 serverURL can not be null
800090002 serverURL length is more than 255 characters
800100001 shipper can not be null
800100002 shipper length is more than 20 characters
800100003 shipper is not a numeric
800110001 tax can not be null
800110002 tax length is more than 20 characters
800110003 tax is not a numeric
800120001 signType not MD5 format
800130001 signMsg can not be null
800130002 signMsg length is more than 50 characters
800140001 goodsList can not be null
600010001 product name can not be null
600010002 product name length is more than 255 characters
600020001 product pictureUrl can not be null
600020002 product pictureUrl length is more than 255 characters
600030001 product price can not be null
600030002 product price length is more than 20 characters
600030003 product price is not numeric
600040001 productUrl can not be null
600040002 productUrl length is more than 255 characters
600050001 productId can not be null
600050002 productId length is more than 50 characters
600060001 quantity can not be null
600060002 quantity length is more than 20 characters
600060003 quantity is not numeric
600070001 weight can not be null
600070002 weight length is more than 10 characters
600070003 weight is not numeric
900010001 Signature error
900020001 Payment error
900030001 Logistics error
999999999 System error
20001 version is null
20002 version value is error
20003 merchantNo is null
20004 merchantNo not exist
20005 currencyType is null
20006 currencyType not exist
20007 orderNo is null
20008 orderNo length is more than 50 characters
20009 orderAmount is null
20010 orderAmount length is more than 50 characters
20011 orderAmount is not a integer value
20012 orderTime is null
20013 orderTime format error, for example:2015-08-18 16:08:39
20014 pageUrl is null
20015 pageUrl length is more than 255 characters
20016 serverUrl is null
20017 serverUrl length is more than 255 characters
20018 redirectUrl is null
20019 redirectUrl length is more than 255 characters
20020 notifyType is null
20021 notifyType is not ^html ̄ or ^json ̄
20022 shipper is null
20023 shipper length is more than 20 characters
20024 shipper is not a integer value
20025 tax is null
20026 tax length is more than 20 characters
20027 tax is not a integer value
20028 signType is null
20029 signType is not ^MD5 ̄ format
20030 signMsg is null
20031 signMsg length is more than 50 characters
20032 goodsList is null
20040 product name is null
20041 product name length is more than 255 characters
20042 product pictureUrl is null
20043 product pictureUrl length is more than 255 characters
20044 price is null
20045 price length is more than 20 characters
20046 price is not a integer value
20047 productUrl is null
20048 productUrl length is more than 255 characters
20049 productId is null
20050 productId length is more than 50 characters
20051 quantity is null
20052 quantity length is more than 20 characters
20053 quantity is not a integer value
20054 weight is null
20055 weight length is more than 10 characters
20056 weight is not a integer value
10000 success
10001 System error
10002 currency rate not exist
10003 order amount more than 2000CNY
10004 order exist
10005 sign error
20057 deductibleAmount length is more than 20 characters
20058 deductibleAmount is not a integer value
10006 order not exist
10007 order amount more than 2000CNY

2 Update Tracking Number Interface

Corresponding to 5. push ship detail in the process diagram

Request Type: GET

URL: https://<pilibaba-domain>/pilipay/updateTrackNo (production domain: www.pilibaba.com; testing domain: pre.pilibaba.com)

Update the track number of the specified order after parcels are sent.

2.1 Parameters

M/O: Mandatory / Optional

Field M/O Type Max Length Description
orderNo M String 50 The order number, created by your e-store, identifies the order which is submitted to Pilibaba via the Submit Order Interface
logisticsNo M String 50 The logistics number, provided by the express company after parcels are sent, is used to track the parcels.
merchantNo M String 50 Merchant number
signMsg M String 50 Encrypt message (orderNo + logisticsNo + merchantNo + appSecrect), no empty, no +. The MD5 is encryption type

2.2 Response

The response of this interface can be ignored.

2.3 Example

// REQUEST:
GET https://www.pilibaba.com/pilipay/updateTrackNo?orderNo=123123&logisticsNo=87782481231231&merchantNo=201023123&signMsg=6a299536258afad2db5e21d92bc9a429

// RESPONSE:
// headers
HTTP/1.1 200 OK
// body:
// nothing...

3 Barcode Interface

This interface generates a bar code picture by Pilibaba’s inner code number. Print out attached/below logo&unique barcode and stick them on the surface of the parcel.

NOTE: You should print out the bar code and pasted at a conspicuous area of the package, before shipping it to one of Pilibaba’s warehouses.

Request Type: GET

URL: https://<pilibaba-domain>/pilipay/barCode (production domain: www.pilibaba.com; testing domain: pre.pilibaba.com)

3.1 Parameters

M/O: Mandatory / Optional

Field M/O Description
orderNo M The order number,which is submitted to Pilibaba via the Submit Order Interface
merchantNo M Merchant number

3.2 Response

The response is a picture. You can show it by tag on a web page.

Example:

<img src="https://www.pilibaba.com/pilipay/barCode?orderNo=XXXX&merchantNo=XXXXX" />

4 Consumer information

4.1 Access url

Production environment:https://www.pilibaba.com/pilipay/consumerInfo

4.2 Parameter Description

M/O:Mandatory (Highlighted in Bluebelow) / Optional

Field Optional Type Max Length Value Description
merchantNo M String 50 Merchant No Register in pilibaba. you can get this number from your account info page
orderNo M String 50 Order No Your website create order Number
signType M String 3 Encypt type MD5
signMsg M String 50 Encypt message Encrypt message(merchantNo + orderNo + signType + appSecrect),no empty,no +

4.3 Return to merchant

Field Type Description
code String
message String
name String in Chinese, full name, can Not separated by first name and last name
mobile String
zipcode String
country String
province String
city String
district String
address String
innerOrderNo String

For Example:

{
   "address" : "苏茂大厦228号9楼I座",
   "city" : "长沙市",
   "country" : "中国",
   "district" : "宁乡县",
   "code" :  "0",
   "message"  :  "success",  
   "email" : "qs@pilibaba.com",
   "innerOrderNo" : "20160121103621100001926166",
   "mobile" : "+8618651859698",
   "name" : "张三",
   "province" : "湖南省",
   "zipcode" : "000000"
}

5 Get Warehouse Address List Interface

This interface provide a programmatic way to fetch warehouse address list of Pilibaba. If shipping address is required by your e-store, you may choose one in the address list to fill as shipping address.

Request Type: GET

URL:https://<pilibaba-domain>/pilipay/getAddressList (production domain: www.pilibaba.com; testing domain: pre.pilibaba.com)

Parameters: None

Response: An array of Pilibaba’s warehouse address. (Encoded in JSON)

The warehouse’s address information contains the following fields:

Field Type Description
country String The country of the warehouse
firstName String The first name of the receiver
lastName String The last name of the receiver
address String The detail address of the warehouse
city String The city of the warehouse
state String The state of the warehouse
zipcode String The zipcode/postcode of the warehouse
tel String The telephone number of the receiver

For Example:

[
    {
        "country": "German",
        "firstName": "Postfach JXPNC",
        "lastName": "c/o Zebra Logistics GmbH",
        "address": "Nordersand 1, #Z0367",
        "city": "Hamburg",
        "state": "Hamburg",
        "zipcode": "20457",
        "tel": "040-57130336"
    },
    {
        "country": "Greate Britain",
        "firstName": "JXPNC",
        "lastName": "Pilibaba",
        "address": "Unit 13, Trident Way, Southall, London, #Z0367",
        "city": "Southall",
        "state": "GREATER LONDON",
        "zipcode": "UB2 5LF",
        "tel": "44 (020) 8571 0218"
    },
    // ...
]

6 Get Supported Currencies Interface

This interface provides all currencies that are currently supported by Pilibaba.

Request Type: GET

URL:https://<pilibaba-domain>/pilipay/getCurrency (production domain: www.pilibaba.com; testing domain: pre.pilibaba.com)

Parameters: None

Response: An array of currency codes that are supported by Pilibaba. (Encoded in JSON)

For Example:

[
    "USD",
    "EUR",
    "GBP",
    "JPY",
    "AUD",
    "CAD",
    "CHF",
    "CNY",
    "TWD"
]

FAQ

1.What is merchant number? How to get it?

Merchant number(merchantNO), is a number Pilibaba allocated to each merchant. It is used to identify merchant.

SIGN UP as a merchant. Then LOG IN to Pilibaba. And you can find the number in member information page:

2.What is appSecret? What is the usage of appSecret?
appSecret is a secret key Pilibaba allocated to each merchant. It is used to impove the security of transactions.

SIGN UP as a merchant. Then LOG IN to Pilibaba. And you can find the appSecret (secret key) in member information page:

3.Why do you use cent as unit in prices?

To avoid round-off error in using float numbers, we use integer for all numeric fields. So the unit must be the minimum one. For prices, taxes, shipping fees and order amounts, we all use cent as unit.

For example, supposing the currency type is USD and a product is priced at 1.89 USD, then the price field of the product must be assigned to 189 (cent).

4.How to embed Pilibaba payment?

If your e-store is created via any of the following tools, please view the corresponding guide:

. Shopify
. Magento
. WooCommerce in Wordpress
. Prestashop

Otherwise, a further development must be done. Please contact to your developers, and contact to Pilibaba.

By the way, for website developers, in order to embed Pilibaba payment, there are mainly two TODOs:

Firstly, in the Admin backend / back office:

Add a configuration page, in which the merchnat could configure merchantNo and appSecret. These two fields are used to identify the merchant and improve security. They need to be saved into a database or a configuration file for future usage;
Add a callback interface. This interface would be assigned to serverUrl field in Submit Order Interface. Please refer to Pay Result Callback Interface, and deal the pay result. Normally, please mark the order’s status to be “Paid” when the result is success.
When the order’s tracking number is updated, please invoke Update Tracking Number Interface to push the tracking number to Pilibaba. This tracking number will help Pilibaba identify the package.
In the order detail page, please show the barcode image from Barcode Interface . And prompt the merchant like this “You should print the barcode and paste it at a conspicuous area of the package before shipping the package out.” This barcode will also help Pilibaba identify the package.
Secondly, in storefront:

Add a “PILIBABA支付” button on the checkout page;
When the “PILIBABA支付” button is clicked, please collect the cart’s information, and invoke Submit Order Interface to push the order to Pilibaba.

5.Are there any environment for testing?

Yes, of course. Our domain for testing payment is pre.pilibaba.com. If you want to login as a merchant, please visit preen.pilibaba.com.