HipoPay Develop Docs NAV
Logo
python java php javascript csharp

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:

  1. 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…)

  2. Add Timestamp to the end of the signature string and separate them with’,’.

  3. Apply RSA encryption to the final string by using SHA256 and the secret key thatyou used to

    submit requests.

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

Unix 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.:

POST /mp_pay

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

POST /order/scan_pay

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

POST /order/scanned_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:

GET /wx_openid

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:

POST /mini_program_pay

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.


wx.requestPayment({
   'timeStamp': timeStamp,
   'nonceStr': nonceStr,
   'package': 'prepay_id=' + prepay_id,
   'signType': 'MD5',
   'paySign': sign,
   'success': function(res) {
   console.log (res) ;
   },
   'fail': function (res) {
   console.log (res) ;
   }
})

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:

First / request API of payment.

POST /order/app_pay

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

POST /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

GET /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

GET /refund

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:
"refunds": [
   {
   "no":"2017073101xxxxx",
   "order_no": "20170731xxxx",
   "refund_amount":50,
   "status":"SUCCESS"
   },{
   "no":"2017073101xxxxx",
   "order_no": "20170731xxxx",
   "refund_amount":50,
   "status":"SUCCESS"
}]

4.9 /Check Exchange Rate

GET /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

POST /alipay/scanned_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&currency=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:

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:

  1. App request API 6.2.1 to get prepay _string.
  2. Use prepay _string to call SDK (6.2.2) to call Alipay.
  3. Server end completes the transaction by payment order checking (6.3) or Asynchronous Notification(13.1).

6.2.1 / Obtain prepay _string

POST /alipay/app_pay

Response

{
    "meta": {
        "status_code": 200,
        "message": "Request successful",
        "success": true
    },
    "data": {
       "prepay_string":"_input_charset=\"utf-8\"&body=\"fortest\"&currency=\"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.

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

POST /alipay/wap_pay

WAP payment means that user uses Alipay to pay money on the H5 page of their mobile terminal. This payment method involves three steps:

-Lead customers to jump to the returned url of API to complete the payment.

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&currency=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

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

GET /alipay/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

POST /alipay/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

GET /alipay/refund

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

GET /alipay/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

POST /alipay/qrcode_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:

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:

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

POST /alipay/scan_pay

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

POST /merchant

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

GET /merchant

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

PUT /merchant

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

DELETE /merchant

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

GET /merchants

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

POST /settle_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

GET /settle_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

GET /settle_accounts

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

POST /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

GET /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

GET /withdrawals
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

POST /transfer

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

GET /transfer
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

GET /transfers
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

POST /wechat_pay/declaration
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

GET /wechat_pay/declaration
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

POST /alipay/declaration
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

GET /alipay/declaration
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:

  1. 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…)
  2. Add the timestamp of header to the end of the signature string, enter “,” to separate them and a query-string signature is then created.
  3. Use SHA-256 to authenticate the query-string signature and the signature included in the header.
  4. 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

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

15 / Help