WiseCashier Develop Docs NAV Navbar
Logo
python java php javascript csharp

1 / Introduction

WiseCashier 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. The responses to all API requests would be returned in a canonical and friendly JSON format (including error info). Every response would contain meta info (status data of request itself) and data info (returned response data).

2 / Authentication

Request

{
    "MerchantNO": '123456',
    "Signature": '539cae75aacf7d6533d288ded0f47b07',
    "Version": '1.0',
    "Timestamp": ''
}

The following four parameters should be added in the Header of all requests made by merchants: ​

Prepare Public Key & Private Key

2.1 / MerchantNO

Merchant No. will be assigned uniformly by WiseCashier.

2.2 / Signature

Signature rules are as follows:

  1. Sort the request parameter names (querystring in GET Request and form in POST Request) by ASCII code in ascending alphabetical order (i.e. lexicographical sequence) and URL encode the parameter values, then join them into signature strings in the URL key value pair format “URL key=value” (key1=value1&key2=value2…).

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

  3. Apply RSA to encrypt the final string by using the Hash algorithm SHA256 and the private key in the key pair that is used to submit requests.

  4. Base64_encode the encrypted string. Then this is the final signature.

Request

def data_sign(data, timestamp, private_key):
    """
    :param data: payload data
    :param timestamp: timestamp
    :param private_key: private key
    :return: signature
    """
    def format_code(x):
       """Compatible with unicode, int and float
       """
        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())
    ))
    # Encode with utf-8
    signature_str = signature_str.encode("utf-8")
    # Add the timestamp to the end of the string and separate them with a comma    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
<?php
function sign($data, $timestamp, $private_key) {

    $prikey = openssl_pkey_get_private($private_key);

    ksort($data);

    $signature_str = '';

    foreach ($data as $key => $item) {
        if (strlen($signature_str) == 0) {
            $signature_str .= $key . '=' . rawurlencode($item);
        } else {
            $signature_str .= '&' . $key . '=' . rawurlencode($item);
        }
    }

    $signature_str = utf8_encode($signature_str);

    $signature_str .= ',' . strval($timestamp);

    $alg = OPENSSL_ALGO_SHA256;

    openssl_sign($signature_str, $sign, $prikey, $alg);

    $sign = base64_encode($sign);

    return $sign;
}
?>
var crypto = require('crypto'), fs = require('fs');

var privatePem = fs.readFileSync('./private.key');

var key = privatePem.toString();

function sign(obj, timestamp) {
    console.log(Object.keys(obj));
    var newkey = Object.keys(obj).sort();
    var newObj = {};
    for (var i = 0; i < newkey.length; i++) {                         //Traverse the newkey data array
        newObj[newkey[i]] = encodeURI(obj[newkey[i]]);    //Add key value pairs to newly created objects based on ascending alphabetical order, and URL encode the parameter values
    }
    var str = '';
    for (var item in newObj) {
        str += item + '=' + newObj[item] + '&';
    }
    str = str.slice(0, -1);
    str += ',' + timestamp;
    //Encryption
    var sign = crypto.createSign('RSA-SHA256');
    sign.update(str);
    sign = sign.sign(key);

    //Encode the encrypted string by using base64
    var base64 = new Buffer(sign);
    var s = base64.toString('base64');
    console.log(s);
    return s;
}

module.exports = {
    data_sign: data_sign
};

2.3 / Version

Latest version: 1.0

Previous version: None

2.4 / Timestamp

Unix Timestamp Unix Timestamp

3 / Error Handling

Status Code Description
400 Bad Request - Request parameter error
401 Unauthorized - Signature error
411 Timestamp Error - Request timeout
403 Forbidden - Permission error
404 Not Found - Resource or object not found
500 internal Server Error - Internal server error, please try later
503 Service Unavailable - Service unavailable, please try later
555 Wechat Service Error - WeChat service error

If error code 555 is returned, the message parameter is a JSON string (as follows). Please refer to the WeChat error description in message for more error info.

Parameter Description
wx_message WeChat error description
wx_code WeChat error code

Click here to find out the description of WeChat error code (wx_code): Check WeChat Error Code

4 / Payment (WeChat Wallet in China Mainland)

Merchants can collect payments via the payment channel of WeChat cross-border payment from those people in China Mainland who had their WeChat accounts undergone the real name authentication. As for the APIs of the following scenarios, merchants can only collect payments from people with a WeChat account of China Mainland:

Payment Method Description Section
Official Account Payment It applies to offline payment scenarios. 4.1 / WeChat Official Account Payment
Quick Pay (Merchants scan customers’ QR code to collect payment) It applies to offline payment scenarios. 4.2 / Quick Pay
Scan to Pay (Customers scan merchants’ QR code to pay) It applies to both online & offline payment scenarios. 4.3 / Scan to Pay
Mini Programs Payment It applies to online payment scenarios. 4.4 / Mini Programs Payment

4.1 / WeChat Official Account Payment

WeChat Official Account payment refers to a payment process via the H5 page opened through WeChat. The steps for this payment method are as follows:

Step 1 Get user’s openid (openid).

https://api.wisecashier.com/mp_pay/oauth?merchant_no=xxx&currency=HKD

The parameters currency and merchant_no are mandatory. Other parameters are optional. All the parameters will be transferred back after user’s openid is obtained. We will run the payment page of merchants in our own docker after the openid is obtained (we need to be informed of the address of the payment page in advance, then we will bind merchant’s page to our docker and bring back all the parameters in the authorized URL, and add an extra parameter openid as well).

Step 2 Place a payment order on the H5 payment page.

After customer inputs the amount payable, the following APIs need to be called.:

POST /mp_pay

Parameters are as follows:

Parameter Description Mandatory
merchant_no Merchant No. Yes
amount Amount Yes
openid openid Yes
currency Currency Yes
product_info Product info Yes
agent_order_id Agent order No. No
notify_url URL of notification of payment result No

This API returns the parameters used to call for WeChat payment.

Step 3 Call the payment page of WeChat client side.

Use the above API parameters to call the payment page of WeChat client side. Refer to the sample code below:

Request

var js_api_param = '';

//Call WeChat JS API to pay
function jsApiCall() {
  WeixinJSBridge.invoke('getBrandWCPayRequest', js_api_param,
                        function (res) {
    if (res.err_msg == "get_brand_wcpay_request:ok") {
      alert('Payment successful');
    }

    if (res.err_msg == "get_brand_wcpay_request:cancel") {
       alert('Cancel payment');
    }

    if (res.err_msg == "get_brand_wcpay_request:fail") {
       alert('Payment failed');
    }
  });
}

//Click to confirm payment
$('#pay-btn').on('click', function () {

  $.ajax({
    async: true,
    url: 'https://api.wisecashier.com/mp_pay',
    type: 'POST',
    data: {
      'merchant_no': $('#merchant_no').val(),
      'amount': $('#amt').val(),
      'openid': $('#openid').val()
    },
    headers: {
      'Version': '1.0'
    },
    beforeSend: function () {
    },
    success: function (r) {
      if (r.meta.success) {
        js_api_param = r.data.js_param;
        if (typeof WeixinJSBridge == "undefined") {
          if (document.addEventListener) {
            document.addEventListener('WeixinJSBridgeReady', jsApiCall, false);
          } else if (document.attachEvent) {
            document.attachEvent('WeixinJSBridgeReady', jsApiCall);
            document.attachEvent('onWeixinJSBridgeReady', jsApiCall);
          }
        } else {
          jsApiCall();
        }
      }
    },
    complete: function () {
    }
  });
});

Step 4 Check order status.

Please refer to 4.9 / Check Payment Order.

4.2 / Quick Pay

POST /order/scan_pay

Quick pay means that the merchant scans customer’s QR code by using a device (like a scanner) and inputs the amount to collect money.

This API brings customer’s QR code and amount to initiates a payment collection request to WeChat. After that, customer clicks Confirm on his/her mobile phone to complete the payment.

Request

def scan_pay():
    url = HOST + '/order/scan_pay'
    data = dict(
        merchant_no='xxx',
        currency='HKD',
        amount='100',
        product_info='Product 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": "Product info",
      "pay_amount": "0.1"
      "status": "PAID",
      "settle_rate": "1",
      "trade_type": "MICRO"
    }
  },
  "meta": {
    "message": "Request successful",
    "status_code": 200,
    "success": true
  }
}
Parameter Description Mandatory
merchant_no Merchant No. Yes
currency Currency Yes
amount Amount Yes
product_info Product info Yes
ip Terminal IP address Yes
auth_code Content of customer’s QR code Yes
agent_order_id Agent order No. No
product_id Product ID No
device_info Device info No
notify_url URL of notification of payment result No

The response is in JSON format. For details of data structure of the payment order, please refer to 14.1 / Rules of Notification.

4.3 / Scan to Pay

POST /order/scanned_pay

Scan to pay means that the customer pays the merchant by scanning the QR code (it contains the payment information like the amount, etc.) that is generated by the merchant by using a device.

This API initiates a payment request to WeChat and WeChat will return payment information and QR code URL. Then, the customer scans this QR code to complete the payment.

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"
        }
    }
}
Parameter Description Mandatory
merchant_no Merchant No. Yes
currency Currency Yes
amount Amount Yes
product_info Product info Yes
ip Terminal IP address Yes
notify_url URL of notification of Payment result No
agent_order_id Agent order No. No
product_id Product ID No
device_info Device info No

The returned data is in JSON format and includes the following two parts:

4.4 / Mini Programs Payment

Step 1 Get user’s login code.

A call of wx.login() needs to be made in Mini Program and user’s login code will be obtained from the returned results (code is valid in 5 minutes).

Step 2 Call the API below to get user’s openid:

GET /wx_openid
Parameter Description Mandatory
code User’s login code Yes
merchant_no Merchant No. Yes

Response

{
    "meta": {
        "status_code":200 ,
        "message": "Request successful",
        "success": true
    },
    "data": {
        "openid":"kxc13i13J123"
    }
}

Step 3 Call the APIs below and transfer the parameters to place a payment order:

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 Mandatory
merchant_no Merchant No. Yes
openid WeChat openid Yes
currency Currency Yes
amount Amount Yes
product_info Product info Yes
agent_order_id Agent order No. No
notify_url URL of notification of payment result No

Step 4 Call the payment page of WeChat client side.

Sample codes are as follows. The timeStamp, nonceStr, prepay_id and sign can be obtained in Step 3.


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) ;
   }
})

Step 5 Check order status.

Please refer to 4.9 / Check Payment Order. Order No. can be obtained in Step 3.

4.5 / In-App Payment

4.5.1 / Description

In-app payment refers to a payment process in which the WeChat payment module is called in merchant’s app and the customer pays in WeChat app and then gets back to merchant’s app.

4.5.2 / App Registration on WeChat Open Platform

Registration Address: WeChat Open Platform

The app _id needs to be sent to WiseCashier after registration.

4.5.3 / Integration

There are three steps:

Step 1 Request API of pre-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 Mandatory
merchant_no Merchant No. Yes
currency Currency Yes
amount Amount Yes
product_info Product info Yes
agent_order_id Agent order No. No
notify_url URL of notification of payment result No

Step 2 Call 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

Step 3 Check order status.

After the process is directed back to merchant’s app, please use the method described in 4.9 / Check Payment Order (or 14 / Payment Notification ) to get the accurate payment status of the order.

4.6 / PC Website Cashier Counter Payment

4.6.1 / Description

PC website cashier counter payment is a payment method that can be quickly integrated with PC websites. Only two steps are required to complete payment.

  1. Merchant guides customers to the cashier counter (4.6.2), and customers will be directed to the page designated by merchant after payment.

  2. Merchant confirms the payment status by checking payment order (4.9) or receiving asynchronous notification (14.1).

4.6.2 / Enter Cashier Counter

GET /wechatpay/cashier_desk
Parameter Description Mandatory
merchant_no Merchant No. Yes
currency Currency Yes
amount Amount Yes
product_info Product info Yes
agent_order_id Agent order No. No
return_url URL returned after payment Yes
notify_url URL of notification of payment result No

Example:

4.6.3 / Jump To

After paying successfully at the cashier counter, the customer will jump to the return_url (it contains the following parameters) transferred from the last step (4.6.2) by GET method.

Parameter Description Example
no Order No. 20181201043212345678
agent_order_id Agent order No. XCY2018392812346127
merchant_no Merchant No. WC58dc50dc59xxx
currency Amount 100
trade_type Exchange rate PC_DESK
exchange_rate Trade type 1.312
product_info Product info Order Sample
trade_time Trade time 2017-06-22 21:29:47
status Status PAID

Example:

4.6.4 / Notes

  1. The data attached in the jumping process of front end should be regarded as a reference only. Check the actual payment status by checking payment order (4.9) or receiving asynchronous notification (14.1).

  2. Extra parameter can be transferred into API after entering the cashier counter (4.6.2) and it will be attached when the page jumps after successful payment, but it’s parameter name cannot be the same as the parameter set by API.

4.7 / Official Account Cashier Counter Payment

4.7.1 / Description

Official Account cashier counter payment is a payment method that can be quickly integrated with WeChat Official Account. Only two steps are required to complete payment.

  1. Merchant guides customers to the cashier counter (4.6.2), and customers will be directed to the page designated by merchant after payment.

  2. Merchant confirms the payment status by checking payment order (4.9) or receiving asynchronous notification (14.1).

4.7.2 / Enter Cashier Counter

GET /wechatpay/cashier_desk
Parameter Description Mandatory
merchant_no Merchant No. Yes
currency Currency Yes
amount Amount Yes
product_info Product info Yes
agent_order_id Agent order No. No
return_url URL returned after payment Yes
notify_url URL of notification of payment result No

Example:

4.7.3 / Jump To

After paying successfully at the cashier counter, the customer will jump to the return_url (it contains the following parameters) transferred from the last step (4.7.2) by GET method.

Parameter Description Example
no Order No. 20181201043212345678
agent_order_id Agent order No. XCY2018392812346127
merchant_no Merchant No. WC58dc50dc59xxx
currency Amount 100
trade_type Exchange rate MP_DESK
exchange_rate Trade type 1.312
product_info Product info Order Sample
trade_time Trade time 2017-06-22 21:29:47
status Status PAID

Example:

4.7.4 / Notes

  1. The data attached in the jumping process of front end should be regarded as a reference only. Check the actual payment status by checking payment order (4.9) or receiving asynchronous notification (14.1).

  2. Extra parameter can be transferred into API after entering the cashier counter (4.7.2) and it will be attached when the page jumps after successful payment, but it’s parameter name cannot be the same as the parameter set by API.

4.8 / 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 Mandatory
order_no Payment order No. Yes
refund_amount Refund amount No
outer_refund_no External refund order No. No

If refund_amount is not specified, then payment will be fully refunded. The returned result is refund info. For details of data structure of the refund order, please refer to 15.2 / Description of Refund Order Data Structure.

4.9 / 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 Mandatory
order_no Payment order No. Yes
agent_order_id Agent order No. No

Get order information by using order_no or agent_order_id. Either of them must be specified.

4.10 / 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 Mandatory
refund_no Refund order No. No
order_no Payment order No. No
agent_order_id Agent order No. No
outer_refund_no External refund order No. No

At least one of the four parameters above is required.
If refund_no or outer_refund_no is transferred, the response is as follows:
{
    "meta": {
        "status_code": 200,
        "message": "Request successful",
        "success": true
    },
    "data": {
        "info": {
            "no":"2017073101xxxxx"
            "order_no": "20170731xxxx",
            "outer_refund_no": "20170731xxxx",
            "refund_amount": "100",
            "status": "SUCCESS"
        }
    }
}
If you specify order_no or agent_order_id, the response is as follows:
"refunds": [
   {
   "no":"2017073101xxxxx",
   "order_no": "20170731xxxx",
   "outer_refund_no": "20170731xxxx",
   "refund_amount":50,
   "status":"SUCCESS"
   },{
   "no":"2017073101xxxxx",
   "order_no": "20170731xxxx",
   "outer_refund_no": "20170731xxxx",
   "refund_amount":50,
   "status":"SUCCESS"
}]

4.11 / 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 Mandatory
merchant_no Merchant No. Yes
currency Currency Yes

5 / Payment (WeChat Wallet in HK)

It applies to collecting payments from WeChat Wallet in HK.

5.1 / Quick Pay

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 payment collection scenarios only.

For Develop Docs, please refer to 4.2 / Quick Pay.

5.2 / Refund

Same as that of WeChat Wallet in China Mainland. For Develop Docs, please refer to 4.8 / Refund.

5.3 / Check Payment Order

Same as that of WeChat Wallet in China Mainland. For Develop Docs, please refer to 4.p / Check Payment Order.

5.4 / Check Refund Order

Same as that of WeChat Wallet in China Mainland. For Develop Docs, please refer to 4.10 / Check Refund Order

6 / Payment (Alipay Online Payment)

6.1 / Scan to Pay

POST /alipay/scanned_pay

Scan to pay means that the merchant requests this API to get payment information and QR code URL which are used to generate a QR code on the page displayed on PC, then the customer scans this QR code to complete the payment.

Request

def scanned_pay():
    url = HOST + '/alipay/scanned_pay'
    data = dict(
        merchant_no='xxx',
        currency='HKD',
        amount='100',
        subject='Product description'
    )
    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 description",
            "exchange_rate": "0.8789"
        }
    }
}
Parameter Description Mandatory
merchant_no Merchant No. Yes
currency Currency Yes
amount Amount Yes
subject Product description Yes
notify_url URL of notification of payment result No
out_order_no Agent order No. No

The returned data is in JSON format and includes the following two parts:

Field Description
payment_no Payment order No.
merchant_no Merchant No.
currency Currency. Refer to 15.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 order status. INIT: awaiting payment; PAID: payment successful; FAIL: payment failed; EXPIRED: payment order expired
pay_method Payment method

6.2 / In-App Payment

In-app payment refers to a payment process in which the Alipay payment module is called in merchant’s app while the customer pays money. There are three steps to complete payment:

  1. Use the app to request API (6.2.1) to get prepay_string.
  2. Use prepay_string to call SDK (6.2.2) to call up Alipay.
  3. Obtain the payment status on the server side by checking payment order (6.3) or receiving asynchronous notification (14.1) to complete the payment.

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 Mandatory
merchant_no Merchant No. Yes
currency Currency Yes
amount Amount Yes
subject Product description Yes
notify_url URL of notification of payment result No
out_order_no Agent order No. No

The returned data is in JSON format and includes the following two parts:

Field Description
payment_no Payment order No.
merchant_no Merchant No.
currency Currency. Refer to 15.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 order status. INIT: awaiting payment; PAID: payment successful; FAIL: payment failed; EXPIRED: payment order expired
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: provides merchants with payment function.

Method parameters: instantiate PayTask and parameter transfer activities.

Parameter Description
String prepay_string Obtained as described in 6.2.1
boolean isShowPayLoading Indicates whether a loading is needed before the wallet is called when the customer clicks PAY in merchant’s app. If it is set to “true”, then a loading will be called when the payment API is called. The loading won’t disappear until the H5 payment page or external wallet payment page is called (we recommend setting it to “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 result is “resultStatus=9000” and result->success=“true”, payment is considered successful. But this result is unreliable. The result obtained by checking payment order (6.5) or receiving asynchronous notification (14.1) on the server side shall be the final result.

6.3 / WAP Payment

POST /alipay/wap_pay

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

Request

def scanned_pay():
    url = HOST + '/alipay/wap_pay'
    data = dict(
        merchant_no='xxx',
        currency='HKD',
        amount='100',
        subject='Product description'
    )
    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 Mandatory
merchant_no Merchant No. Yes
currency Currency Yes
amount Amount Yes
subject Product description Yes
notify_url URl of notification of payment result No
out_order_no Agent order No. No
return_url URL returned after payment Yes

The returned data is in JSON format and includes the following two parts:

Field Description
payment_no Payment order No.
merchant_no Merchant No.
currency Currency. Refer to 15.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 order status. INIT: awaiting payment; PAID: payment successful; FAIL: payment failed; EXPIRED: payment order expired
pay_method Payment method

6.4 / PC Website Cashier Counter Payment

6.4.1 / Description

PC website cashier counter payment is a payment method that can be quickly integrated with PC websites. Only two steps are required to complete payment.

  1. Merchant guides customers to the cashier counter (6.4.2), and customers will be directed to the page designated by merchant after payment.

  2. Merchant confirms the payment status by checking payment order (6.5) or receiving asynchronous notification (14.1).

6.4.2 / Enter Cashier Counter

GET /alipay/cashier_desk
Parameter Description Mandatory
merchant_no Merchant No. Yes
currency Currency Yes
amount Amount Yes
subject Product description Yes
return_url URL returned after payment Yes
agent_order_id Agent order No. No
notify_url URL of notification of payment result No

Example:

6.4.3 / Jump To

After paying successfully at the cashier counter, the customer will jump to the return_url (it contains the following parameters) transferred from the last step (6.4.2) by GET method.

Parameter Description Example
no Merchant Order No. 20181201043212345678
out_order_no Agent order No. XCY2018392812346127
merchant_no Merchant No. WC58dc50dc59xxx
currency Currency HKD
amount Amount 100
exchange_rate Exchange rate 1.2312
tarde_type Trade type PC_DESK
subject Product description Order Sample
trade_time Trade time 2017-06-22 21:29:47
status Status PAID

Example:

6.4.4 / Notes

  1. The data attached in the jumping process of front end should be regarded as a reference only. Check the actual payment status by checking payment order (6.5) or receiving asynchronous notification (14.1).
  2. Extra parameter can be transferred into API after entering the cashier counter (6.4.2) and it will be attached when the page jumps after successful payment, but it’s parameter name cannot be the same as the parameter set by API.

6.5 / 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": "Request successful",
    "status_code": 200,
    "success": true
  }
}
Parameter Description Mandatory
payment_no Payment order No. No
out_order_no Agent order No. No

Get order information by using payment_no or out_order_no. Either of them must be specified.

Parameter Description
payment_no Payment order No.
merchant_no Merchant No.
buyer_email Buyer’s email
buyer_id buyer ID
currency Currency. Refer to 15.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 order status. INIT: awaiting payment; PAID: payment successful; FAIL: payment failed; EXPIRED: payment order expired
pay_method Payment method
refund_status Refund status. NONE: no refund; PART: partial refund; FULL: full refund
refundable_amount Refundable amount

6.6 / 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 Mandatory
payment_no Payment order No. Yes
outer_refund_no External refund order No. No
refund_amount Refund amount No

If refund_amount is not specified, then payment will be fully refunded. The returned result is refund info.

Field Description
payment_no Payment order No.
refund_no Refund order No.
refund_amount Refund amount
status Refund status
outer_refund_no External refund order No.

6.7 / 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 Mandatory
refund_no Refund order No. No
payment_no Payment order No. No
outer_order_no External order No. No
outer_refund_no External refund order No. No
At least one of the four parameters above is required.
If refund_no or outer_refund_no is transferred, the response is as follows:
{
    "meta": {
        "status_code": 200,
        "message": "Request successful",
        "success": true
    },
    "refund": {
        "no":"2017073101xxxxx"
         "order_no": "20170731xxxx",
         "agent_order_id": "20170731xxxx",
         "outer_refund_no": "20170731xxxx",
        "refund_amount": "100",
        "status": "SUCCESS"
    }
}
If order_no or agent_order_id is transferred, the response is as follows:
"refunds": [
    {
    "no":"2017073101xxxxx"
         "order_no": "20170731xxxx",
         "refund_no": "20170731xxxx",
         "agent_order_id": "20170731xxxx",
         "outer_refund_no": "20170731xxxx",
        "refund_amount": "100",
        "status": "SUCCESS"
    },
    {
    "no":"2017073101xxxxx"
         "order_no": "20170731xxxx",
         "refund_no": "20170731xxxx",
         "agent_order_id": "20170731xxxx",
         "outer_refund_no": "20170731xxxx",
        "refund_amount": "100",
        "status": "SUCCESS"
    }
]

6.8 / Check Exchange Rate

GET /alipay/rate

This API returns the exchange rate of the requested currency against RMB for reference, 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"
    }
}
Parameter Description Mandatory
currency Currency Yes

The response is as follows:

Field Description
currency Currency
rate Exchange rate

7 / Payment (Alipay Offline Payment)

7.1 / Dynamic QR Code Payment

POST /alipay/qrcode_pay

Dynamic QR code payment refers to the payment process in which the merchant gets a QR code by requesting the API below thus to enable customers to scan the QR code via their Alipay app to complete payment. There are three steps to complete payment:

Request

def scanned_pay():
    url = HOST + '/alipay/qrcode_pay'
    data = dict(
        merchant_no='xxx',
        currency='HKD',
        amount='100',
        subject='Product description'
    )
    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 description",
            "exchange_rate": "0.8789"
        }
    }
}
Parameter Description Mandatory
merchant_no Merchant No. Yes
currency Currency Yes
amount Amount Yes
subject Product description Yes
notify_url URL of notification of payment result No
out_order_no Agent order No. No

The returned data is in JSON format and includes the following two parts:

Field Description
payment_no Payment order No.
merchant_no Merchant No.
currency Currency. See 15.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 order status. INIT: awaiting payment; PAID: payment successful; FAIL: payment failed; EXPIRED: payment order expired
pay_method Payment method

7.2 / Quick Pay

POST /alipay/scan_pay

Quick pay means that the merchant scans customer’s Alipay payment code by using a device (like a scanner) and then requests the API below by using the payment code to collect money. There are three steps to complete payment:

Request

def scanned_pay():
    url = HOST + '/alipay/scan_pay'
    data = dict(
        merchant_no='xxx',
        currency='HKD',
        amount='100',
        auth_code='123456',
        subject='Product description'
    )
    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 Mandatory
merchant_no Merchant No. Yes
auth_code QR code of Alipay Yes
currency Currency Yes
amount Amount Yes
subject Product description Yes
notify_url URL of notification of payment result No
out_order_no Agent order No. No

The returned data is in JSON format.

order: indicates the details of the payment order. See below for the details of data structure.

Field Description
payment_no Order No.
merchant_no Merchant No.
currency Currency. Refer to 15.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 order status. INIT: awaiting payment; PAID: payment successful; FAIL: payment failed; EXPIRED: payment order expired
pay_method Payment method

Server side can still receive an asynchronous notification yet the synchronously returned result of the payment status is PAID. The asynchronous notification should be seen as the final status of the payment.

7.3 / Refund

Same as that of Alipay Online Payment. For Develop Docs, please refer to 6.6 / Refund.

7.4 / Check Payment Order

Same as that of Alipay Online Payment. For Develop Docs, please refer to 6.5 / Check Payment Order.

7.5 / Check Refund Order

Same as that of Alipay Online Payment. For Develop Docs, please refer to 6.7 / Check Refund Order.

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": "Request successful",
    "status_code": 200,
    "success": true
  }
}

At WiseCashier, merchant account can be divided into 2 categories: one is the real merchant account, which is created for the real merchant who has signed agreement with us; the other is the virtual merchant account, also defined as sub-merchant account in this document, which is used for separate account management. The virtual merchant account is an affiliate to the real merchant account (unless otherwise specified, sub-merchant account in this document means virtual merchant account). Currently, only virtual merchant accounts are allowed to be created since real merchant accounts can only be enabled in the process of signing the agreement. Virtual merchant accounts can be used to receive money transfers from other merchant accounts but can’t be used to collect payments. The following are parameters required to create a virtual merchant account:

Parameter Description Mandatory
name Merchant name Yes
short_name DBA name Yes
country_code Code of the country in which the merchant is registered Yes
settle_currency Settlement currency Yes
parent_merchant_no Merchant No. of its parent merchant Yes
account Account used to log in to the merchant system which shall be an email adreess Yes
password Password used to log in to the merchant system Yes
remark Note of the merchant Yes

Description of returned parameters:

Parameter Description
no Merchant No.
parent_merchant_no Merchant No. of its parent merchant
account Account
name Merchant name
short_name DBA name
country_code Code of the country in which the merchant is registered
is_sub_merchant Sub-merchant or not
settle_currency Settlement currency
settled_balance Settled balance
unsettled_balance Unsettled balance
remark Note

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": "Request successful",
    "status_code": 200,
    "success": true
  }
}

Both real merchant’s information and virtual merchant’s information can be checked through the API. Enter a merchant No. and the information of the merchant will be returned.

Parameter Description Mandatory
merchant_no Merchant No. of a merchant or a sub-merchant Yes

Description of returned parameters:

Parameter Description
no Merchant No.
parent_merchant_no Merchant No. of its parent merchant
account Account
name Merchant name
short_name DBA name
country_code Code of the country in which the merchant is registered
is_sub_merchant Sub-merchant or not
settle_currency Settlement currency
settled_balance Settled balance
remark Note

8.3 / Change 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": "Request successful",
    "status_code": 200,
    "success": true
  }
}

Currently, only the information of virtual merchants can be changed through the API and only their merchant name and DBS name can be changed. If you do need to change other information of a virtual merchant, please delete the virtual merchant and create a new one.

Parameter Description Mandatory
merchant_no Merchant No. of the sub-merchant Yes
name Merchant name No
short_name DBA name No

Description of returned parameters:

Parameter Description
no Merchant No.
parent_merchant_no Merchant No. of its parent merchant
account Account
name Merchant name
short_name DBA name
country_code Code of the country in which the merchant is registered
is_sub_merchant Sub-merchant or not
settle_currency Settlement currency
settled_balance Settled balance
unsettled_balance Unsettled balance
remark Note

8.4 /Delete Merchant Account

DELETE /merchant

Response

{
  "data": {},
  "meta": {
    "message": "Request successful",
    "status_code": 200,
    "success": true
  }
}

Currently, only sub-merchant accounts can be deleted through the API.

But when there is balance left in the sub-merchant 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 the account. Please note the risk of parameter in this case.

Parameter Description Mandatory
merchant_no Merchant No. Yes
force Force delete, YES or NO? The defualt value is NO No

8.5 / Check the List of Sub-merchants

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": "Request successful",
    "status_code": 200,
    "success": true
  }
}

To check the sub-merchants of a real merchant, the merchant No. of the real merchant must be specified, and the response will be a list of sub-merchants affiliated to the real merchant.

Parameter Description Mandatory
merchant_no Merchant No. Yes

Description of returned parameters:

Parameter Description
no Merchant No.
parent_merchant_no Merchant No. of its parent merchant
account Account
name Merchant name
short_name DBA name
country_code Code of the country in which the merchant is registered
is_sub_merchant Sub-merchant or not
settle_currency Settlement currency
settled_balance Settled balance
unsettled_balance Unsettled balance
remark Note

8.6 / Check Payment Channel

GET /pay_channels

The API can be used to check the enabled payment channels of a merchant.

Parameter Description Mandatory
None - -

No parameter is required to be tansferred when this API is called.

Description of returned parameters:

Parameter Description
channel Payment channel
channel_name Name of the payment channel
pricing_currency Pricing currency
settle_currency Settlement currency
cate Channel type

9 / 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": "Request successful",
    "status_code": 200,
    "success": true
  }
}

Currently, settlement accounts cannot be added for real merchants through this API. This API only supports adding settlement accounts for virtal merchants. Please refer to 15.3 / Currency Code https://www.wisecashier.com/Document/merchant#15-3 for currency codes.

Parameter Description Mandatory
merchant_no Merchant No. of the sub-merchant Yes
account Account No. (Card No.) Yes
account_name Account name Yes
bank Bank name Yes
branch Branch Yes
country_code Code of the country in which the bank locates 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 Code of the country in which the bank locates
bank Bank name
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": "Request successful",
    "status_code": 200,
    "success": true
  }
}

Input” settle _account _no.’’, and the response will be a settlement account.

Parameter Description Mandatory
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 Code of the country in which the bank locates
bank Bank name
branch Branch
address Address
currency_codes Supported currecies
status Status
swift_code SWIFT code

9.3 / Check the List of Settlement Accounts

GET /settle_accounts

This API is used to check the settlement accounts that are bound to a merchant account or sub-merchant account.

Parameter Description Mandatory
merchant_no Merchant No. of the merchant or sub-merchant Yes

Description of returned parameters:

Parameter Description
no Account No.
account Account No.
account_name Account name
country_code Code of the country in which the bank locates
bank Bank name
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": "Request successful",
    "status_code": 200,
    "success": true
  }
}

10 / Export Transaction Data

GET /download_bill
Parameter Description Mandatory
merchant_no Merchant No. Yes
start_date Start date Yes
end_date End date Yes

This API can only be used to access the transaction data of the last three months. Export the transaction data, and a txt file will be returned.

11 / Withdrawal

11.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": "Request successful",
    "status_code": 200,
    "success": true
  }
}

Funds in the merchant account can be withdrawn to the merchant’s settlement account in any supported through this API. Please refer to 15.3/ Currency Code https://www.wisecashier.com/Document/merchant#15-3 for currency codes.

Parameter Description Mandatory
merchant_no Merchant No. of the merchant or sub-merchant Yes
source_amount Withdrawal amount Yes
source_currency Withdrawal 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 (GST), only applicable to New Zealand merchants
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.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": "Request successful",
    "status_code": 200,
    "success": true
  }
}

This API is used to check the status of a withdrawal by entering the withrawal No. Input withdrawal No. and the withdrawal status will be returned.

Parameter Description Mandatory
withdrawal_no Withdrawal No. Yes

Description of returned parameters:

Parameter Description
no Withdrawal No.
forex_rate Service rate
gst Goods and Services Tax (GST), only applicable to New Zealand merchants
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.3 / Check the List of Withdrawals

GET /withdrawals
Parameter Description Mandatory
merchant_no Merchant No. of the merchant or sub-merchant 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": "Request successful",
    "status_code": 200,
    "success": true
  }
}

Description of returned parameters:

Parameter Description
no Withdrawal No.
forex_rate Service rate
gst Good and Services Tax (GST), only applicable to New Zealand merchants
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

12 / Transfer

12.1 / Create Transfer

POST /transfer

Funds in a merchant account can be transferred to other merchant accounts or sub-merchant accounts in any supported currencies. Please refer to 15.3 / Currency Code for currency codes.

Parameter Description Mandatory
source_merchant_no Merchant No. of the merchant or sub-merchant Yes
source_amount Transfer amount Yes
target_merchant_no Merchant No. of the receiving merchant Yes
target_merchant_name Merchant name of the receiving merchant Yes
remark Note 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": "Request successful",
    "status_code": 200,
    "success": true
  }
}

Description of returned parameters:

Parameter Description
no Withdrawal No.
forex_rate Service rate
source_merchant_no Merchant No. of the sending merchant
source_amount Settlement amount
source_currency Settlement currency
target_merchant_no Merchant No. of the receiving merchant
target_amount Received amount
target_currency Received currency
target_merchant_name Merchant name of the receiving merchant
status Status
remark Note
time Time

12.2 / Check Transfer

GET /transfer
Parameter Description Mandatory
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": "Request successful",
    "status_code": 200,
    "success": true
  }
}

Description of returned parameters:

Parameter Description
no Withdrawal No.
forex_rate Service rate
source_merchant_no Merchant No. of the sending merchant
source_amount Settlement amount
source_currency Settlement currency
target_merchant_no Merchant No. of the receiving merchant
target_amount Received amount
target_currency Received currency
target_merchant_name Merchant name of the receiving merchant
status Status
remark Note
time Time

12.3 / Check the List of Transfers

GET /transfers
Parameter Description Mandatory
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": "Request successful",
    "status_code": 200,
    "success": true
  }
}
Parameter Description
no Withdrawal No.
forex_rate Service rate
source_merchant_no Merchant No. of the sending merchant
source_amount Settlement amount
source_currency Settlement currency
target_merchant_no Merchant No. of the receiving merchant
target_amount Received amount
target_currency Received currency
target_merchant_name Merchant name of the receiving merchant
status Status
remark Note
time Time

13 / Assistant APIs

13.1 / Customs Declaration of WeChat Pay

POST /wechat_pay/declaration
Parameter Description Mandatory Type Example
out_order_no Merchant order No. Yes String 18051893975650968
payment_no WiseCashier payment order No. Yes String 20180518163203689
customs Customs code (e.g. SHENZHEN) Yes String SHENZHEN
mch_customs_no CR code Yes String 123456789BTW
duty Duty (some customs requires this parameter) No int 88
action_type Action type. ADD (default value): add; MODIFY: modify. If action_type is set to MODIFY, the parameters must be the same as those of the first customs declaration. No String ADD

The following parameters are required if each order needs separate customs declaration:

Parameter Description Mandatory Type Example
out_order_no Merchant sub-order No. Yes string 2018051716124
payment_no Sub-order amount Yes float 46.44
transport_amount Logistics cost Yes float 23.22
product_amount Price of the product Yes float 23.22

The following parameters are required if identity verification is needed:

Parameter Description Mandatory Type Example
cert_id ID No. Yes String 510921199308772318
name Name Yes String Lisa

Note: Amount payable = Logistics cost + Product price

Returned results are as follows:

Parameter Description
out_order_no Merchant order No.
payment_no WiseCashier payment oder No.
customs Customs code
wechatpay_no WeChat receipt No.
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
modify_time Last update time

The following parameters will be returned if each order needs separate customs declaration:

Parameter Description
sub_order_no Merchant sub-order No.
sub_order_amount Sub-order amount
transport_amount Logistics cost
product_amount Price of the product

The following parameter will be returned when identity is verified:

Parameter Description
cert_check_result Identity verification result: UNCHECKED means no identity information has been uploaded; SAME means the identity information of the person who makes the order is same as that of the person who makes the payment; DIFFERENT means the identity information of the person who makes the order is different from that of the person who makes the payment.

13.2 / Resubmit Customs Declaration of WeChat Pay

POST /wechatpay/redeclaration

Transfer one of the three parameters below. In case of separate customs declaration of each order, transfer sub_order_no; otherwise, transfer payment_no or out_order_no.

Parameter Description Mandatory Type Example
payment_no WiseCashier payment order No. No String 2018051716124
out_order_no Merchant order No. No String 18051893975650968
sub_order_no Sub-order No. No String 20180518939756968

The following two parameters are required:

Parameter Description Mandatory Type Example
customs Customers code Yes String SHENZHEN
mch_customs_no CR code Yes String 123456789BTW

Returned results are as follows:

Parameter Description
out_order_no Merchant order No.
payment_no WiseCashier payment oder No.
customs Customs code
wechatpay_no WeChat receipt No.
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
modify_time Last update time
explanation Explanation of the declaration result (if failed, the returned

13.3 / Check Customs Declaration of WeChat Pay

GET /wechat_pay/declaration

Transfer one of the three parameters below. In case of separate customs declaration of each order, transfer sub_order_no; otherwise, transfer payment_no or out_order_no.

Parameter Description Mandatory Type Example
payment_no WiseCashier payment order No. No String 2018051816320384498567689
out_order_no Merchant order No. No String 1805123918160384498567689
sub_order_no Sub-order No. No String 18051816320384338567689
customs Customs code Yes String BEIJING

Returned results are as follows:

Parameter Description
out_order_no Merchant order No.
payment_no WiseCashier payment order No.
customs Customs code
wechatpay_no WeChat Pay receipt No.
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
modify_time Last update time

The following parameters will be returned if each order needs separate customs declaration:

Parameter Description
sub_order_no Merchant sub-order No.
sub_order_amount Sub-order amount
transport_amount Logistics cost
product_amount Price of the product

The following parameter will be returned when identity is verified:

Parameter Description
cert_check_result Identity verification result: UNCHECKED means no identity information has been uploaded; SAME means the identity information of the person who makes the order is same as that of the person who makes the payment; DIFFERENT means the identity information of the person who makes the order is different from that of the person who makes the payment.

13.4 / Customs Declaration of Alipay

Note: each order requires separate customs declaration.

POST /alipay/declaration
Parameter Description Mandatory Type Example
out_order_no Merchant order No. Yes String 180518939756568
payment_no WiseCashier payment order No. Yes String 20180518163203
customs Customs code (e.g. SHENZHEN) Yes String SHENZHEN
mch_customs_no CR code Yes String 123456789BTW
merchant_customs_name Company name of the merchant Yes String xxxhanguo_card

The following parameters are required if each order needs separate customs declaration:

Parameter Description Mandatory Type Example
sub_order_no Merchant sub-order No. Yes String 2018051716124
sub_order_amount Sub-order amount Yes String 46.44

The following parameters are required when identity is verified:

Parameter Description Mandatory Type Example
cert_id ID No. Yes String 510921199308772318
name Name Yes String Lisa

Returned results are as follows:

Parameter Description
out_order_no Merchant order No.
payment_no WiseCashier payment order No.
customs Customs code
alipay_no Alipay receipt No.
state “SUCCESS” successful, “FAIL” failed
modify_time Last update time

The following parameters will be returned if each order needs separate customs declaration:

Parameter Description
sub_order_no Merchant sub-order No.
sub_order_amount Sub-order amount

The following results will be returned when identity is verified:

Parameter Description
cert_check_result Identity verification result: T means the name and the ID No. of the person who makes the order that were uploaded by the merchant are same as those of the person who makes the payment. F means the name and the ID No. of the person who makes the order that were uploaded by the merchant are different to those of the person who makes the payment.

13.5 / Resubmit Customs Declaration of Alipay

Resubmit Customs Declaration of Alipay

POST /alipay/redeclaration

Transfer one of the three parameters below. In case of separate customs declaration of each order, transfer sub_order_no; otherwise, transfer payment_no or out_order_no.

Parameter Description Mandatory Type Example
payment_no WiseCashier payment order No. No String 201805188567689
out_order_no Merchant order No. No String 1805975650968
sub_order_no Sub-order No. No String 2018051856968
customs Customs code (e.g. SHENZHEN) Yes String SHENZHEN
mch_customs_no CR code Yes String 123456789BTW
merchant_customs_name Company name of the merchant Yes String xxxhanguo_card

The following parameters are required if each order needs separate customs declaration:

Parameter Description Mandatory Type Example
sub_order_no Merchant sub-order No. Yes String 2018051716124
sub_order_amount Sub-order amount Yes String 46.44

The following parameters are required when identity is verified:

Parameter Description Mandatory Type Example
cert_id ID No. Yes String 510921199308772318
name Name Yes String Lisa

Returned results are as follows:

Parameter Description
out_order_no Merchant order No.
payment_no WiseCashier payment oder No.
customs Customs code
alipay_no Alipay receipt No.
state SUCCESS - successful
modify_time Last update time

The following parameters will be returned if each order needs separate customs declaration:

Parameter Description
sub_order_no sub-order No.
sub_order_amount sub-order amount

The following parameter will be returned when identity is verified:

Parameter Description
cert_check_result Identity verification result: T means the name and the ID No. of the person who makes the order that were uploaded by the merchant are same as those of the person who makes the payment. F means the name and the ID No. of the person who makes the order that were uploaded by the merchant are different to those of the person who makes the payment.

13.6 / Check Customs Declaration of Alipay

GET /alipay/declaration

Transfer one of the three parameters below. In case of separate customs declaration of each order, transfer sub_order_no; otherwise, transfer payment_no or out_order_no.

Parameter Description Mandatory Type Example
out_order_no Merchant order No. No String 201805181632038449
payment_no WiseCashier payment order No. No String 180512391816038449
sub_order_no Sub-order No. No String 18051816320384338

The following parameters are required if each order needs separate customs declaration:

Parameter Description Mandatory Type Example
out_order_no Merchant sub-order No. Yes String 2018051716124
payment_no Sub-order amount Yes float 46.44

The following parameters are required if identity verification is needed:

Parameter Description Mandatory Type Example
cert_id ID No. Yes String 510921199308772318
name Name Yes String Lisa

Returned results are as follows:

Parameter Description
out_order_no Merchant order No.
payment_no WiseCashier payment oder No.
customs Customs code
alipay_no Alipay receipt No.
state SUCCESS - successful
modify_time Last update time

The following parameters will be returned if each order needs separate customs declaration:

Parameter Description
sub_order_no Merchant sub-order No.
sub_order_amount Sub-order amount

The following parameter will be returned when an identity is verified:

Parameter Description
cert_check_result Identity verification result: T means the name and the ID No. of the person who makes the order that were uploaded by the merchant are same as those of the person who makes the payment. F means the name and the ID No. of the person who makes the order that were uploaded by the merchant are different to those of the person who makes the payment.

14 / Payment Notification

14.1 / Rules of Notification

14.2 / Contents of Notification

Field Description
status Order status. INIT: awaiting payment; PAID: payment successful; FAIL: payment failed; EXPIRED: payment order expired
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 Currency
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"
}

14.3 / Check Signature

Rules for signature:

  1. Sort the parameter names (form in POST request) by ASCII code in ascending alphabetical order (i.e. lexicographical sequence), then join them into a signature string in the URL key-value pair format (e.g. key1=value1&key2=value2…).
  2. Add the timestamp in header to the end of the signature string and separate them with “,” and thus a query_string is created.
  3. Use SHA-256 to authenticate the query_string and the signature included in the header.
  4. To get the public key, please contact WiseCashier.

15 / Appendix

15.1 / Description of Payment Order Data Structure

Field Description
no Payment order No.
merchant_no Merchant No.
currency Currency. Refer to 15.3 / Currency Code 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 Terminal IP address
product_id Product ID
trade_type Trade type
trade_time Trade time
agent_order_id Agent order No.
status Payment order status. INIT: awaiting payment; PAID: payment successful; FAIL: payment failed; EXPIRED: payment order expired
pay_method Payment method
refund_status Refund status. NONE: no refund; PART: partial refund; FULL: full refund
refundable_amount Refundable amount

15.2 / Description of Refund Order Data Structure

Field Description
no Refund order No.
order_no Payment order No.
outer_refund_no External refund order No.
refund_amount Refund amount
status Refund order status

15.3 / Currency Code

Currency 3-Character Code
CNY CNY
GBP GBP
HKD HKD
USD USD
JPY JPY
CAD CAD
AUD AUD
EUR EUR
NZD NZD
KRW KRW
THB THB

15.4 / WeChat Customs Code

Customs Code Customs Name
GUANGZHOU_ZS Guangzhou Customs
GUANGZHOU_HP_GJ Huangpu 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 Nansha Entry-Exit Inspection and Quarantine Bureau must be both submitted to Guangzhou Customs and Nansha 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

15.5 / Alipay Customs Code

Customs Name Overall Customs Declaration Solution Customs Code
Hangzhou Customs Push HANGZHOU_ZONGSHU HANGZHOU_ZONGSHU
Guangzhou Customs Push ZONGSHU ZONGSHU
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_ZS 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

15.6 / SDK and Sample Codes

http://s.transfereasy.com/wc/document/WiseCashier%20Java%20SDK.zip

C# sample codes of signature and signature verification: http://s.transfereasy.com/wc/document/Signature.cs