HTTP API Reference (V1)

English Version


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:; testing domain:

1.1 Parameters

M/O: Mandatory / Optional

Field M/O Type Max Length Description
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
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.
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 String 50 Goods’ attributes. Such as color, size…
category O String 10 The category when taxing
height O Integer 10 Height of goods. Unit: mm.
length O Integer 10 Length of goods. Unit: mm.
width O Integer 10 Width of goods. Unit: mm.
name M String 500 Name of the product.
pictureURL M String 250 URL of the product’s picture.
price M Integer 20 Price of the product(including tax if any). Unit: cent
productURL M String 250 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


// with form data: (decoded)
orderTime:2015-11-25 15:52:51
sendTime:2015-11-25 15:52:51

// headers:
HTTP/1.1 302 Found

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

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:; testing domain:

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

2.2 Response

The response of this interface can be ignored.

2.3 Example


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

3 Pay Result Callback Interface

Corresponding to 4. push payment status in the process diagram

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

Request Type: GET

URL:serverUrl in Submit Order Interface

3.1 Parameters

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
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 + sendTime + appSecret), in which + means string concatenation
payResult String The result of the payment. “10” for success; “11” for failure.
dealId String Pilibaba’s interal pay ID.
fee String Charge for pilibaba by fee rate.
sendTime String The time when the order is sent. Its format is like 2001-12-13 14:15:16
customerMail String The email address of the customer.

3.2 Response

After the callback is dealed, the following fields should be returned. And the returned response should be encoded in xml:

Field Type Description
result Integer 1 for success, other values for failure.
redirecturl String The URL, which the customer will be redirected to.



4 Barcode Interface

This interface generates a bar code picture by Pilibaba’s inner code number.

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:; testing domain:

###4.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

4.2 Response

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


<img src="" />

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:; testing domain:

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:; testing domain:

Parameters: None

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

For Example:



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 If you want to login as a merchant, please visit