Product Introduction ¶

Nowadays, more and more Chinese customers directly shop from the stores of overseas merchants via their mini-programs. Thus, merchants can integrate our payment solution into their mini-programs to improve user experience by providing them with the familiar and comfortable payment method, as well as to facilitate payment, foreign exchange and settlement for both merchants and customers. After integration, a payment button is added to the mini-program.

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

The SDK of HipoPay with a full set of mobile payment interfaces provides merchants with convenient, safe and reliable payment services.

Payment Process and User Experience ¶

1. The customer shops goods or services within a mini-program:

2. The customer makes payment:

3. Payment is successful:

Integration Process ¶

1. Process digital signature

2. Integrate with Place Order

3. Call payment in your mini-program

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 in Your Mini-Program ¶

Perform the following three steps.

1. Get user’s openid. Refer to mini-program login.

2. Call the order placement API to obtain the prepayment parameter.

3. Use the prepayment parameter to call payment. Refer to call payment in mini-program

{
    "is_success": True,
    "response": {
        "amount": "0.10",
        "currency": "HKD", 
        "exchange_rate": "0.881890",
        "out_trade_id": "d2849e8140a6",
        "payment_no": "2018081316331654230251111",
        "status": "INIT",
        "product_info": "Wechat Mini Program Pay",
        "trade_time": "2018-08-13 16:33:16",
        "finish_time": "2018-08-13 16:33:16",
        "trade_type": "MINIPROGRA",
"prepay_params": {
          "nonceStr": "572666791269",
          "order_no": "2019021911592704114199308",
          "paySign": "466790B2486C24F2DE0BD4C77C7D22AB",
          "prepay_id": "wx19115928908673c06a1d48960711201017",
          "timeStamp": "1550548767"
        },
    }
}

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

{
    "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 ¶