Product Introduction ¶

This method can call payment within WeChat official account or any H5 page within WeChat. Thus, merchants can integrate this payment method into their WeChat shopping malls or official accounts to improve user experience as well as to facilitate payment, foreign exchange and settlement for both merchants and customers. After integration, a payment button is added to the page.

• The customer clicks the payment button, and a payment page will be opened on his mobile phone.

• Once payment is successful, the merchant can check the payment result/status to decide the next operation step.

• Meanwhile, HipoPay will inform the merchant about the payment result via an asynchronous notification, which features a reliable built-in retry mechanism.

Payment Process and User Experience ¶

1. The customer shops goods or services within an official account or WeChat shopping mall:

2. The customer makes payment:

3. Payment is successful:

Integration Process ¶

1. Process digital signature

2. Integrate with Place Order

3. Call payment

4. Receive asynchronous notification

5. Integrate with refund API

6. Integrate with reconciliation API

Digital Signature ¶

Unless otherwise stated, all APIs require the siginature for HipoPay to confirm the identity of the user.。

HipoPay SDK has processed signature and signature verification and thus integration can be accelerated.

Python SDK

PHP SDK

JAVA SDK

NodeJS SDK

If it is not convenient to usd the SDK, perform the following steps to process signature.

I. Generate the private key and the public key.

• Private Key

Purpose: It performs paramter signing when the client requests the API.

Storage: Please keep it safe and properly. Do not reveal it to others.

Locally generated private key: openssl genrsa -out private.key 2048

• Public Key

Purpose: It is used for signature verification by HipoPay.

Storage: Please send it to HipoPay.

Locally generated public key: openssl rsa -pubout -in private.key -out public.key

II. Generate to-be-signed string.

1. Arrange the request parameters (query string of the GET request and form of the POST request) by parameter names based on the ASCII code in ascending lexicographical order, and use the URL key pair format (key1=value1&key2=value2…) to generate a signature string.

2. Append Timestamp to the signature string and separate them with a , to generate a to-be-signed string.

III. Generate the signature.

1. Encrypt the to-be-signed string by using RSA. Specify SHA256 as Hash algorithm, and use the private key in the key pair submitted when the service is requested.

2. Code the encryption result by using base64 to generate the final signature result.

IIII. Add the request header.

When the merchant sends the request, add the following four paramters in the header.

When receiving HipoPay asynchronous notification, the merchant should verify the signature to confirm that the notification is sent by HipoPay and is intact. The signature verification method is as follows:

Signature verification method:

1. Arrange the returned contents corrsponding to form of the POST request by parameter names based on the ASCII code in ascending lexicographical order, and use the URL key pair format (key1=value1&key2=value2…) to generate a signature string.

2. Append the Timestamp value in the header of the POSTrequest to the signature string and separate them with a ,to get the query_string.

3. Verify the query_string and the Signature value in the header of the POST request by using SHA-256. Contact HipoPay to obtain the public key.

Call Payment ¶

Perform the following three steps.

1. Step 1 Get user’s openid.

Guide consumer to click url as below:

Cross-border Wallet: https://api.wisecashier.com/mp_pay/oauth?merchant_no=xxx&currency=HKD
HongKong-Local Wallet: https://api.wisecashier.com/wechatpay/hk/oauth?merchant_no=xxx&currency=HKD

Other parameters are optional. All the parameters will be transferred back after user’s openid is obtained.
The parameters "currency" and "merchant_no" are mandatory.

We will run the payment page of the merchant 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).

Notice:
If merchant wanna use own page

Openid should be get by Back-end .
It’s not iframe, it's reverse proxy。 
You can't get it by browser.
That's because Wechat's rules, it only recognition domain of hipopay.com

2. Step 2 Place a payment order on the H5 payment page to get prepay params(prepay_params)

3. Use the prepayment parameter (prepay_params) to call payment. Refer to call payment within official account.

{
       "appId":"",
       "nonceStr":"",
       "package":"prepay_id=wxxxxxxxxxxxxxx",
       "paySign":"xxxxxxxxxxxxxxx",
       "signType":"MD5",
       "timeStamp":"1552631723"
}

{
    "is_success": True,
    "response": {
        "amount": "0.02",
        "currency": "HKD",
        "exchange_rate": "0.881890",
        "out_trade_id": "2746847384112837273872",
        "payment_no": "2018071823332342210483065",
        "status": "PAID",
        "product_info": "Alipay App Pay",
        "trade_time": "2018-07-18 23:33:23",
        "trade_type": "APP",
    }
}

{
    "is_success": False,
    "error": "PAYMENT_NOT_FOUND",
    "error_message" : "Order not found",
}

{
  "is_success": true,
  "response": {
    "currency": "USD",
    "forex_rate": "0.1490046489450470854690666349"
  }
}

{
    "is_success": False,
    "error": "CURRENCY_NOT_SUPPORT",
    "error_message" : "This currency is not supported",
}

{
  "is_success": true,
  "response": {
    "fail_message": "Settled Balance Not Enough",
    "finish_time": "2021-12-23 16:42:34",
    "out_refund_id": "R201901021232213",
    "payment_no": "2637473637382",
    "refund_amount": "8.88",
    "refund_no": "2637473637452",
    "result_code": "0011",
    "status": "FAIL"
  },
  "return_message": "OK"
}

{
    "is_success": False,
    "error": "REFUND_AMOUNT_INVALID",
    "error_message" : "Refund amount is invalid",
}

{
  "is_success": true,
  "response": {
    "finish_time": "2021-12-23 19:22:14",
    "out_refund_id": "R201637473637452",
    "payment_no": "2637473637382",
    "refund_amount": "8.88",
    "refund_no": "2637473637452",
    "result_code": "0000",
    "status": "SUCCESS"
  },
  "return_message": "OK"
}

{
    "is_success": False,
    "error": "REFUND_NOT_FOUND",
    "error_message" : "Refund order not found",
}

Test: company's reconciliation report of 20190101 to 20190120
Transaction Type,Transaction Time,Order No.,External order No.,Credit,Debit,Balance,Transaction Amount,Exchange Rate Adopted for Settlement,Service Fee,Refund Amount,Refund Order,External Refund Order No.,Fee for Withdrawal,Converted Currency,Exchange Rate Adopted for Conversion,Amount After Conversion,Payment Channel
Collection via WeChat Pay,2019-01-02 10:55:10,`2019010210551024660612990,`13260056057_wechat_1546397710000,0.99 HKD,-,1.06 HKD,1.00 HKD,1,0.01 HKD,-,-,-,-,-,-,-,WECHATPAYCN
Collection via WeChat Pay,2019-01-02 11:07:05,`2019010211070452703917004,`13260056057_wechat_1546398424000,0.99 HKD,-,2.05 HKD,1.00 HKD,1,0.00 HKD,-,-,-,-,-,-,-,WECHATPAYCN
Refund,2019-01-04 10:50:34,`2019010410503295208356067,`,-,-0.99 HKD,1.06 HKD,-,-,-,1.00 HKD,`2019010211070452703917004,`13260056057_wechat_1546398424000,-,-,-,-,WECHATPAYCN

"raw_response": "{
                "modify_time": "20190403171704", 
                "state": "UNDECLARED", 
                "cert_check_result": "SAME", 
                "transaction_id": "4200xxxxxxxx665", 
                "return_code": "SUCCESS", 
                "return_msg": "成功", 
                "sign": "23XxXxXxXx78E", 
                "sub_order_id": "42000002XXXXX8166500", 
                "mch_id": "1517456621", 
                "out_trade_no": "201904xxxxxxx26156", 
                "err_code_des": "OK", 
                "appid": "wx3zzzzzzz4", 
                "sub_order_no": "XXXXX", 
                "verify_department_trade_id": "42000002XXXXX8166500", 
                "verify_department": "NETSUNION", 
                "result_code": "SUCCESS", 
                "err_code": "0"
            }"

Currency Code ¶

Payment Order Status ¶

Refund Status ¶

Refund Code ¶