Developer API Document
Index
Document Illustration
- The document's provider is iPasspay,we focus on providing our merchants a standard API integration rules.We have the right of final explaination on the document,and reserve the right to update it any time.
- To use the document,you can achieve the following functions: 'Accept credit payment online','Query order information','refund the order','Upload tracking information' and so on.
- The document's reader is merchants' administrator,maintainer and developer.
- Except otherwise defined,platform mentioned in this document means iPasspay.
Preparation
- 1.Read all the API document carefully
- 2.Obtain 4 very important parameters,they are "mid","site_id","api_key","gateway_version".
-
mid
- Merchant ID,an integer and you will use it to login the merchant dashborad. You will find it in the "My account" page.
-
site_id
- Site ID,when account is active,merchants need to submit those websites they want to do API integration.And once you add the website,you will get it.It is also an integer.You will get it in "My Website" page.
-
api_key
- API_KEY,very important parameter,it is used in all endpoint to create sha256 hash string.You will find it in the "My account" page.
-
gateway_version
- Gateway version,very important parameter.You will find it in the "My account" page.
-
- 3.All hash string mentioned in the document will use sha256 method to create.Each programing language will have its own method to create it.
- 4.Please make sure those websites added are active before you do live or test processing.If the website cannot pass our compliance,you will be notified via email as soon as possbile.
- 5.If you want to do test,ask our merchant service department staff to create a sandbox account for you.Do not worry about the reall charge because we will not send those payment data to the bank.
- 6.All gateway or endpoint mentioned in this document works on standard HTTPS protocol.You can use the "POST" or "GET" method to send data,and you will receive all response in "JSON" format.
- 7.Except otherwise defined,Currency format means the amount like 5.00,5.95,100.78,99.09,78.20 and so on. It is a positive float,accurate to the second decimal place.
- 8.Paramers format as following is data type|isMandatory|illustration.
- 9.M/O/C: M means "Mandatory",O means "Optinal",C means "Mandatory on constaint conditions"
Payment Gateway(Direct)
-
Gateway URL
- https://www.ipasspay.biz/index.php/Gateway/securepay
-
Method
- POST
-
Function
- Accept credit card payment online from the customers
-
Remark
- 25 mandatory and 13 optinonal parameters
1)Sending data
- mid
-
intMMerchant ID,please read the 'Preparation' to know how to get it.
- oid
-
stringMMerchant Order ID
- site_id
-
intMSite id,please read the 'Preparation' to know how to get it.
- order_amount
-
decimal(12,2)MOrder Amount,currency format
- order_currency
-
char(3)MCurrency code,3 upper-case letters,for example USD,GBP,CNY.For details,please refer to the currency support behind.
- hash_info
-
string(256)MHash string of the payment data via sha256 algorithm. Connect the following 6 paramters and use sha256 algorithm to create the hash value(lower case),they are 'mid','site_id','order_id','order_amount','order_currency','api_key'.
Sample Code(PHP):
$hash_info=hash("sha256",$mid.$site_id.$oid.$order_amount.$order_currency.$api_key); - card_no
-
number(16)MCredit Card Number
- card_ex_month
-
number(2)MCredit card expiration month.2 digits;for example,08 means August,11 means November.
- card_ex_year
-
number(2)MCredit card expiration year.2 digits. For example,18 means 2018; 19 means 2019.
- card_cvv
-
number(3) number(4)MCVV/CVV2/CVC number of the credit card,3 digits;for Amex card, 4 digits.
- bill_email
-
stringMCustomer billing email
- bill_phone
-
stringMCustomer billing phone
- bill_country
-
char(2)MCustomer billing country,2 upper-case letters.For details,please refer to Appendix 1:Country code.
- bill_state
-
stringMCustomer billing state,now it is mandatory for the USA and Canada.If there is no states for other countries,you can use '--'.For some interface,Austrilian and Japan also require to submit the correct state data.For details,please refer to Appendix 2:State code.
- bill_city
-
stringMCustomer billing city
- bill_street
-
stringMCustomer billing street
- bill_zip
-
stringMCustomer billing zip
- bill_firstname
-
stringMCustomer first name
- bill_lastname
-
stringMCustomer last name
- syn_url
-
stringMSynchronous notification URL,you can find it in the response data.
- asyn_url
-
stringMasyn_url is for Asynchronous notification URL.Asyn_url must be accessed via internet,so local URL is not allowed.Asyn_url can resolve those data loss issue due to bad network or timeout.Aysn_url is called by the platform,so it is silence to the merchants,but merchants should output data as required as following to the page,so we know that merchants have received the notification data.
When merchants receive the notification, they need to output a json format data as a response as following:
{ "status":100 }
If there is no "status" field or the value is not "100" in json, our system will push the notification 3 times at the most during the priod.
See hehind how to receive data sent by the platform. - source_ip
-
stringMClient IP address
- source_url
-
stringMClient's source URL
- gateway_version
-
floatMGateway version,please read the 'Preparation' to know how to get it..
- uuid
-
stringMUUID,Universally Unique Identifier,the format is like:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (8-4-4-4-12).Each programing language has its own method to create it。
- ship_email
-
stringCCustomer's shipping email
- ship_phone
-
stringCCustomer's shipping phone
- ship_country
-
char(2)CCustomer's shipping country
- ship_state
-
stringCCustomer's shipping state
- ship_city
-
stringOCustomer's shipping city
- ship_street
-
stringCCustomer's shipping street
- ship_zip
-
stringCCustomer's shipping zip code
- order_items
-
stringCShopping items by the customer,the format for multiple goods should be like this:
goods_name1|goods_attr1|goods_price1|goods_quantity1#goods_name2|goods_attr2|goods_price2|goods_quantity2#goods_name3|goods_attr3|goods_price3|goods_quantity3 ...
For example:
bag|red|100.00|1#shoe|small size,white|120.00|2#mac mini|8G,1T|500.00|1....
2)Posting code(PHP)
//encrypted the sensitive data
$hash_info=hash("sha256",$params['merchantid'].$params['siteid'].
$params['invoiceid'].$params['amount'].$params['currency'].$api_key);
$curlPost="order_amount=".$params['amount'];
$curlPost.="&order_currency=".$params['currency'];
$curlPost.="&mid=".$params['merchantid'];
$curlPost.="&site_id=".$params['siteid'];
$curlPost.="&oid=".$params['invoiceid'];
$curlPost.="&hash_info=".$hash_info;
$curlPost.="&card_no=".$params["card_number"];
$curlPost.="&card_ex_year=".$params["expiry_year"];
$curlPost.="&card_ex_month=".$params["expiry_month"];
$curlPost.="&card_cvv=".$params["cvv"];
$curlPost.='&bill_firstname='.$params['firstname'];
$curlPost.='&bill_lastname='.$params['lastname'];
$curlPost.='&bill_street='.$params['address1'];
$curlPost.='&bill_city='.$params['city'];
$curlPost.='&bill_state='.$params['state'];
$curlPost.='&bill_country='.$params['country'];
$curlPost.='&bill_zip='.$params['postcode'];
$curlPost.='&bill_phone='.$params['phonenumber'];
$curlPost.='&bill_email='.$params['email'];
$curlPost.='&syn_url='.$params['syn_url'];
$curlPost.='&asyn_url='.$params['asyn_url'];
$curlPost.='&source_ip='.$params['client_ip'];
$curlPost.='&source_url='.$_SERVER["HTTP_REFERER"];
$curlPost.='&gateway_version=1.0';
$curlPost.='&uuid='.create_guid();
/*If the gateway version is 2.0*/
$curlPost.='&ship_email='.$params['ship_email'];
$curlPost.='&ship_phone='.$params['ship_phone'];
$curlPost.='&ship_country='.$params['ship_country'];
$curlPost.='&ship_state='.$params['ship_state'];
$curlPost.='&ship_city='.$params['ship_city'];
$curlPost.='&ship_street='.$params['ship_street'];
$curlPost.='&ship_zip='.$params['ship_zip'];
$curlPost.='&order_items='.$params['order_items'];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $gateway_url);
curl_setopt($ch,CURLOPT_POST,1);
curl_setopt($ch,CURLOPT_POSTFIELDS,$curlPost);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,1);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
$response = curl_exec($ch);
curl_close($ch);
//process $response
$result = json_decode($response,true);
/**
* the function for creating uuid in PHP
*/
function create_guid() {
$charid = strtoupper(md5(uniqid(mt_rand(), true)));
$hyphen = chr(45); // "-"
$uuid = substr($charid, 0, 8) . $hyphen
. substr($charid, 8, 4) . $hyphen
. substr($charid, 12, 4) . $hyphen
. substr($charid, 16, 4) . $hyphen
. substr($charid, 20, 12);
return $uuid;
}
The code is just for reference.
Test Card information
4391880502212396 12/20 123
5105105105105100 12/20 123
3)Response
- Payment declined
-
{ "status": 0, "data": 10018, "info": "Billing street cannot be NULL" }
- Sale transaction success
-
{ "status": 1, "info": "payment success", "data": { "order_status": 2, "oid": "1", "pid": 2879, "order_amount": "1.00", "order_currency": "USD", "hash_info": "be17b8c545f13cddca1dd7ed05defb93", "syn_url": "http%3A%2F%2Fwww.baidu.com", "cascading":0, "billing_desc":"xxxxxx" } }
- Auth transaction success
-
{ "status": 1, "info": "authorized success", "data": { "order_status": 3, "oid": "1", "pid": 2879, "order_amount": "1.00", "order_currency": "USD", "hash_info": "be17b8c545f13cddca1dd7ed05defb93", "syn_url": "http%3A%2F%2Fwww.baidu.com", "cascading":0, "billing_desc":"xxxxxx" } }
- Payment failed
-
{ "status": 1, "info": "payment declined", "data": { "order_status": 6, "oid": "1", "pid": 2879, "order_amount": "1.00", "order_currency": "USD", "hash_info": "be17b8c545f13cddca1dd7ed05defb93", "syn_url": "http%3A%2F%2Fwww.baidu.com", "cascading":0, "billing_desc":"xxxxxx" } }
- Pending status
-
{ "status": 1, "info": "processing,please wait...", "data": { "order_status": 1, "oid": "1", "pid": 2879, "order_amount": "1.00", "order_currency": "USD", "hash_info": "be17b8c545f13cddca1dd7ed05defb93", "syn_url": "http%3A%2F%2Fwww.baidu.com", "cascading":0, "billing_desc":"xxxxxx", } }
3)Receive Notification by using asyn-url
We will send the following data (Non-json) to the asyn-url set by merchants via the standard HTTP POST method.
"order_status": 6,
"oid": "1",
"pid": 2879,
"order_amount": "1.00",
"order_currency": "USD",
"billing_desc": "xxxxxx",
"syn_url": "http%3A%2F%2Fwww.baidu.com",
"hash_info": "be17b8c545f13cddca1dd7ed05defb93",
"info":'High risk'
Sample Code(PHP)
If you're programing through PHP,you can get the data as following:
$order_status=$_POST['order_status'];
$order_id=$_POST['oid'];
$platform_oid=$_POST['pid'];
$order_amt=$_POST['order_amount'];
$order_currency=$_POST['order_currency'];
$billing_desc=$_POST['billing_desc'];
$syn_url=$_POST['syn_url'];
$hash_info=$_POST['hash_info'];
$info=$_POST['info'];
4)Response illustration
- status
- Transaction accepted or not,1 is yes,0 is no.
- info
- The prompting of the transaction,if the payment was declined or transaction is failed,it shows the reason.
- data
- If status is 0,it shows a code.if status is 1,it contains the following fileds of the order
- order_status
-
Order status code,they could be:
- 1 => Pending
- Transaction is submitted,but there is no response from the bank,so we donot know the final status of the transction.Keep waiting.
- 6 => Declined
- Payment failed."info" field contains the declined reason
- 2 => Approved
- Payment success.
- 3 => Authorized
- Payment authroized.
- oid
- Merchant Order ID
- pid
- Platform order id,please take care if it,some other endpoints behind will use it.
- order_amount
- Order Amount
- order_currency
- Currency
- hash_info
-
Hash string for the response,it's created by connecting the following 6 parameters with SHA256.
'order_status','oid','pid','order_amount','order_currency','api_key'.Sample Code(PHP):
$hash_info=hash("sha256",$order_status.$oid.$pid.$order_amount.$order_currency.$api_key); - syn_url
- Synchronous notification URL posted by merchants
- cascading
- Shows the times posted to the bank.0 means one time,1 means two times.The value could be 0,1,2,3。
- billing_desc
- The billing descriptor(merchant name) displayed on the customer's billing statment.
Payment Gateway(Host)
-
Gateway URL
- https://www.ipasspay.biz/index.php/Gateway/paygates
-
Method
- POST|GET
-
Function
- Accept credit card payment online from the customers
-
Remark
- 8 mandatory parameters,the others are all optional
- mid
- oid
- site_id
- order_amount
- order_currency
- syn_url
- asyn_url
- hash_info
Please check the description above so you can know how to obtain and set these paramters.
3D Payment Gateway(Direct)
-
Gateway URL
- https://www.ipasspay.biz/index.php/Gateway/securepay
-
Method
- POST
-
Function
- Accept credit card payment online from the customers
-
Remark
- 25 mandatory and 13 optinonal parameters
1)Sending data
2)Sample Code(PHP):
3)Response
- Payment declined
-
{ "status": 0, "data": 10018, "info": "Billing street cannot be NULL" }
- Pending status
-
Note
1).The response of 3D direct payment gateway is only pending status.
2).Merchant is required to set up "syn_url" and "asyn_url" to receive notification to change merchant's platform order status.
3).If Merchants got the "redirect_url" filed, please decode the URL and redirect the clients to the URL themselves, When the clients complete the 3D verification, they will be redirected to the "syn_url" set by the merchants with parameter. For more parameter details please refer to 'Receive Notification by using syn-url'.
{ "status": 1, "info": "processing,please wait...", "data": { "order_status": 1, "oid": "1", "pid": 2879, "order_amount": "1.00", "order_currency": "USD", "hash_info": "be17b8c545f13cddca1dd7ed05defb93", "syn_url": "http%3A%2F%2Fwww.baidu.com", "cascading":0, "billing_desc":"xxxxxx" "redirect_url":"http%3A%2F%2Fwww.baidu.com" } }
3)Receive Notification by using asyn-url
4)Receive Notification by using syn-url
We will send the following data (Non-json) to the syn-url set by merchants via the standard HTTP GET method.
"order_status": 6,
"oid": "1",
"pid": 2879,
"order_amount": "1.00",
"order_currency": "USD",
"billing_desc": "xxxxxx",
"info":'High risk'
"hash_info": "be17b8c545f13cddca1dd7ed05defb93",
"cascading": "1"
Sample Code(PHP)
If you're programing through PHP, you can get the data as following:
$order_status=$_GET['order_status'];
$order_id=$_GET['oid'];
$platform_oid=$_GET['pid'];
$order_amt=$_GET['order_amount'];
$order_currency=$_GET['order_currency'];
$billing_desc=$_GET['billing_desc'];
$info=$_GET['info'];
$hash_info=$_GET['hash_info'];
$cascading=$_GET['cascading'];
5)Response illustration
- status
- Transaction accepted or not,1 is yes,0 is no.
- info
- The prompting of the transaction,if the payment was declined or transaction is failed,it shows the reason.
- data
- If status is 0,it shows a code.if status is 1,it contains the following fileds of the order
- order_status
-
Order status code,they could be:
- 1 => Pending
- Transaction is submitted,but there is no response from the bank,so we donot know the final status of the transction.Keep waiting.
- 6 => Declined
- Payment failed."info" field contains the declined reason.
- 2 => Approved
- Payment success.
- 3 => Authorized.
- Payment authroized.
- oid
- Merchant Order ID
- pid
- Platform order id,please take care if it,some other endpoints behind will use it.
- order_amount
- Order Amount
- order_currency
- Currency
- hash_info
-
Hash string for the response,it's created by connecting the following 6 parameters with SHA256.
'order_status','oid','pid','order_amount','order_currency','api_key'.Sample Code(PHP):
$hash_info=hash("sha256",$order_status.$oid.$pid.$order_amount.$order_currency.$api_key); - syn_url
- Synchronous notification URL posted by merchants.
- cascading
- Shows the times posted to the bank.0 means one time,1 means two times.The value could be 0,1,2,3。
- billing_desc
- The billing descriptor(merchant name) displayed on the customer's billing statment.
- redirect_url
- The parameter is returned only when the transaction is sent to the 3D gateway. If Merchants got the "redirect_url" filed, please decode the URL and redirect the clients to the URL themselves, When the clients complete the 3D verification, they will be redirected to the "syn_url" set by the merchants with parameter. For more parameter details please refer to 'Receive Notification by using syn-url'.
6)3D Payment Gateway Flow Chart
Refund endpoint
-
Gateway URL
- https://www.ipasspay.biz/index.php/Openapi/Orders/refund
-
Method
- GET
-
Function
- Merchants can refund an order via the endpoint.
-
Remark
- 5 mandatory parameters
1)Sending data
- mid
-
intMMerchant ID,please read the 'Preparetion' to know how to get it.
- site_id
-
intMSite id,please read the 'Preparetion' to know how to get it.
- oid
-
intMPlatform order id,the 'pid' field in the gateway response,it is not merchant order id.
- refund_amount
-
decimal(12,2)MRefund amount;Currency format.Not more than origin order amount.
- hash_info
-
string(256)MHash string of the refunding endpoint,connect the 4 parameters above with 'api_key' to create a string via sha256 algorithm.
Sample Code(PHP):
$hash_info=hash("sha256",$mid.$site_id.$oid.$refund_amount.$api_key);
2)Response
- refund success
-
{ "status": 1, "info": "refund request successfully sent" }
- refund failed
-
{ "status": 0, "info": "invalid refund amount" }
3)Response illustration
- status
- Refunded or not, 1 means yes,0 means no.
- info
- Refund remark,if the status is 0,it is the failed reason.
Cancel refunding endpoint
-
Gateway URL
- https://www.ipasspay.biz/index.php/Openapi/Orders/cancelRefund
-
Method
- GET
-
Function
- Merchants can cancel those transactions with 'Pending refund' status.
-
Remark
- 4 mandatory parameters
1)Sending data
- mid
-
intMMerchant ID,please read the 'Preparetion' to know how to get it.
- site_id
-
intMSite id,please read the 'Preparetion' to know how to get it.
- oid
-
intMPlatform order id,the 'pid' field in the gateway response,it is not merchant order id.
- hash_info
-
string(256)MHash string of the refunding endpoint,connect the 4 parameters above with 'api_key' to create a string via sha256 algorithm.
Sample Code(PHP):
$hash_info=hash("sha256",$mid.$site_id.$oid.$api_key);
2)Response
- Cancel refunding success
-
{ "status": 1, "info": "cancel refund request successfully sent" }
- Cancel refunding failed
-
{ "status": 0, "info": "invalid order status" }
3)Response illustration
- status
- Canceled or not.1 means yeas,0 means no.
- info
- Cancel refunding remark.If status is 0,it shows the failed reson.
Void endpoint
-
Gateway URL
- https://www.ipasspay.biz/index.php/Openapi/Orders/void
-
Method
- GET
-
Function
- Merchants can void those 'authorized' transactions so it can not be captured automatically.
-
Remark
- 4 mandatory parameters,only pre-auth transaction will call the endpoint
1)Sending data
- mid
-
intMMerchant ID,please read the 'Preparetion' to know how to get it.
- site_id
-
intMSite id,please read the 'Preparetion' to know how to get it.
- oid
-
intMPlatform order id,the 'pid' field in the gateway response,it is not merchant order id.
- hash_info
-
string(256)MHash string of the void endpoint.Connect the 3 parameters above with 'api_key' to create a string via sha256 algorithm.
Sample Code(PHP):
$hash_info=hash("sha256",$mid.$site_id.$oid.$api_key);
2)Response
- Void success
-
{ "status": 1, "info": "Pre-auth voided successfully" }
- Void failed
-
{ "status": 0, "info": "Transaction not found" }
3)Response illustration
- status
- Voided or not,1 means yes,0 means no.
- info
- If the status is 0,it shows the failed reason.
Capture endpoint
-
Gateway URL
- https://www.ipasspay.biz/index.php/Openapi/Orders/capture
-
Method
- GET
-
Function
- Merchants can capture those 'authorized' transactions manually.If merchants don't take any action,these "authorized" transactions will be captured automatically after 15 days.
-
Remark
- 4 mandatory parameters,only pre-auth transaction will call the endpoint
1)Sending data
- mid
-
intMMerchant ID,please read the 'Preparetion' to know how to get it.
- site_id
-
intMSite id,please read the 'Preparetion' to know how to get it.
- oid
-
intMPlatform order id,the 'pid' field in the gateway response,it is not merchant order id.
- hash_info
-
string(256)MHash string of the void endpoint.Connect the 3 parameters above with 'api_key' to create a string via sha256 algorithm.
Sample Code(PHP):
$hash_info=hash("sha256",$mid.$site_id.$oid.$api_key);
2)Response
- Capture success
-
{ "status": 1, "info": "Pre-auth captured successfully" }
- Capture failed
-
{ "status": 0, "info": "Transaction not found" }
3)Response illustration
- status
- Captured or not,1 means yes,0 means no.
- info
- If the status is 0,it shows the failed reason.
Order query endpoint
-
Gateway URL
- https://www.ipasspay.biz/index.php/Openapi/Orders/getInfo
-
Method
- GET
-
Function
- Order query endpoint allows merchants to query some basic information of a transaction like order_id,order amount,billing address,order_status and exchange rate.
-
Remark
- 3 mandatory parameters,2 mandatory parameters on some constrait conditions.
1)Sending data
- mid
-
intMMerchant ID,please read the 'Preparetion' to know how to get it.
- site_id
-
intMSite id,please read the 'Preparetion' to know how to get it.
- oid
-
intCPlatform order id,the 'pid' field in the gateway response,it is not merchant order id.
- mh_oid
-
stringCMerchant order id,if there is more than 1 order with the same merchant order id,only the latest will be returned.
- hash_info
-
string(256)MHash string the query endpoint,connect the 4 parameters above with 'api_key' to create a string via sha256 algorithm.
Sample Code:$hash_info=hash("sha256",$mid.$site_id.$oid.$mh_oid.$site_key);
2)Response
- Query success
-
{ "status": 1, "info": "success", "data": { "order_id": 3, "merchant_oid": "3", "order_time": "2014-12-10 11:18:24", "order_status": 1, "order_amount": "1.00", "order_currency": "USD", "card_type": "visa", "order_site": "http://www.test.com", "billing_strongail": "test@test.com", "billing_country": "US", "billing_state": "CA", "billing_city": "test", "billing_street": "test", "billing_phone": "18888888888", "process_mode": "sales", "process_type": "production" } }
- Query failed
-
{ "status": 0, "info": "transaction not found" }
3)Response illustration
- status
- Query successfully or not,1 means yes,0 means no.
- info
- If status is 0,it shows the failed reason.
- data
- Only when quering is successful,the field will be returned.It contains the following fields:
- order_id
- Platform Order ID
- merchant_oid
- Merchant Order ID
- order_time
- Order Time(Beijing time)
- order_status
- Order status,please refer to Appendix3.
- order_amount
- Order Amount
- order_currency
- Currency
- card_type
- Credit Card Type
- billing_email
- order_site
- Website
- billing_country
- Country
- billing_state
- State/Province
- billing_city
- City
- billing_street
- Street
- billing_phone
- Phone
- process_mode
- Processing mode,the value could be 'sale' or 'authorized'
- process_type
- Porcessing type,the value could be 'sandbox' or 'production'
'oid' and 'mh_oid' are not required to posted at the same time.If you do so,'mh_oid' will be ignored by the platform.
Tracking upload endpoint
-
Gateway URL
- https://www.ipasspay.biz/index.php/Openapi/Tracking/upload
-
Method
- GET
-
Function
- Merchant can upload tracking number without signing in.
-
Remark
- 6 mandatory parameters
1)Sending data
- mid
-
intMMerchant ID,please read the 'Preparetion' to know how to get it.
- site_id
-
intMSite id,please read the 'Preparetion' to know how to get it.
- oid
-
intMPlatform order id,the 'pid' field in the gateway response,it is not merchant order id.
- tracking_company
-
stringMExpress company code,please refer to Express Support
- tracking_number
-
stringMTracking Number
- hash_info
-
string(256)MHash string of the tracking upload endpoint.Connect the 5 parameters above with 'api_key' to create a string via sha256 algorithm.
Sample Code(PHP):$hash_info=hash("sha256",$mid.$site_id.$oid.$tracking_company.$tracking_number.$api_key);
2)Response
- Uploading success
-
{ "status": 1, "info": "tracking uploaded" }
- Uploading failed
-
{ "status": 0, "info": "transaction not found" }
3)Response illustration
- status
- Uploaded or not,1 means yes,0 means no.
- info
- If the status is 0,it shows the failed reason.
1.Only those express company supported by the platform allow to upload tracking number
2.If you upload tracking number for the same order more than twice,the latest information will be used.
Query order list endpoint
-
Gateway URL
- https://www.ipasspay.biz/index.php/Openapi/Orders/getOrderList
-
Method
- GET
-
Function
- The endpoint allows merchants to query the order list by the status and date.
-
Remark
- 5 mandatory parameters,1 optional parameter.
1)Sending data
- mid
-
intMMerchant ID,please read the 'Preparetion' to know how to get it.
- start_time
-
dateMThe start date you want to query the order list, the format of which is xxxx-xx-xx, for example,2018-07-03.
- end_time
-
dateMThe end date you want to query the order list, the format of which is xxxx-xx-xx, for example,2018-07-03.
- order_status
-
intMCheck Appendix3 behind.
- hash_info
-
stringMHash string the query endpoint,connect the 3 parameters above with 'api_key' to create a string via sha256 algorithm.
Sample Code:$hash_info=hash("sha256",$mid.$start_time.$end_time.$order_status.$api_key); - page
-
intOThe pagination parameter, which means when the number of the records you queried is over 30, you need to send "page" like 2,3,4 or similar to get more data.If you don't send the parameter,the platform will take it as 1.
2)Response
- Query success
-
{ "status": 1, "info": "success", "data": { "total_num": 2, "page_num": 1, "order_list": [ { "order_id": 167, "mh_oid": "1", "mid": 3, "site_id": 1, "order_amount": "1.00", "order_currency": "USD", "order_time": "2018-01-17 11:47:07", "complete_time": "2018-01-17 11:47:10", "order_status": 2, "source_url": "https:\/\/www.google.com", "source_ip": "127.0.0.1", "billing_descriptor": "test", "card_type": "visa", "card_no": "411111******1111", "card_holder": "test", "bill_email": "test@test.com", "bill_country": "US", "bill_state": "CA", "bill_city": "test", "bill_street": "test", "bill_phone": "18611111111", "bill_zip": "21300", "remark": "Payment Success" }, { "order_id": 166, "mh_oid": "1", "mid": 3, "site_id": 1, "order_amount": "1.00", "order_currency": "USD", "order_time": "2018-01-17 11:47:07", "complete_time": "2018-01-17 11:47:10", "order_status": 2, "source_url": "https:\/\/www.google.com", "source_ip": "127.0.0.1", "billing_descriptor": "test", "card_type": "visa", "card_no": "411111******1111", "card_holder": "test", "bill_email": "test@test.com", "bill_country": "US", "bill_state": "CA", "bill_city": "test", "bill_street": "test", "bill_phone": "18611111111", "bill_zip": "21300", "remark": "Payment Success" } ] } }
- Query failed
-
{ "status": 0, "info": "Merchant not found" }
3)Response illustration
- status
- Query successfully or not,1 means yes,0 means no.
- info
- If status is 0,it shows the failed reason.
- data
- Only when quering is successful,the field will be returned.It contains the following fields:
- total_num
- The total number of the records.
- page_num
- The total pagination number.
- order_list
- The array of the order list,it contains the following fields:
- order_id
- The unique order id in the platform.
- mh_oid
- Merchant Order ID, submitted by the merchants.
- mid
- Merchant ID,please read the 'Preparetion' to know how to get it.
- site_id
- The site ID of this transaction.
- order_amount
- Order Amount
- order_currency
- Currency
- order_time
- Order time
- complete_time
- Complete time of the transaction.
- order_status
- Order status,please check Appendix3 behind.
- source_url
- The source URL of the client
- source_ip
- Source IP of the client.
- billing_descriptor
- Billing descriptor of the order
- card_type
- Credit card type.
- card_no
- Credit card number with the middle 6 digits masked.
- card_holder
- The name of the cardholder
- bill_email
- Billing email address
- billing_country
- Country
- billing_state
- State/Province
- billing_city
- City
- billing_street
- Street
- billing_phone
- Phone
- billing_zip
- Post Code
- remark
- Some description of this order status.
The system only returns 30 records of the total querying result, if you want to check more, you need to know how to use the pagination parameter "page".
Currency Support
The following currencies are supported now by us,actually we can support more to meet merchants' needs.
- CNY
- Chinese Yuan
- GBP
- United Kingdom Pound
- USD
- United States Dollar
- EUR
- Euro
- CAD
- Canadian Dollar
- JPY
- Japanese Yen
- AUD
- Australia Dollar
Express Support
Here list some express companys supported,for all list,please check in merchant dashboard.
- FEDEX
- http://www.fedex.com/us/
- USPS
- http://www.usps.com
Appendix1.Country Code
Country code supported by the platform,ISO Alpha-2
- Afghanistan(AF)
- Albania(AL)
- Algeria(DZ)
- American Samoa(AS)
- Andorra(AD)
- Angola(AO)
- Anguilla(AI)
- Antarctica(AQ)
- Antigua and Barbuda(AG)
- Argentina(AR)
- Armenia(AM)
- Aruba(AW)
- Australia(AU)
- Austria(AT)
- Azerbaijan(AZ)
- Bahamas(BS)
- Bahrain(BH)
- Bangladesh(BD)
- Barbados(BB)
- Belarus(BY)
- Belgium(BE)
- Belize(BZ)
- Benin(BJ)
- Bermuda(BM)
- Bhutan(BT)
- Bolivia(BO)
- Bosnia and Herzegowina(BA)
- Botswana(BW)
- Bouvet Island(BV)
- Brazil(BR)
- British Indian Ocean Territory(IO)
- Brunei Darussalam(BN)
- Bulgaria(BG)
- Burkina Faso(BF)
- Burundi(BI)
- Cambodia(KH)
- Cameroon(CM)
- Canada(CA)
- Cape Verde(CV)
- Cayman Islands(KY)
- Central African Republic(CF)
- Chad(TD)
- Chile(CL)
- China(CN)
- Christmas Island(CX)
- Cocos (Keeling) Islands(CC)
- Colombia(CO)
- Comoros(KM)
- Congo(CG)
- Cook Islands(CK)
- Costa Rica(CR)
- Cote D'Ivoire(CI)
- Croatia(HR)
- Cuba(CU)
- Cyprus(CY)
- Czech Republic(CZ)
- Denmark(DK)
- Djibouti(DJ)
- Dominica(DM)
- Dominican Republic(DO)
- Timor-Leste(TL)
- Ecuador(EC)
- Egypt(EG)
- El Salvador(SV)
- Equatorial Guinea(GQ)
- Eritrea(ER)
- Estonia(EE)
- Ethiopia(ET)
- Falkland Islands (Malvinas)(FK)
- Faroe Islands(FO)
- Fiji(FJ)
- Finland(FI)
- France(FR)
- French Guiana(GF)
- French Polynesia(PF)
- French Southern Territories(TF)
- Gabon(GA)
- Gambia(GM)
- Georgia(GE)
- Germany(DE)
- Ghana(GH)
- Gibraltar(GI)
- Greece(GR)
- Greenland(GL)
- Grenada(GD)
- Guadeloupe(GP)
- Guam(GU)
- Guatemala(GT)
- Guinea(GN)
- Guinea-bissau(GW)
- Guyana(GY)
- Haiti(HT)
- Heard and Mc Donald Islands(HM)
- Honduras(HN)
- Hong Kong(HK)
- Hungary(HU)
- Iceland(IS)
- India(IN)
- Indonesia(ID)
- Iran (Islamic Republic of)(IR)
- Iraq(IQ)
- Ireland(IE)
- Israel(IL)
- Italy(IT)
- Jamaica(JM)
- Japan(JP)
- Jordan(JO)
- Kazakhstan(KZ)
- Kenya(KE)
- Kiribati(KI)
- Korea, Democratic People's Republic of(KP)
- Korea, Republic of(KR)
- Kuwait(KW)
- Kyrgyzstan(KG)
- Lao People's Democratic Republic(LA)
- Latvia(LV)
- Lebanon(LB)
- Lesotho(LS)
- Liberia(LR)
- Libyan Arab Jamahiriya(LY)
- Liechtenstein(LI)
- Lithuania(LT)
- Luxembourg(LU)
- Macao(MO)
- Macedonia, The Former Yugoslav Republic of(MK)
- Madagascar(MG)
- Malawi(MW)
- Malaysia(MY)
- Maldives(MV)
- Mali(ML)
- Malta(MT)
- Marshall Islands(MH)
- Martinique(MQ)
- Mauritania(MR)
- Mauritius(MU)
- Mayotte(YT)
- Mexico(MX)
- Micronesia, Federated States of(FM)
- Moldova(MD)
- Monaco(MC)
- Mongolia(MN)
- Montserrat(MS)
- Morocco(MA)
- Mozambique(MZ)
- Myanmar(MM)
- Namibia(NA)
- Nauru(NR)
- Nepal(NP)
- Netherlands(NL)
- Netherlands Antilles(AN)
- New Caledonia(NC)
- New Zealand(NZ)
- Nicaragua(NI)
- Niger(NE)
- Nigeria(NG)
- Niue(NU)
- Norfolk Island(NF)
- Northern Mariana Islands(MP)
- Norway(NO)
- Oman(OM)
- Pakistan(PK)
- Palau(PW)
- Panama(PA)
- Papua New Guinea(PG)
- Paraguay(PY)
- Peru(PE)
- Philippines(PH)
- Pitcairn(PN)
- Poland(PL)
- Portugal(PT)
- Puerto Rico(PR)
- Qatar(QA)
- Reunion(RE)
- Romania(RO)
- Russian Federation(RU)
- Rwanda(RW)
- Saint Kitts and Nevis(KN)
- Saint Lucia(LC)
- Saint Vincent and the Grenadines(VC)
- Samoa(WS)
- San Marino(SM)
- Sao Tome and Principe(ST)
- Saudi Arabia(SA)
- Senegal(SN)
- Seychelles(SC)
- Sierra Leone(SL)
- Singapore(SG)
- Slovakia (Slovak Republic)(SK)
- Slovenia(SI)
- Solomon Islands(SB)
- Somalia(SO)
- South Africa(ZA)
- South Georgia and the South Sandwich Islands(GS)
- Spain(ES)
- Sri Lanka(LK)
- St. Helena(SH)
- St. Pierre and Miquelon(PM)
- Sudan(SD)
- Suriname(SR)
- Svalbard and Jan Mayen Islands(SJ)
- Swaziland(SZ)
- Sweden(SE)
- Switzerland(CH)
- Syrian Arab Republic(SY)
- Taiwan(TW)
- Tajikistan(TJ)
- Tanzania, United Republic of(TZ)
- Thailand(TH)
- Togo(TG)
- Tokelau(TK)
- Tonga(TO)
- Trinidad and Tobago(TT)
- Tunisia(TN)
- Turkey(TR)
- Turkmenistan(TM)
- Turks and Caicos Islands(TC)
- Tuvalu(TV)
- Uganda(UG)
- Ukraine(UA)
- United Arab Emirates(AE)
- United Kingdom(GB)
- United States(US)
- United States Minor Outlying Islands(UM)
- Uruguay(UY)
- Uzbekistan(UZ)
- Vanuatu(VU)
- Vatican City State (Holy See)(VA)
- Venezuela(VE)
- Viet Nam(VN)
- Virgin Islands (British)(VG)
- Virgin Islands (U.S.)(VI)
- Wallis and Futuna Islands(WF)
- Western Sahara(EH)
- Yemen(YE)
- Serbia(RS)
- Zambia(ZM)
- Zimbabwe(ZW)
- Aaland Islands(AX)
Appendix2.State Code
For the USA and Canada,please use 2 letters state code. Some will require Australia and Japan's state code.
- Alabama(AL)
- Alaska(AK)
- American Samoa(AS)
- Arizona(AZ)
- Arkansas(AR)
- Armed Forces Africa(AF)
- Armed Forces Americas(AA)
- Armed Forces Canada(AC)
- Armed Forces Europe(AE)
- Armed Forces Middle East(AM)
- Armed Forces Pacific(AP)
- California(CA)
- Colorado(CO)
- Connecticut(CT)
- Delaware(DE)
- District of Columbia(DC)
- Federated States Of Micronesia(FM)
- Florida(FL)
- Georgia(GA)
- Guam(GU)
- Hawaii(HI)
- Idaho(ID)
- Illinois(IL)
- Indiana(IN)
- Iowa(IA)
- Kansas(KS)
- Kentucky(KY)
- Louisiana(LA)
- Maine(ME)
- Marshall Islands(MH)
- Maryland(MD)
- Massachusetts(MA)
- Michigan(MI)
- Minnesota(MN)
- Mississippi(MS)
- Missouri(MO)
- Montana(MT)
- Nebraska(NE)
- Nevada(NV)
- New Hampshire(NH)
- New Jersey(NJ)
- New Mexico(NM)
- New York(NY)
- North Carolina(NC)
- North Dakota(ND)
- Northern Mariana Islands(MP)
- Ohio(OH)
- Oklahoma(OK)
- Oregon(OR)
- Pennsylvania(PA)
- Puerto Rico(PR)
- Rhode Island(RI)
- South Carolina(SC)
- South Dakota(SD)
- Tennessee(TN)
- Texas(TX)
- Utah(UT)
- Vermont(VT)
- Virgin Islands(VI)
- Virginia(VA)
- Washington(WA)
- West Virginia(WV)
- Wisconsin(WI)
- Wyoming(WY)
- Alberta(AB)
- British Columbia(BC)
- Manitoba(MB)
- Newfoundland(NL)
- New Brunswick(NB)
- Nova Scotia(NS)
- Northwest Territories(NT)
- Nunavut(NU)
- Ontario(ON)
- Prince Edward Island(PE)
- Quebec(QC)
- Saskatchewan(SK)
- Yukon Territory(YT)
- Australian Capital Territory(ACT)
- New South Wales(NSW)
- Northern Territory(NT)
- Queensland(QLD)
- South Australia(SA)
- Tasmania(TAS)
- Victoria(VIC)
- Western Australia(WA)
- Hokkaido(HK)
- Aomori(AO)
- Iwate(IW)
- Miyagi(MY)
- Akita(AK)
- Yamagata(YM)
- Fukushima(FK)
- Ibaragi(IB)
- Tochigi(TC)
- Gunma(GU)
- Saitama(SI)
- Chiba(CB)
- Tokyo(TK)
- Kanagawa(KN)
- Niigata(NI)
- Toyama(TY)
- Ishikawa(IS)
- Fukui(FI)
- Yamanashi(YN)
- Nagano(NG)
- Gifu(GF)
- Shizuoka(SZ)
- Aichi(AI)
- Mie(ME)
- Shiga(SG)
- Kyoto(KT)
- Osaka(OS)
- Hyogo(HG)
- Nara(NR)
- Wakayama(WK)
- Tottori(TT)
- Shimane(SM)
- Okayama(OK)
- Hiroshima(HR)
- Yamaguchi(YG)
- Tokushima(TS)
- Kagawa(KG)
- Ehime(EH)
- Kouchi(KC)
- Fukuoka(FO)
- Saga(SA)
- Nagasaki(NS)
- Kumamoto(KM)
- Ooita(OI)
- Miyazaki(MZ)
- Kagoshima(KS)
Appendix3.Order status illustration
- Status Code
- Meaning
- 1
- Pending
- 2
- Approved
- 3
- Authorized
- 4
- Captured
- 5
- Voided
- 6
- Declined
- 7
- Pending Refund
- 8
- Refunded
- 9
- Chargeback
- 10
- Pre-dispute
Appendix4.Developer Kit
https://github.com/boss420/ipasspay
Composer require boss420/ipasspay