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: int

M
Merchant ID,please read the 'Preparation' to know how to get it.
oid: string

M
Merchant Order ID
site_id: int

M
Site id,please read the 'Preparation' to know how to get it.
order_amount: decimal(12,2)

M
Order Amount,currency format
order_currency: char(3)

M
Currency code,3 upper-case letters,for example USD,GBP,CNY.For details,please refer to the currency support behind.
hash_info: string(256)

M
Hash 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)

M
Credit Card Number
card_ex_month: number(2)

M
Credit card expiration month.2 digits;for example,08 means August,11 means November.
card_ex_year: number(2)

M
Credit card expiration year.2 digits. For example,18 means 2018； 19 means 2019.
card_cvv: number(3) number(4)

M
CVV/CVV2/CVC number of the credit card，3 digits;for Amex card, 4 digits.
bill_email: string

M
Customer billing email
bill_phone: string

M
Customer billing phone
bill_country: char(2)

M
Customer billing country,2 upper-case letters.For details,please refer to Appendix 1:Country code.
bill_state: string

M
Customer 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: string

M
Customer billing city
bill_street: string

M
Customer billing street
bill_zip: string

M
Customer billing zip
bill_firstname: string

M
Customer first name
bill_lastname: string

M
Customer last name
syn_url: string

M
Synchronous notification URL,you can find it in the response data.
asyn_url: string

M
asyn_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: string

M
Client IP address
source_url: string

M
Client's source URL
gateway_version: float

M
Gateway version，please read the 'Preparation' to know how to get it..
uuid: string

M
UUID,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。

For gateway version 2.0,the following parameters are mandatory

ship_email

string

C

Customer's shipping email

ship_phone

string

C

Customer's shipping phone

ship_country

char(2)

C

Customer's shipping country

ship_state

string

C

Customer's shipping state

ship_city

string

O

Customer's shipping city

ship_street

string

C

Customer's shipping street

ship_zip

string

C

Customer's shipping zip code

order_items

string

C

Shopping items by the customer,the format for multiple goods should be like this:

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 08/21 123
5105105105105100 08/21 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

Note

The parameters required for host payment gateway is almost the same as we required for direct payment gateway,but there are only 8 parameters are mandatory. They are as follwing:

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

Note

The parameters required for 3D direct payment gateway is almost the same as we required for direct payment gateway, please refer to direct payment gateway.

2）Sample Code(PHP):

Note

The sample code for 3D direct payment gateway is almost the same as sample code for direct payment gateway, please refer to direct payment gateway.

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

Note

The asynchronous notification for 3D direct payment gateway is almost the same as asynchronous notification for direct payment gateway, please refer to direct payment gateway.

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: int

M
Merchant ID,please read the 'Preparetion' to know how to get it.
site_id: int

M
Site id,please read the 'Preparetion' to know how to get it.
oid: int

M
Platform order id,the 'pid' field in the gateway response,it is not merchant order id.
refund_amount: decimal(12,2)

M
Refund amount;Currency format.Not more than origin order amount.
hash_info: string(256)

M
Hash 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: int

M
Merchant ID,please read the 'Preparetion' to know how to get it.
site_id: int

M
Site id,please read the 'Preparetion' to know how to get it.
oid: int

M
Platform order id,the 'pid' field in the gateway response,it is not merchant order id.
hash_info: string(256)

M
Hash 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: int

M
Merchant ID,please read the 'Preparetion' to know how to get it.
site_id: int

M
Site id,please read the 'Preparetion' to know how to get it.
oid: int

M
Platform order id,the 'pid' field in the gateway response,it is not merchant order id.
hash_info: string(256)

M
Hash 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: int

M
Merchant ID,please read the 'Preparetion' to know how to get it.
site_id: int

M
Site id,please read the 'Preparetion' to know how to get it.
oid: int

M
Platform order id,the 'pid' field in the gateway response,it is not merchant order id.
hash_info: string(256)

M
Hash 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: int

M
Merchant ID,please read the 'Preparetion' to know how to get it.
site_id: int

M
Site id,please read the 'Preparetion' to know how to get it.
oid: int

C
Platform order id,the 'pid' field in the gateway response,it is not merchant order id.
mh_oid: string

C
Merchant 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)

M
Hash 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: 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'

System Notice：
'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: int

M
Merchant ID,please read the 'Preparetion' to know how to get it.
site_id: int

M
Site id,please read the 'Preparetion' to know how to get it.
oid: int

M
Platform order id,the 'pid' field in the gateway response,it is not merchant order id.
tracking_company: string

M
Express company code,please refer to Express Support
tracking_number: string

M
Tracking Number
hash_info: string(256)

M
Hash 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.

System Notice：
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: int

M
Merchant ID,please read the 'Preparetion' to know how to get it.
start_time: date

M
The start date you want to query the order list, the format of which is xxxx-xx-xx, for example,2018-07-03.
end_time: date

M
The end date you want to query the order list, the format of which is xxxx-xx-xx, for example,2018-07-03.
order_status: int

M
Check Appendix3 behind.
hash_info: string

M
Hash 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: int

O
The 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.

System Notice：
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

To use this endpoint,you must use the express company name provided here.

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.

For US:

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)

For Canada(CA):

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)

For Australia(AU):

Australian Capital Territory(ACT)
New South Wales(NSW)
Northern Territory(NT)
Queensland(QLD)
South Australia(SA)
Tasmania(TAS)
Victoria(VIC)
Western Australia(WA)

For Japan(JP):

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

Powerful,flexible but easy to integrate in your application...

Powerful,flexible but easy to integrate in your application...

Developer API Document

Document Illustration

Preparation

Payment Gateway(Direct)

1）Sending data

2）Posting code(PHP)

Test Card information

3）Response

3）Receive Notification by using asyn-url

4）Response illustration

Payment Gateway(Host)

3D Payment Gateway(Direct)

1）Sending data

2）Sample Code(PHP):

3）Response

3）Receive Notification by using asyn-url

4）Receive Notification by using syn-url

5）Response illustration

6）3D Payment Gateway Flow Chart

Refund endpoint

1）Sending data

2）Response

3）Response illustration

Cancel refunding endpoint

1）Sending data

2）Response

3）Response illustration

Void endpoint

1）Sending data

2）Response

3）Response illustration

Capture endpoint

1）Sending data

2）Response

3）Response illustration

Order query endpoint

1）Sending data

2）Response

3）Response illustration

Tracking upload endpoint

1）Sending data

2）Response

3）Response illustration

Query order list endpoint

1）Sending data

2）Response

3）Response illustration

Currency Support

Express Support

Appendix1.Country Code

Appendix2.State Code

Appendix3.Order status illustration

Appendix4.Developer Kit

Powerful,flexible but easy to
integrate in your application...

Powerful,flexible but easy to
integrate in your application...