1 / Introduction
HipoPay Open API adopts the “REST” design principles. All API requests are resource-oriented. Standard Response status codes are used to indicate whether the request result is correct or not. All API requests would return in a canonical and friendly ‘JSON’ format (including error info). Every response would contain Meta info (status data of request itself) and data info (response data return from request).
2 / Authorization
Request
{
"MerchantNO": '123456',
"Signature": '539cae75aacf7d6533d288ded0f47b07',
"Version": '1.0',
"Timestamp": ''
}
The following four parameters should be added in the Header for all request made by merchants:
Prepare Public Key & Private Key
2.1 / MerchantNO
Merchant No. will be assigned by HipoPay.
2.2 / Signature
Signature rules are as follows:
Sort the request parameter names (querystring requested from GET, form content requested from POST) in ascending alphabetical order (i.e. lexicographical sequence) according to ASCII code and apply urlencode, then join them into string via the corresponding “URL key=value” format (as: key1=value1&key2=value2…)
Add Timestamp to the end of the signature string and separate them with’,’.
Apply RSA encryption to the final string by using SHA256 and the secret key thatyou used to
submit requests.
Base64_encode the encrypted string. Then this is the final signature.
Commonly-used signature algorithms will be provided by our technical personnel.
Request
def data_sign(data, timestamp, private_key):
"""
:param data: payload data
:param timestamp
:param private_key
:return: signature
"""
def format_code(x):
if isinstance(x, unicode):
return quote(x.encode("utf-8"), safe="")
elif isinstance(x, (float, int)):
return str(x)
else:
return quote(x, safe="")
# Sort the request parameter
signature_str = "&".join((
"=".join(map(format_code, i)) for i in sorted(data.items())
))
signature_str = signature_str.encode("utf-8")
signature_str += "," + str(timestamp)
print signature_str
pri_key = rsa.PrivateKey.load_pkcs1(private_key)
signature = base64.b64encode(rsa.sign(signature_str, pri_key, "SHA-256"))
return signature
2.3 / Version
Latest version: 1.0
Previous version: None.
2.4 / Timestamp
3 / Error Handling
Status Code | Description |
---|---|
400 | Bad Request |
401 | Unauthorized |
411 | Timestamp Error |
403 | Forbidden |
404 | Not Found |
500 | Internal Server Error |
503 | Service Unavailable |
555 | Wechat / Alipay Service Error |
If 555 error occurs, message parameter is a json string (as follows). Please refer to the WeChat / Alipay Error Description in message for more error info.
Parameter | Description |
---|---|
wx_message | WeChat Error Message |
wx_code | WeChat Error Code |
Click here to find out the description of error code:Check WeChat Error Code
4 / Payment (WeChat Wallet in China Mainland)
WeChat Cross-border Payment is available for those people who had their WeChat accounts undergone the real name authentication. APIs for the following scenarios are only available to collect payment from people with a WeChat account of China Mainland.:
Payment scenarios | Description | Docs |
---|---|---|
Official Account Payment | It applies to offline payment scenarios | 4.1 / Official Account Payment |
Quick Pay (Vendors scan payers’ QR code to collect money) | It applies to offline payment scenarios | 4.2 / Vendors scan payers’ QR code to collect |
Scanned _pay (Payer scans QR Code shown by vendors to pay) | It applies to both online & offline payment scenarios | 4.3 / Scanned _pay (Payer scans QR Code shown by vendors to pay) |
Mini Programs Payment | It applies to online payment scenarios | 4.4 / Mini Programs Payment |
4.1 /Official Account Payment
Official Account Payment refers to that customer scans the static QR code of merchant and inputs the amount payable on the official account interface to complete the transaction. There are a few steps:
First, get user’s openid(openid)
After scanning the QR code, customer will go to the following url::
After user’s openid is obtained, we will run the payment interface of merchants in our docker (we need to be informed of this interface in advance, then we will bind to merchants and bring back all the parameters in the authorized URL, and add an extra parameter (openid) as well.
Second, Place a payment order on the H5 payment interface.
After customer inputs the amount payable, the following APIs need to be called.:
Parameters are as follows:
Parameter | Description | Required |
---|---|---|
merchant_no | merchant _no | Yes |
amount | amount | Yes |
openid | openid | Yes |
currency | openid | Yes |
product_info | Product _info | Yes |
agent_order_id | Agent Order No. | No |
notify_url | Notify _url of payment result | No |
This API returns and calls the parameters of WeChat pay APP.
Third, call the payment page of client side.
Use API parameters above to make a call to the payment interface of Client side. Refer to the sample code on the right.
Request
Forth, check order status
Please refer to 4.7/ check payment order.
4.2 / Vendor Scans Payer’ s QR Code to Collect Money
Scan to Collect Payment means that merchant scans customers’ QR code by a device (like a scanner) and inputs the amount payable to collect money.
This API brings the QR code and payable amount to initiate a request of collection to WeChat. After that, customer confirms the payment amount on his/her mobile phone to complete the transaction.
Request
def scan_pay():
url = HOST + '/order/scan_pay'
data = dict(
merchant_no='xxx',
currency='HKD',
amount='100',
product_info='here is products info',
ip='102.142.32.12',
auth_code='135605691981176449'
)
timestamp = str(time.time())
sign = data_sign(data, timestamp, pri_key)
header = HEADER.copy()
header['Signature'] = sign
header['Timestamp'] = timestamp
response = requests.post(url, data, headers=header)
return response.content
Response
{
"data": {
"order": {
"agent_order_id": "xxxx",
"amount": "100",
"currency": "HKD",
"exchange_rate":""0.8789"",
"ip": "102.142.32.12",
"merchant_no": "xxx",
"no": "2017062313070231980966651",
"product_info": "here is products info",
"pay_amount": "0.1"
"status": "PAID",
"settle_rate": "1",
"trade_type": "MICRO"
}
},
"meta": {
"message": "Request successful",
"status_code": 200,
"success": true
}
}
Parameter | Description | Required |
---|---|---|
merchant_no | merchant_no | Yes |
currency | currency | Yes |
amount | amount | Yes |
product_info | product_info | Yes |
ip | Terminal IP | Yes |
auth_code | Content of Customer QR Code | Yes |
agent_order_id | Agent Order No. | No |
product_id | product_id | No |
device_info | device_info | No |
notify_url | Notify _url Of Payment result | No |
The response is in json format. Refer to appendix 14.1 for details of data structure of the payment order.
4.3 / Payer scans QR Code shown by vendors to pay
Scanned _Pay means that merchants generate a QR Code, which contains the payment information (like the amount payable, etc.) for customer to scan and pay.
This API initiates a payment request to WeChat and WeChat will return payment information and QR code url, then customer scan this QR code to complete the transaction.
Request
def scanned_pay():
url = HOST + '/order/scanned_pay'
data = dict(
merchant_no='xxx',
currency='HKD',
amount='100',
product_info='Product Info',
ip='102.142.32.12'
)
timestamp = str(time.time())
sign = data_sign(data, timestamp, pri_key)
header = HEADER.copy()
header['Signature'] = sign
header['Timestamp'] = timestamp
response = requests.post(url, data, headers=header)
return response.content
Response
{
"meta": {
"status_code": 200,
"message": "Request successful",
"success": true
},
"data": {
"code_url": "weixin://wxpay/bizpayurl?pr=3CaDEKX",
"order": {
"status": "INIT",
"trade_type": "NATIVE",
"no": "2017062312381442716795237",
"ip": "102.142.32.12",
"currency": "HKD",
"amount": "100",
"merchant_no": "xxx",
"agent_order_id": "xxxx"
"pay_amount": "0.1"
"settle_rate": "0.1"
"trade_time": "xxxxx"
"product_info": "Product Info",
"exchange_rate": "0.8789"
}
}
}
Parameters | Description | Required |
---|---|---|
merchant_no | merchant_no | Yes |
currency | currency | Yes |
amount | amount | Yes |
product_info | product_info | Yes |
ip | Terminal IP | Yes |
notify_url | Notify _url Of Payment result | No |
agent_order_id | Agent Order No. | No |
product_id | Product _id | No |
device_info | Device _info | No |
The response is in json format, and the content of data includes the following two parts: - code_url: it is used to generate QR code, when merchants get this url, please generate QR code on the devices for customers to scan and pay. - order: Please refer to appendix 14.1 for payment details and data structure.
4.4 / Mini Programs Payment
First, get user’s login code.
A call of wx.login need to be made and the user’s login code will be obtained from the return results(code is valid in 5 mins).
Second, get user’s openid and call the API below:
Parameter | Description | Required |
---|---|---|
code | user’s login code | Yes |
merchant_no | merchant_no | Yes |
Response
{
"meta": {
"status_code":200 ,
"message": "Request successful",
"success": true
},
"data": {
"openid":"kxc13i13J123"
}
}
Third, place an order, Call the API below and transfer the parameters:
Response
{
"meta": {
"status_code":200 ,
"message": "Request successful",
"success": true
},
"data": {
"timeStamp": "1509692687",
"prepay_id": "wc1312341312312",
"nonceStr": "casd135Defg",
"paySign": "55511808baf7f301b5270d7334a4cec0",
"order_no": "2017062317201074212938080"
}
}
Parameter | Description | required |
---|---|---|
merchant_no | merchant_no | Yes |
openid | WeChat openid | Yes |
currency | currency | Yes |
amount | mount | Yes |
product_info | product_info | Yes |
agent_order_id | Agent Order No. | No |
notify_url | Notify _url of payment result | No |
Forth, call the payment page of client side.
Sample codes are as follows. Among that,timeStamp,nonceStr,prepay_id,sign can be obtained through the previous step.
|
Fifth, check order status.
Please refer to 4.7/Check Payment Order. Order No. can be obtained by the third step.
4.5 / In-App Payment
4.5.1 / Description
In-App payment refers to a mobile-based payment in which the Vendor calls the WeChat payment module while users pay in WeChat App and then get back to the Vendors’ App.
4.5.2 / APP registration on WeChat Open Platform
Registered Address:WeChat Open Platform
You need to submit the app _id to HipoPay after registration.
4.5.3 / Integration
There are three steps:
- Make API request to get payment parameters.
- Call WeChat SDK to make a payment. -Get payment status.
First / request API of payment.
Response
{
"meta": {
"status_code":200 ,
"message": "Request successful",
"success": true
},
"order": {
"status": "INIT",
"trade_type": "NATIVE",
"no": "2017062312381442716795237",
"ip": "102.142.32.12",
"currency": "HKD",
"amount": "100",
"merchant_no": "xxx",
"agent_order_id": "xxxx"
"pay_amount": "0.1"
"settle_rate": "0.1"
"trade_time": "xxxxx"
"product_info": "product_info",
"exchange_rate": "0.8789"
},
"prepay_params": {
"timeStamp": "1509692687",
"appid": "2619692747",
"prepayId": "20180210XXXXXXXXX",
"PartnerId": "wc1312341312312",
"packageValue": "Sign=WXPay",
"nonceStr": "casd135Defg",
"sign": "55511808baf7f301b5270d7334a4cec0",
}
}
Parameter | Description | Required |
---|---|---|
merchant_no | merchant_no | Yes |
currency | currency | Yes |
amount | amount | Yes |
product_info | product_info | Yes |
agent_order_id | agent_order_id | No |
notify_url | Notify _url of payment result | No |
Second, Call the WeChat SDK.
iOS SDK: Download
Android SDK: Download
iOS SDK Docs.: iOS SDK Document of WeChat Cross-border Payment.pdf
Android SDK Docs.: Android SDK Document of WeChat Cross-border Payment.pdf
第三步 / Third/ get order status
After you get back to APP, please call 4.7/ Check Payment Order (or 13/ asynchronous notification ) to get order status.
4.6 / Refund
Request
def refund():
url = HOST + '/refund'
data = dict(
order_no='2017062015040461510',
)
timestamp = str(time.time())
sign = data_sign(data, timestamp, pri_key)
header = HEADER.copy()
header['Signature'] = sign
header['Timestamp'] = timestamp
response = requests.post(url, data, headers=header)
return response.content
Response
{
"data": {
"refund": {
"no": "2017062313110444111557843",
"order_no": "2017062313070231980966651",
"refund_amount": "0.1",
"status": "SUCCESS"
}
},
"meta": {
"message": "Request successful",
"status_code": 200,
"success": true
}
}
Parameter | Description | Required |
---|---|---|
order_no | Order _no | Yes |
refund_amount | Refund _amount | No |
If no refund amount parameter is transferred, then payment will be fully refunded. The returned result is refund info. Refer to appendix 5.2 for the details of data structure of refund.
4.7 / Check Payment Order
Request
def query_order():
url = HOST + '/order'
data = dict(
order_no='xxxx',
)
timestamp = str(time.time())
sign = data_sign(data, timestamp, pri_key)
header = HEADER.copy()
header['Signature'] = sign
header['Timestamp'] = timestamp
response = requests.get(url, data, headers=header)
return response.content
Version1.0 Response
{
"meta": {
"status_code": 200,
"message": "Request successful",
"success": true
},
"data": {
"order": {
"status": "FAIL",
"openid": "oQx43wJiwtsjv8C0lT5Lj7Mw1QZ4",
"trade_type": "JSAPI",
"exchange_rate": "0.8777",
"ip": "47.52.77.110",
"no": "xxxx",
"device_info": "",
"currency": "HKD",
"amount": "1",
"trade_time": "2017-06-22 21:29:47",
"merchant_no": "xx",
"pay_currency": "CNY",
"product_info": "Quickpay - xx Science and Technology Ltd.",
"settle_rate": "1",
"pay_amount": "0.87",
"refund_status": "None",
"refundable_amount": "1"
}
}
}
Version2.0 Response
{
"meta": {"status_code":200,
"message": "Request successful",
"success": true
},
"data": {
"order": {
"status": "FAIL",
"openid":"oQx43wJiwtsjv8C0lT5Lj7Mw1QZ4",
"trade_type": "JSAPI",
"exchange_rate": 0.8777,
"ip": "47.52.77.110",
"no" :"2017062221294656822821341",
"device_info": "",
"currency": "HKD",
"amount": 1,
"trade_time": "2017-06-22 21:29:47",
"merchant_no":"test-mer",
"pay_currency": "CNY",
"product_info": "Quickpay - xx Science and Technology Ltd",
"pay_amount": 0.877
},
"refunds": [
{
"no":"2017073101xxxxx",
"order_no": "20170731xxxx",
"refund_amount":50,
"status":"SUCCESS"
},{
"no":"2017073101xxxxx",
"order_no": "20170731xxxx",
"refund_amount":50,
"status":"SUCCESS"
}
]
}
Parameter | Description | Required |
---|---|---|
order_no | Payment Order No. | Yes |
agent_order_id | Agent Order No. | No |
Get order Info by order No. or agent order ID. Either of them is required.
4.8 / Check Refund Order
Request
def query_refund():
url = HOST + '/refund'
data = dict(
refund_no="2017073101xxxxx",
)
timestamp = str(time.time())
sign = data_sign(data, timestamp, pri_key)
header = HEADER.copy()
header['Signature'] = sign
header['Timestamp'] = timestamp
response = requests.get(url, data, headers=header)
return response.content
Response
{
"meta": {
"status_code": 200,
"message": "Request successful",
"success": true
},
"data": {
"info": {
"no":"2017073101xxxxx"
"order_no": "20170731xxxx",
"refund_amount": "100",
"status": "SUCCESS"
}
}
}
Parameter | Description | Required |
---|---|---|
refund_no | Refund Order No. | No |
order_no | Payment Order No. | No |
agent_order_id | Agent Order No. | No |
At least one parameter is required. |
If you choose to transfer the refund No., see the response on the right. |
If you choose to transfer the order No. or agent order ID, see the response below: |
|
4.9 /Check Exchange Rate
Request
def query_rate():
url = HOST + '/rate'
data = dict(
merchant_no='xxx',
currency='USD',
)
timestamp = str(time.time())
sign = data_sign(data, timestamp, pri_key)
header = HEADER.copy()
header['Signature'] = sign
header['Timestamp'] = timestamp
response = requests.get(url, data, headers=header)
return response.content
Response
{
"data": {
"currency": "USD",
"rate": "6.8575"
},
"meta": {
"message": "Request successful",
"status_code": 200,
"success": true
}
}
Parameter | Description | Required |
---|---|---|
merchant_no | merchant_no | Yes |
currency | currency | Yes |
5 / Payment (WeChat Wallet in HK)
It applies to collecting payment from WeChat Wallet in HK
5.1 / Vendors scan payers’ QR code to collect money
Currently ‘’quick pay’’ is the only way supported by WeChat to collect money from WeChat wallet in HK, , which means that it’s available for offline collection only.
For Develop DOCs, please refer to 4.2/ Vendors scan payers’ QR code to collect payment for Develop Docs.
5.2 / Refund
It is same to WeChat Wallet in China Mainland. Please refer to 4.6 / refund for Develop Docs.
5.3 /Check Payment Order
It is same to WeChat Wallet in China Mainland. Please refer to 4.7 / Check Payment Order.
5.4 / Check Refund Order
It is same o WeChat Wallet in China Mainland. Please refer to 4.8 / Check Refund Order
6 / Payment (Alipay Online Payment)
6.1 / Payer scans QR Code shown by vendors to pay
Scanned-Pay means that merchant requests this API to get payment information and QR code url and generate a transaction QR Code on their PC, then customer scan this QR code to complete the transaction.
Request
def scanned_pay():
url = HOST + '/alipay/scanned_pay'
data = dict(
merchant_no='xxx',
currency='HKD',
amount='100',
subject='Product Info'
)
timestamp = str(time.time())
sign = data_sign(data, timestamp, pri_key)
header = HEADER.copy()
header['Signature'] = sign
header['Timestamp'] = timestamp
response = requests.post(url, data, headers=header)
return response.content
Response
{
"meta": {
"status_code": 200,
"message": "Request successful",
"success": true
},
"data": {
"code_url": "https://mapi.alipay.com/gateway.do?_input_charset=UTF-8&body=for+test¤cy=HKD&out_trade_no=2018020810241642236276717&partner=2088021966645500&payment_inst=ALIPAYCN&product_code=NEW_WAP_OVERSEAS_SELLER&qr_pay_mode=4&qrcode_width=200&service=create_forex_trade&subject=wisecasheir+test&total_fee=0.10&sign=X0UzNA4Ygd%2FY5jLL9Dm8069pMUaWTAOiGwY1N1ihdSxjb6uKFu970y7Z8SI%2FptovMYanGRhgbzAMjBNsVCSNQGZSgSsBJf%2BI9GPmsNydLwXP2rGzFiMA0hUnL9uj25AASrNYtsVF%2Be%2BeZuafJwXbEj%2BK%2FHo8KoUA%2F0eay4DvQ8g%3D&sign_type=RSA",
"order": {
"status": "INIT",
"trade_type": "NATIVE",
"payment_no": "2017062312381442716795237",
"currency": "HKD",
"amount": "100",
"merchant_no": "xxx",
"outer_order_no": "xxxx",
"trade_time": "xxxxx",
"subject": "Product Info",
"exchange_rate": "0.8789"
}
}
}
Parameter | Description | Required |
---|---|---|
merchant_no | Merchant _no | Yes |
currency | currency | Yes |
amount | amount | Yes |
subject | Product Information | Yes |
notify_url | Notify _url of payment result | No |
out_order_no | Agent Order No. | No |
The response is in json format, and the content of data includes the following two parts:
- code_url: it is used to generate QR code. When merchants get this url, please generate QR code on the devices, then customers scan the QR code to pay.
- order: see below for the details of payment and data structure of order.
Field | Description |
---|---|
payment_no | payment order no. |
merchant_no | merchant_no |
currency | currency. Refer to 6.3 for supported currencies |
amount | amount |
exchange_rate | exchange rate here refers to the rate at which one currency is exchanged for RMB |
subject | Product Description |
product_info | Product info |
trade_type | Trade _type |
trade_time | trade_ time |
out_order_no | Agent Order No. |
status | Payment status,INIT :to be pay;PAID :payment successful;FAIL :payment failed; EXPIRED: payment invalid |
pay_method | Pay _method |
6.2 / In -APP Payment
In -APP payment refers to that customers call Alipay in merchant’ app. There are three steps:
- App request API 6.2.1 to get prepay _string.
- Use prepay _string to call SDK (6.2.2) to call Alipay.
- Server end completes the transaction by payment order checking (6.3) or Asynchronous Notification(13.1).
6.2.1 / Obtain prepay _string
Response
{
"meta": {
"status_code": 200,
"message": "Request successful",
"success": true
},
"data": {
"prepay_string":"_input_charset=\"utf-8\"&body=\"fortest\"¤cy=\"HKD\"&forex_biz=\"FP\"&out_trade_no=\"2018022322365133840xxxx74\"&partner=\"208882182xxxx743\"&payment_type=\"1\"&seller_id=\"208882182xxxx743\"&service=\"mobile.securitypay.pay\"&subject=\"wisecasheirtest\"&total_fee=\"0.10\"&sign=\"Dld8ki9s26LB6s0UgJpX6ItU7AR5SAIcoCTbSxcl34Ka1mvrtRPZNyLfiHtGmhCzrPGU7WnZ12P%2BV1bS8EftQXMhHJbw07SG6apnHwNMjAHSFgGaZ78k8prlJfWwggMgks1TxN6MNrF2FPMQvsHGpzG1dLqgbdNlKGGe7uW1VBnFSgLtJWjTBFO3ceYtMIOcUPLON1uKu0Z%2F0NcsNdWQIu03yiqU2tgik9XthCTOmVYh6mFSocL9Q87SXL9fgfSrPEUPS%2FHb%2BNHhosKckc3%2BESXYfiRsKoQmos%2FU7vbuYoJSXCkW68r2T1gC3m2Ltfcn45W4Wro5JgcOlUD3FFf%2BRg%3D%3D\"&sign_type=\"RSA\"",
"order": {
"status": "INIT",
"trade_type": "NATIVE",
"payment_no": "201706231238144271679XXX",
"currency": "HKD",
"amount": "100",
"merchant_no": "xxx",
"outer_order_no": "xxxx",
"trade_time": "xxxxx",
"subject": "Product Info",
"exchange_rate": "0.8789"
}
}
}
Parameter | Description | Required |
---|---|---|
merchant_no | merchant_no | Yes |
currency | currency | Yes |
amount | amount | Yes |
subject | Product Info | Yes |
notify_url | Notify _url of payment result | No |
out_order_no | Agent Order No. | No |
The response is in json format, and this data includes two parts.
- perpay_string: it is used to request SDK call.
- order: see below for payment details and data structure.
Field | Description |
---|---|
payment_no | Payment _no |
merchant_no | Merchant _no |
currency | currency,Refer to 6.3 for supported currencies |
amount | amount |
exchange_rate | exchange rate here refers to the rate at which one currency is exchanged for RMB |
subject | Product description |
product_info | Product description |
trade_type | Trade _type |
trade_time | Trade _time |
out_order_no | Agent Order No. |
status | Payment status,INIT :to be pay;PAID :payment successful;FAIL :payment failed; EXPIRED: payment invalid |
pay_method | Payment method |
6.2.2 / obtain and call SDK
iOS-SDK: Download
Android-SDK:Download
iOS-DEMO-SRC: Download
Android-DEMO:Download
Android-DEMO-SRC:Download
iOS:
iOS SDK Document of Alipay Cross-border Payment: Download
Android:
Call payment
API Name: payTask
Method Name:payTask.pay
Method Prototype:PayTask payTask = new PayTask(activity); payTask.pay(prepay_string, true);
Method Function:payTask.pay provides merchants with order payment function.
Method Parameters: Instantiate PayTask, and transfer instance of parameter activity
Parameter | Description |
---|---|
String prepay_string | get prepay _string from the previous step |
boolean isShowPayLoading | User clicks PAY in merchants’ App, and sets “need a loading before calling wallet” as “true, then a loading will be called when user is calling the API of payment. The loading won’t disappear until the H5 payment interface is called (we strongly recommend setting “need a loading before calling wallet” as “true” so that customers can get better experience. ) |
Returned result:
Response
resultStatus={9000};memo={};
result={partner="2088101568358171"&out_trade_no="0819145412-6177"&
subject="test"&body="testtest"&total_fee="0.01"&
notify_url="http://notify.msp.hk/notify.htm"
&service="mobile.securitypay.pay"&payment_type="1"&_input_charset="utf-8"
&it_b_pay="30m"&success="true"&sign_type="RSA"
&sign=".../3cr3UwmEV4L3Ffir/02RBVtU=..."}
When the returned results are resultStatus =9000, and success= “true”, payment is successful. But this result is unreliable. The result of calling 6.3 or 13.1 by server shall be the final result of successful payment.
6.3 /WAP Payment
WAP payment means that user uses Alipay to pay money on the H5 page of their mobile terminal. This payment method involves three steps:
- Merchant requests the following API in the server side.
-Lead customers to jump to the returned url of API to complete the payment.
- 3. Return _url will be returned after payment, merchants can get payment status by active query or asynchronous notification.
Request
def scanned_pay():
url = HOST + '/alipay/wap_pay'
data = dict(
merchant_no='xxx',
currency='HKD',
amount='100',
subject='Product Info'
)
timestamp = str(time.time())
sign = data_sign(data, timestamp, pri_key)
header = HEADER.copy()
header['Signature'] = sign
header['Timestamp'] = timestamp
response = requests.post(url, data, headers=header)
return response.content
Response
{
"meta": {
"status_code": 200,
"message": "Request successful",
"success": true
},
"data": {
"url": "https://mapi.alipay.com/gateway.do?_input_charset=UTF-8&body=for+test¤cy=HKD&out_trade_no=2018020810241642236276717&partner=2088021966645500&payment_inst=ALIPAYCN&product_code=NEW_WAP_OVERSEAS_SELLER&qr_pay_mode=4&qrcode_width=200&service=create_forex_trade&subject=wisecasheir+test&total_fee=0.10&sign=X0UzNA4Ygd%2FY5jLL9Dm8069pMUaWTAOiGwY1N1ihdSxjb6uKFu970y7Z8SI%2FptovMYanGRhgbzAMjBNsVCSNQGZSgSsBJf%2BI9GPmsNydLwXP2rGzFiMA0hUnL9uj25AASrNYtsVF%2Be%2BeZuafJwXbEj%2BK%2FHo8KoUA%2F0eay4DvQ8g%3D&sign_type=RSA",
"order": {
"status": "INIT",
"trade_type": "NATIVE",
"payment_no": "2017062312381442716795237",
"currency": "HKD",
"amount": "100",
"merchant_no": "xxx",
"outer_order_no": "xxxx",
"trade_time": "xxxxx",
"subject": "Product Info",
"exchange_rate": "0.8789"
}
}
}
Parameter | Description | Required |
---|---|---|
merchant_no | Merchant _no | Yes |
currency | currency | Yes |
amount | amount | Yes |
subject | Product Information | Yes |
notify_url | Notify _url of payment result | No |
out_order_no | Agent Order No. | No |
return_url | Return-url | Yes |
The returned data is in json format. There are two parts in the data
- url: lead customers to jump to this url, and they will get access to the transferred return _url.
- order: see below for payment details and data structure details.
Field | Description |
---|---|
payment_no | Payment _no |
merchant_no | Merchant _no |
currency | currency,Refer to 6.3 for supported currencies |
amount | amount |
exchange_rate | exchange rate here refers to the rate at which one currency is exchanged for RMB |
subject | Product Description |
product_info | Product Description |
trade_type | Trade _type |
trade_time | Trade _time |
out_order_no | Agent Order No. |
status | Payment status,INIT :to be pay;PAID :payment successful;FAIL :payment failed; EXPIRED: payment invalid |
pay_method | Payment Method |
6.4 / Check Payment Order
Request
def query_order():
url = HOST + '/alipay/order'
data = dict(
out_order_no='xxxx',
)
timestamp = str(time.time())
sign = data_sign(data, timestamp, pri_key)
header = HEADER.copy()
header['Signature'] = sign
header['Timestamp'] = timestamp
response = requests.get(url, data, headers=header)
return response.content
Repsonse
{
"data": {
"order": {
"amount": "0.10",
"buyer_email": "18624@163.com",
"channel": "ALIPAYCN",
"charge_amount": "0.01",
"currency": "HKD",
"exchange_rate": "0.804740",
"merchant_no": "test-mer",
"payment_no": "2018020716122408862056356",
"buyer_id": "2088702631783753",
"pay_amount": "0.08",
"pay_currency": "CNY",
"product_info": "for test",
"refund_status": "None",
"refundable_amount": "0.10",
"status": "PAID",
"subject": "wisecasheir test",
"trade_time": "2018-02-07 16:12:24",
"trade_type": "NATIVE",
"out_order_no": "2018020721001003750533954072"
}
},
"meta": {
"message": "Requset Successes",
"status_code": 200,
"success": true
}
}
Parameter | Description | Required |
---|---|---|
payment_no | Payment Order No. | No |
out_order_no | Agent Order No. | No |
Get order Info by order No. or agent order ID. Either of them is required.
Parameter | Description |
---|---|
payment_no | Payment order no |
merchant_no | Merchant _no |
buyer_email | buyer Email |
buyer_id | buyer id |
currency | Currency. Refer to 6.3 for supported currencies |
amount | amount |
exchange_rate | exchange rate here refers to the rate at which one currency is exchanged for RMB |
subject | Product Description |
product_info | Product Description |
trade_type | Trade _type |
trade_time | Trade _time |
out_order_no | Agent Order No. |
status | Payment status,INIT :to be pay;PAID :payment successful;FAIL :payment failed; EXPIRED: payment invalid |
pay_method | Payment Method |
refund_status | Refund Status. NONE :No refund;PART :Partial Refund;FULL :Fully Refund |
refundable_amount | Refundable _amount |
6.5 / Refund
Request
def refund():
url = HOST + '/alipay/refund'
data = dict(
payment_no ='2017062015040461510',
)
timestamp = str(time.time())
sign = data_sign(data, timestamp, pri_key)
header = HEADER.copy()
header['Signature'] = sign
header['Timestamp'] = timestamp
response = requests.post(url, data, headers=header)
return response.content
Response
{
"data": {
"refund": {
"refund_no": "2017062313110444111557843",
"payment_no": "2017062313070231980966651",
"refund_amount": "0.1",
"status": "SUCCESS"
}
},
"meta": {
"message": "Request successful",
"status_code": 200,
"success": true
}
}
Parameter | Description | Required |
---|---|---|
payment_no | Payment order no | Yes |
refund_amount | Refund_amount | No |
If no refund amount parameter transferred, then payment will be fully refunded. The returned result is refund info.
Field | Description |
---|---|
payment_no | Payment _no |
refund_no | Refund _no |
refund_amount | Refund _amount |
status | Refund status |
6.6 / Check Refund Order
Request
def query_refund():
url = HOST + '/alipay/refund'
data = dict(
refund_no="2017073101xxxxx",
)
timestamp = str(time.time())
sign = data_sign(data, timestamp, pri_key)
header = HEADER.copy()
header['Signature'] = sign
header['Timestamp'] = timestamp
response = requests.get(url, data, headers=header)
return response.content
Response
{
"meta": {
"status_code": 200,
"message": "Request successful",
"success": true
},
"refund": {
"no":"2017073101xxxxx"
"order_no": "20170731xxxx",
"refund_amount": "100",
"status": "SUCCESS"
}
}
Parameter | Description | Required |
---|---|---|
refund_no | Refund _no | Yes |
The returned result is refund information:
Field | Description |
---|---|
payment_no | payment order no |
refund_no | refund_no |
refund_amount | refund_amount |
status | refund status |
6.7 / Check Exchange Rate
This API returns the referred exchange rate between requested currency and RMB, but the actual exchange rate depends on the real-time exchange rate.
Request
def query_refund():
url = HOST + '/alipay/rate'
data = dict(
currency="HKD",
)
timestamp = str(time.time())
sign = data_sign(data, timestamp, pri_key)
header = HEADER.copy()
header['Signature'] = sign
header['Timestamp'] = timestamp
response = requests.get(url, data, headers=header)
return response.content
Response
{
"meta": {
"status_code": 200,
"message": "request successful",
"success": true
},
"rate": {
"currency": "HKD",
"rate": "0.860000"
}
}
Parameters | Description | Required |
---|---|---|
currency | currency | Yes |
the returned results are:
Field | Description |
---|---|
currency | Order No. |
rate | rate |
7 / Payment (Alipay Offline Payment)
7.1 / Payer scans dynamic QR Code shown by vendors to pay
Dynamic QR Code Payment refers to that merchant gets a QR code by requesting the API below for customer to scan using his/her Alipay app to complete payment. This includes 3 steps:
Merchant gets a QR code by requesting the API below on the server side
Merchant shows the QR code to customer and customer scans the code by using their Alipay app
Server obtains payment result through active query or asynchronous notification
Request
def scanned_pay():
url = HOST + '/alipay/qrcode_pay'
data = dict(
merchant_no='xxx',
currency='HKD',
amount='100',
subject='product info'
)
timestamp = str(time.time())
sign = data_sign(data, timestamp, pri_key)
header = HEADER.copy()
header['Signature'] = sign
header['Timestamp'] = timestamp
response = requests.post(url, data, headers=header)
return response.content
Response
{
"meta": {
"status_code": 200,
"message": "request successful",
"success": true
},
"data": {
"qrcode": "https://qr.alipay.com/bax04448a1pogrhduko280d3",
"order": {
"status": "INIT",
"trade_type": "NATIVE",
"payment_no": "2017062312381442716795237",
"currency": "HKD",
"amount": "100",
"merchant_no": "xxx",
"outer_order_no": "xxxx",
"trade_time": "xxxxx",
"subject": "product info",
"exchange_rate": "0.8789"
}
}
}
Parameter | Description | Required |
---|---|---|
merchant_no | Merchant No. | Yes |
currency | currency | Yes |
amount | amount | Yes |
subject | product info. | Yes |
notify_url | notify URL of payment result | No |
out_order_no | agent order No. | No |
The returned data is in JSON format and includes 2 parts:
- qrcode: merchant generates a qr code by using parameters above
- order: payment order details; data structure details are as follows:
Field | Description |
---|---|
payment_no | payment No. |
merchant_no | merchant No. |
currency | currency,see appendix 6.3 for supported currencies |
amount | amount |
exchange_rate | exchange rate here refers to the rate at which one currency is exchanged for RMB |
subject | product description |
product_info | product description |
trade_type | trade type |
trade_time | trade time |
out_order_no | agent No. |
status | order status,INIT :to be paid;PAID :payment successful;FAIL :payment failed; EXPIRED: invalid payment order |
pay_method | payment method |
7.2 / Quick Pay Vendors scan payers’ QR code to collect
can QR Code to Collect Payment refers to that merchant scans customer’s QR code on their Alipay app by a scanner or other scanning tools, and then request the API below through the QR code to complete payment. This includes 3 steps:
-Merchant uses a scanner or other scanning tools to scan the QR code on customer’s Alipay app -Merchant requests the API below through the QR code -Server obtains payment result according to synchronously returned result or asynchronous notification
Request
def scanned_pay():
url = HOST + '/alipay/scan_pay'
data = dict(
merchant_no='xxx',
currency='HKD',
amount='100',
auth_code='123456',
subject='product info'
)
timestamp = str(time.time())
sign = data_sign(data, timestamp, pri_key)
header = HEADER.copy()
header['Signature'] = sign
header['Timestamp'] = timestamp
response = requests.post(url, data, headers=header)
return response.content
Response
{
"meta": {
"status_code": 200,
"message": "request successful",
"success": true
},
"data": {
"order": {
"status": "INIT",
"trade_type": "NATIVE",
"payment_no": "2017062312381442716795237",
"currency": "HKD",
"amount": "100",
"merchant_no": "xxx",
"outer_order_no": "xxxx",
"trade_time": "xxxxx",
"subject": "product info",
"exchange_rate": "0.8789"
}
}
}
Parameter | Description | Required |
---|---|---|
merchant_no | merchant No. | Yes |
auth_code | QR code of Alipay | Yes |
currency | currency | Yes |
amount | amount | Yes |
subject | product info. | Yes |
notify_url | notify URL of payment result | No |
out_order_no | agent order No. | No |
The return date is in JSON format
order: payment order details; data structure details are as follows:
Field | Description |
---|---|
payment_no | order No. |
merchant_no | merchant No. |
currency | currency, please see supported currencies in Appendix 6.3 |
amount | amount |
exchange_rate | exchange rate here refers to the rate at which one currency is exchanged for RMB |
subject | product description |
product_info | product description |
trade_type | trade type |
trade_time | trade time |
out_order_no | agent No. |
status | order status,INIT :to be paid;PAID :payment successful;FAIL :payment failed; EXPIRED: invalid payment order |
pay_method | payment method |
7.3 / Refund
Same to that of Alipay online payment. Please refer to 6.5 / Refund for Develop Docs
7.4 / Check Payment Order
Same to that of Alipay Online Payment. Please refer to 6.4 / Check Payment Order for Develop Docs
7.5 / Check Refund Order
Same to that of Alipay Online Payment. Please refer to 6.6 / Check Refund Order for Develop Docs.
8 / Merchant
8.1 / Create Merchant Account
Response
{
"data": {
"merchant": {
"account": "123@123.com",
"country_code": "HKG",
"is_sub_merchant": 1,
"name": "for test put",
"no": "SM5a5f1d19b6b15",
"parent_merchant_no": "WC5985cd2280082",
"remark": "test put remark",
"settle_currency": "HKD",
"settled_balance": "189000.00",
"short_name": "test put",
"unsettled_balance": "0"
}
},
"meta": {
"message": "Requset Successes",
"status_code": 200,
"success": true
}
}
At HipoPay, merchant account can be divided into 2 categories: one is merchant account which is created for the other part to the contract, namely the real merchant; the other is virtual account, also defined as sub-account in this document, which actually is set up for the convenience of separate financial management of the real merchant. Among them, a virtual account is an affiliate to a merchant account (Unless specifically stated in this document, sub-account refers to virtual account). Presently, we only allow to create virtual account since merchant account can only be set up after signing the contract. Virtual account can be used to receive money transfer from other merchants but can’t be used to collect payment. The following are parameters of posting a virtual account:
Parameter | Description | Required |
---|---|---|
name | (sub) merchant name | Yes |
short_name | abbreviation of (sub) merchant name | Yes |
country_code | country of (sub) merchant | Yes |
settle_currency | settlement currency | Yes |
parent_merchant_no | parent merchant No. | Yes |
account | saas login account which must be an email address | Yes |
password | sass login password | Yes |
remark | remark | Yes |
Description of returned parameters:
Parameter | Description |
---|---|
no | merchant No. |
parent_merchant_no | parent merchan No. |
account | account |
name | merchant name |
short_name | abbreviation of merchant name |
country_code | registered country code |
is_sub_merchant | sub- merchant or not |
settle_currency | settlement currency |
settled_balance | settled balance |
unsettled_balance | unsettled balance |
remark | remark |
8.2 / Check Merchant Information
Response
{
"data": {
"merchant": {
"account": "123@123.com",
"country_code": "HKG",
"is_sub_merchant": 1,
"name": "for test put",
"no": "SM5a5f1d19b6b15",
"parent_merchant_no": "XXXXXXXX",
"remark": "test put remark",
"settle_currency":test put",
"unsettled_balance": "0"
}
},
"meta": {
"message": "Requset Successes",
"status_code": 200,
"success": true
}
}
Account information, be that of a merchant account or a virtual account, can be obtained through the API. Enter a merchant account No. and the response is all the merchant-related information.
Parameter | Description | Required |
---|---|---|
merchant_no | merchant No or sub-merchant No. | Yes |
Description of returned parameters :
Parameter | Description |
---|---|
no | merchant No. |
parent_merchant_no | parent merchant No. |
account | account |
name | merchant name |
short_name | abbreviation of merchant name |
country_code | registered country code |
is_sub_merchant | sub-merchant or not |
settle_currency | settlement currency |
settled_balance | settled balance |
remark | remark |
8.3 / Update Merchant Information
Response
{
"data": {
"merchant": {
"account": "123@123.com",
"country_code": "HKG",
"is_sub_merchant": 1,
"name": "for test put",
"no": "SM5a5f1d19b6b15",
"parent_merchant_no": "XXXXXXXX",
"remark": "test put remark",
"settle_currency": "HKD",
"settled_balance": "189000.00",
"short_name": "test put",
"unsettled_balance": "0"
}
},
"meta": {
"message": "Requset Successes",
"status_code": 200,
"success": true
}
}
Presently, information of merchant account can’t be updated through the API. As for sub-account, only its name and the abbreviation of name can be updated through the API. If any attributes of a sub-account need to be updated, please delete the account and create a new one.
Parameter | Description | Required |
---|---|---|
merchant_no | Sub-merchant No | Yes |
name | merchant name | No |
short_name | abbreviation of merchant name | No |
Description of the returned parameters::
Parameter | Description |
---|---|
no | merchant No. |
parent_merchant_no | parent merchant No. |
account | account |
name | merchant name |
short_name | abbreviation of merchant name |
country_code | registered country code |
is_sub_merchant | sub-merchant or not |
settle_currency | settlement currency |
settled_balance | settled balance |
unsettled_balance | unsettled balance |
remark | remark |
8.4 /Delete Merchant Account
Response
{
"data": {},
"meta": {
"message": "Requset Successes",
"status_code": 200,
"success": true
}
}
Presently, only sub-account can be deleted through the API.
But when there is any balance in the account, it can’t be deleted directly. To force delete the account, you have to set force=YES. Balance in the account will be cleared after force deleting account. Please note the risk of parameter in this case.
Parameter | Description | Required |
---|---|---|
merchant_no | submerchant No. | Yes |
force | force delete, choose NO to make default force delete | No |
8.5 / Check Merchant List
Response
{
"data": {
"merchant": [
{
"account": "123@123.com",
"country_code": "HKG",
"is_sub_merchant": 1,
"name": "for test put",
"no": "SM5a5f1d19b6b15",
"parent_merchant_no": "XXXXXX",
"remark": "test put remark",
"settle_currency": "HKD",
"settled_balance": "189000.00",
"short_name": "test put",
"unsettled_balance": "0"
},
{
"account": "1234@1234.com",
"country_code": "HKG",
"is_sub_merchant": 1,
"name": "test 2",
"no": "SM5a6206fb392ff",
"parent_merchant_no": "XXXXX",
"remark": "",
"settle_currency": "HKD",
"settled_balance": "0",
"short_name": "test 2",
"unsettled_balance": "0"
}
]
},
"meta": {
"message": "Requset Successes",
"status_code": 200,
"success": true
}
}
To get a list of a merchant’s sub-accounts, you have to enter its Merchant No. using API and the response is a list of all its sub-accounts.
Parameter | Description | Required |
---|---|---|
merchant_no | merchant No. | Yes |
Description of Returned parameters:
Parameter | Description |
---|---|
no | merchant No. |
parent_merchant_no | parent merchant No. |
account | account |
name | merchant name |
short_name | abbreviation of merchant name |
country_code | registered country code |
is_sub_merchant | sub-merchant or not |
settle_currency | settlement currency |
settled_balance | settled balance |
unsettled_balance | unsettled balance |
remark | remark |
9 / SettleAccount (Settlement Account)
9.1 / Create Settlement Account
Response
{
"data": {
"settle_account": {
"account": "12345678",
"account_name": "test card",
"address": "SC chengdu",
"bank": "no bank",
"branch": "no branch",
"country_code": "HKG",
"currency_codes": "HKG,CNY",
"no": "5a620ade49aec",
"status": "INIT",
"swift_code": "HKGHKHKHKHK"
}
},
"meta": {
"message": "Requset Successes",
"status_code": 200,
"success": true
}
}
Currently adding merchant’s settlement account is not supported by this API. The API is only available for adding merchant’s sub-account. Refer to 14.3 for currency code.
Parameter | Description | Required |
---|---|---|
merchant_no | sub-merchant No. | Yes |
account | bank account (account No.) | Yes |
account_name | account name | Yes |
bank | bank | Yes |
branch | branch | Yes |
swift_code | swift_code | Yes |
currency_codes | supported currencies, separated with “,” | Yes |
address | address | Yes |
Description of returned parameters:
Parameter | Description |
---|---|
no | account No. |
account | account No. |
account_name | account name |
country_code | country code of bank |
bank | bank |
branch | branch |
address | adress |
currency_codes | supported currencies |
status | status |
swift_code | swift code |
9.2 / Check Settlement Account
Response
{
"data": {
"settle_account": {
"account": "12345678",
"account_name": "test card",
"address": "SC chengdu",
"bank": "no bank",
"branch": "no branch",
"country_code": "HKG",
"currency_codes": "HKG,CNY",
"no": "5a620ade49aec",
"status": "INIT",
"swift_code": "HKGHKHKHKHK"
}
},
"meta": {
"message": "Requset Successes",
"status_code": 200,
"success": true
}
}
Input” settle _account _no.’’, and the response will be a settlement account.
Parameter | Description | Required |
---|---|---|
settle_account_no | settlement account No. | Yes |
Description of returned parameters:
Parameter | Description |
---|---|
no | account No. |
account | account No. |
account_name | account name |
country_code | country code of bank |
bank | bank |
branch | branch |
address | address |
currency_codes | supported currecies |
status | status |
swift_code | swift code |
9.3 / Check Settlement Account List
Check the settlement accounts bound to merchants or merchant’s sub-accounts.
Parameter | Description | Required |
---|---|---|
merchant_no | merchant No. or sub-merchant No. | Yes |
Description of returned parameters:
Parameter | Description |
---|---|
no | account No. |
account | account |
account_name | account name |
country_code | country code of bank |
bank | bank |
branch | branch |
address | address |
currency_codes | supported currencies |
status | status |
swift_code | swift code |
Response
{
"data": {
"settle_account": [
{
"account": "12345678",
"account_name": "test card",
"address": "SC chengdu",
"bank": "no bank",
"branch": "no branch",
"country_code": "HKG",
"currency_codes": "HKG,CNY",
"no": "5a5f7f5ab3c24",
"status": "INIT",
"swift_code": "HKGHKHKHKHK"
},
{
"account": "12345678",
"account_name": "test card",
"address": "SC chengdu",
"bank": "no bank",
"branch": "no branch",
"country_code": "HKG",
"currency_codes": "HKG,CNY",
"no": "5a5f7f84939c7",
"status": "INIT",
"swift_code": "HKGHKHKHKHK"
}
]
},
"meta": {
"message": "Requset Successes",
"status_code": 200,
"success": true
}
}
10 / Withdrawal (Withdrawal)
10.1 / Create Withdrawal
Response
{
"data": {
"withdrawal": {
"forex_rate": 7.8409,
"gst": 0.00,
"no": "2018011923161675515520294",
"service_fee": 6.00,
"source_amount": 1000.00,
"source_currency": "HKD",
"status": "INIT",
"target_amount": 69.37,
"target_currency": "USD",
"withdrawal_fee": 450.00
}
},
"meta": {
"message": "Requset Successes",
"status_code": 200,
"success": true
}
}
Funds in a merchant account can be settled to the merchant’s settlement account in other currencies. Please see currency code in 14.3/ Currency Code.
Parameter | Description | Required |
---|---|---|
merchant_no | merchant No. or sub-merchant No. | Yes |
source_amount | withdrawal amount | Yes |
source_currency | source currency | Yes |
target_currency | target currency | Yes |
settle_account_no | settlement account No. | Yes |
Description of Returned Parameters:
Parameter | Description |
---|---|
no | Withdrawal No. |
forex_rate | account No. |
gst | goods and services tax, only applicable to New Zealand |
service_fee | service fee |
source_amount | settlement amount |
source_currency | settlement currency |
target_amount | target amount |
target_currency | target currency |
withdrawal_fee | withdrawal fee |
status | status |
10.2 / Check Withdrawal
Response
{
"data": {
"withdrawal": {
"forex_rate": 7.8409,
"gst": 0,
"no": "2018011923161675515520294",
"service_fee": 6.00,
"source_amount": 1000.00,
"source_currency": "HKD",
"status": "INIT",
"target_amount": 69.37,
"target_currency": "USD",
"withdrawal_fee": 450
}
},
"meta": {
"message": "Requset Successes",
"status_code": 200,
"success": true
}
}
Check withdrawal status by entering withrawal No., namely, input withdrawal No. and withdrawal status will be output.
withdrawal status | Description | Required |
---|---|---|
withdrawal_no | withdrawal No. | Yes |
Description of returned parameters:
Parameter | Description |
---|---|
no | Withdrawal No. |
forex_rate | rate |
gst | Goods and Services Tax, only applicable to New Zealand |
service_fee | service fee |
source_amount | settlement amount |
source_currency | settlement currency |
target_amount | target amount |
target_currency | target currency |
withdrawal_fee | target currency |
status | status |
10.3 / Check Withdrawal List
Parameter | Description | Required |
---|---|---|
merchant_no | merchant No. or sub-merchant No. | Yes |
date | date: YYYY-MM-DD | Yes |
Response
{
"data": {
"withdrawal": [
{
"forex_rate": 7.8409,
"gst": 0,
"no": "2018011922052090560811376",
"service_fee": 6.00,
"source_amount": 1000.00,
"source_currency": "HKD",
"status": "INIT",
"target_amount": 69.37,
"target_currency": "USD",
"withdrawal_fee": 450
},
{
"forex_rate": 7.8409,
"gst": 0,
"no": "2018011922053150790173487",
"service_fee": 6.00,
"source_amount": 1000.00,
"source_currency": "HKD",
"status": "INIT",
"target_amount": 69.37,
"target_currency": "USD",
"withdrawal_fee": 450
}
]
},
"meta": {
"message": "Requset Successes",
"status_code": 200,
"success": true
}
}
Description of returned parameters:
Parameter | Description |
---|---|
no | withdrawal No. |
forex_rate | rate |
gst | Good and Services Tax (only applicable to New Zealand |
service_fee | service fee |
source_amount | settlement amount |
source_currency | settlement currency |
target_amount | target amount |
target_currency | target currency |
withdrawal_fee | withdrawal fee |
status | status |
11 / Transfer (Transfer)
11.1 / Create Transfer Order
Funds in a merchant account can be transferred to the merchant’s sub-account or other merchant accounts in other currencies. Please see currency code in 14.3 /currency code.
Parameter | Description | Required |
---|---|---|
source_merchant_no | merchant No. or sub-merchant No. | Yes |
source_amount | transfer amount | Yes |
target_merchant_no | target merchant No. | Yes |
target_merchant_name | target merchant name | Yes |
remark | remark | No |
Response
{
"data": {
"transfer": {
"forex_rate": 1,
"no": "TS2018012122391005986366833",
"remark": "test transfer",
"source_amount": 1000,
"source_currency": "HKD",
"source_merchant_no": "SM5a5f1d19b6b15",
"status": "INIT",
"target_amount": 1000.00,
"target_currency": "HKD",
"target_merchant_name": "test 2",
"target_merchant_no": "SM5a6206fb392ff",
"time": "2018-01-21 12:39:10"
}
},
"meta": {
"message": "Requset Successes",
"status_code": 200,
"success": true
}
}
Description of Returned Parameters:
Parameter | Parameter |
---|---|
no | withdrawal No. |
forex_rate | rate |
source_merchant_no | withdrawal No. |
source_amount | settlement amount |
source_currency | settlement currency |
target_merchant_no | target merchant No. |
target_amount | received amount |
target_currency | received currency |
target_merchant_name | target merchant name |
status | status |
remark | remark |
time | time |
11.2 / Check Transfer Details
Parameter | Description | Required |
---|---|---|
transfer_no | transfer No. | Yes |
Response
{
"data": {
"transfer": {
"forex_rate": 1,
"no": "TS2018012122391005986366833",
"remark": "test transfer",
"source_amount": 1000,
"source_currency": "HKD",
"source_merchant_no": "SM5a5f1d19b6b15",
"status": "SUCCESS",
"target_amount": 1000.00,
"target_currency": "HKD",
"target_merchant_name": "test 2",
"target_merchant_no": "SM5a6206fb392ff",
"time": "2018-01-21 12:39:10"
}
},
"meta": {
"message": "Requset Successes",
"status_code": 200,
"success": true
}
}
Description of Returned Parameters:
Parameter | Description |
---|---|
no | withdrawal No. |
forex_rate | rate |
source_merchant_no | source merchant No. |
source_amount | settlement amount |
source_currency | settlement currency |
target_merchant_no | target merchant No. |
target_amount | received amount |
target_currency | received currency |
target_merchant_name | target merchant name |
status | status |
remark | remark |
time | time |
11.3 / Check the List of Transfer
Parameter | Description | Required |
---|---|---|
merchant_no | merchant No. | Yes |
date | date: YYYY-MM-DD | Yes |
Response
{
"data": {
"transfer": [
{
"forex_rate": 1,
"no": "TS2018012122391005986366833",
"remark": "test transfer",
"source_amount": 1000,
"source_currency": "HKD",
"source_merchant_no": "SM5a5f1d19b6b15",
"status": "SUCCESS",
"target_amount": 1000.00,
"target_currency": "HKD",
"target_merchant_name": "test 2",
"target_merchant_no": "SM5a6206fb392ff",
"time": "2018-01-21 12:39:10"
},
{
"forex_rate": 1,
"no": "TS2018012122391005986366833",
"remark": "test transfer",
"source_amount": 1000,
"source_currency": "HKD",
"source_merchant_no": "SM5a5f1d19b6b15",
"status": "SUCCESS",
"target_amount": 1000.00,
"target_currency": "HKD",
"target_merchant_name": "test 2",
"target_merchant_no": "SM5a6206fb392ff",
"time": "2018-01-21 12:39:10"
}
]
},
"meta": {
"message": "Requset Successes",
"status_code": 200,
"success": true
}
}
Parameter | Description |
---|---|
no | withdrawal No. |
forex_rate | rate |
source_merchant_no | source merchant No. |
source_amount | settlement amount |
source_currency | settlement currency |
target_merchant_no | target merchant No. |
target_amount | received amount |
target_currency | received currency |
target_merchant_name | target merchant name |
status | status |
remark | remark |
time | time |
12 /Assist API
12.1 / Customs Declaration of WeChat Pay
Parameter | Description | Required |
---|---|---|
out_order_no | merchant order No. | Yes |
payment_no | HipoPay payment No. | Yes |
customs | HS Code (e.g. SHENZHEN) | Yes |
mch_customs_no | merchant HS Code | Yes |
Returned results are as follows:
Parameter | Description |
---|---|
out_order_no | Merchant Order No. |
payment_no | HipoPay payment order No. |
customs | HS Code |
state | UNDECLARED – undeclared SUBMITTED – submitted(The status would be SUBMITTED if a merchant re-submits a transaction order for customs declaration in the customs system having an API for modification.) PROCESSING – processing SUCCESS – successful FAIL– failed EXCEPT –abnormal |
12.2 / Check Customs Declaration of WeChat Pay
Parameter | Description | Required |
---|---|---|
out_order_no | merchant order No. | No |
payment_no | HipoPay payment order No. | No |
Returned results are as follows:
Parameter | Description |
---|---|
out_order_no | merchant order No. |
payment_no | HipoPay payment order No. |
customs | HS Code |
state | UNDECLARED – undeclared SUBMITTED – submitted (The status would be SUBMITTED if a merchant re-submits a transaction order for customs declaration in the customs system having an API for modification.) |
PROCESSING – processing SUCCESS – successful FAIL– failed EXCEPT –abnormal |
12.3 / Customs Declaration of Alipay
Parameter | Description | Required |
---|---|---|
out_order_no | merchant order No. | Yes |
payment_no | HipoPay payment order No. | Yes |
customs | HS Code(e.g. SHENZHEN) | Yes |
mch_customs_no | merchant customs record No. | Yes |
merchant_customs_name | merchant customs record name | Yes |
Returned results are as follows:
Parameter | Description |
---|---|
out_order_no | merchant order No. |
payment_no | HipoPay payment order No. |
customs | HS No. |
state | “SUCCESS” successful “FAIL” failed |
err_detail | state when the description of “state” is FAIL, response describing the reason of being failed will be received |
12.4 /Check Customs Declaration of Alipay
Parameter | Description | Required |
---|---|---|
out_order_no | merchant order No. | No |
payment_no | HipoPay payment order No. | No |
Parameter | Description |
---|---|
out_order_no | merchant order No. |
payment_no | HipoPay payment order No. |
customs | HS Code |
state | “SUCCESS” successful “FAIL” failed |
err_detail | when the description of “state” is FAIL, response describing the reason of being failed will be received |
13 / Payment Notification
13.1 / Rules of Notification
13.2 / Contents of Notification
Field | Description |
---|---|
status | order status,INIT :to be paid;PAID :payment successful ;FAIL :failed; EXPIRED: invalid order |
openid | openID |
trade_type | trade type |
exchange_rate | exchange rate here refers to the rate at which one currency is exchanged for RMB |
no | order No. |
currency | order No. |
amount | amount |
trade_time | trade time |
pay_currency | payment currency |
pay_amount | payment amount |
agent_order_id | agent order No. |
Response
{
"status": "PAID",
"openid": "oQx43wJiwtsjv8C0lT5Lj7Mw1QZ4",
"trade_type": "JSAPI",
"exchange_rate": "0.8777",
"no": "xxxx",
"currency": "HKD",
"amount": "1",
"trade_time": "2017-06-22 21:29:47",
"pay_currency": "CNY",
"pay_amount": "0.87",
"agent_order_id": "xxxx"
}
13.3 / Check Signature
Rules for Creating Query-string Signature:
- Sort all characters in the POST request in ascending alphabetical order (i.e. lexicographical sequence) based on their ASCII encoded names, join them into a signature string via the corresponding URL in key-value format (e.g. key1=value1&key2=value2…)
- Add the timestamp of header to the end of the signature string, enter “,” to separate them and a query-string signature is then created.
- Use SHA-256 to authenticate the query-string signature and the signature included in the header.
- To get the public key, please contact HipoPay.
14 / Appendix
14.1 / Description of Payment Order Data Structure
Field | Description |
---|---|
no | payment order No. |
merchant_no | merchant No. |
currency | currency. refer to appendix 5.3 for supported currencies |
amount | amount |
exchange_rate | exchange rate here refers to the rate at which one currency is exchanged for RMB |
device_info | device info |
product_info | product info |
ip | cashing terminal IP |
product_id | product ID |
trade_type | trade type |
trade_time | trade time |
agent_order_id | agent order No. |
status | payment status,INIT :to be pay;PAID :payment successful;FAIL :payment failed; EXPIRED: payment invalid |
pay_method | payment method |
refund_status | refund status. NONE :No refund;PART :Partial Refund;FULL :Fully Refund |
refundable_amount | refundable amount |
14.2 / Description of Refund Data Structure
Field | Description |
---|---|
no | refund No. |
order_no | payment order No. |
refund_amount | refund amount |
status | refund order status |
14.3 / Currency Code
Currency | Code |
---|---|
CNY | CNY |
GBP | GBP |
HKD | HKD |
USD | USD |
JPY | JPY |
CAD | CAD |
AUD | AUD |
EUR | EUR |
NZD | NZD |
KRW | KRW |
THB | THB |
14.4 / WeChat HS Code
HS Code | Customs Name |
---|---|
GUANGZHOU_ZS | Guangzhou Customs |
GUANGZHOU_HP_GJ | Nansha Entry-Exit Inspection and Quarantine Bureau, P.R. China (Payment orders to be submitted to Huangpu Entry-Exit Inspection and Quarantine Bureau must be both submitted to Guangzhou Customs and Huangpu Entry-Exit Inspection and Quarantine Bureau, that’s to say, these orders must be submitted for customs declaration twice. |
GUANGZHOU_NS_GJ | Nansha Entry-Exit Inspection and Quarantine Bureau, P.R. China (Payment orders to be submitted to Huangpu Entry-Exit Inspection and Quarantine Bureau must be both submitted to Guangzhou Customs and Huangpu Entry-Exit Inspection and Quarantine Bureau, that’s to say, these orders must be submitted for customs declaration twice. |
HANGZHOU_ZS | Hangzhou Customs |
NINGBO | Ningbo Customs |
ZHENGZHOU_BS | Zhengzhou Customs |
CHONGQING | Chongqing Customs |
XIAN | Xi'an Customs |
SHANGHAI_ZS | Shanghai Customs |
SHENZHEN | Shenzhen Customs |
ZHENGZHOU_ZH_ZS | Zhengzhou Customs |
TIANJIN | Tianjing Customs |
BEIJING | Beijing Customs |
14.5 / Alipay HS Code
Customs Name | Overall Customs Declaration Solution | HS Code |
---|---|---|
Hangzhou Customs | push Hangzhou | Hangzhou Customs |
Guangzhou Customs | push Guangzhou | |
Henan Bonded Logistics Center | push Zhengzhou | Zhengzhou |
Zhengzhou Xinzheng Comprehensive Zone | push HENAN for local customs declaration,then push ZONGSHU | HENAN,ZONGSHU |
Ningbo Customs | push NINGBO | NINGBO |
Chongqing Customs | push ZONGSHU | ZONGSHU |
Shenzhen Customs | push SHENZHEN_Z for local customs declaration, and then push ZONGSHU | SHENZHEN_ZS,ZONGSHU |
Shanghai Customs | push SHANGHAI_CBT | SHANGHAI_CBT |
Xi'an Customs | push ZONGSHU | ZONGSHU |
Nansha Entry-Exit Inspection and Quarantine Bureau, P.R.China | push NANSHAGJ | NANSHAGJ |
Tianjin Customs | push ZONGSHU | ZONGSHU |
Hefei Customs | push ZONGSHU | ZONGSHU |
Suzhou Customs | push ZONGSHU | ZONGSHU |
Huangpu Customs | push GUANGZHOU_HUANGPU | GUANGZHOU_HUANGPU |
14.6 / SDK and sample codes
- Java SDK and download link of document:
http://s.transfereasy.com/wc/document/WiseCashier%20Java%20SDK.zip
C# sample codes of signature and its verification: http://s.transfereasy.com/wc/document/Signature.cs