Product Introduction ¶

With this payment method, the customer uses his mobile phone to scan the QR code displayed by the merchant. This payment method is mainly used by Chinese customers who shop in overseas stores. Merchants can integrate this payment method into their cashier system 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, an Alipay payment collection button is added to the cashier system/software.

• The cashier clicks the payment collection button, and then a QR code is displayed.

• The customer needs to open Alipay app to scan this QR code to complete payment.

• 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 merchant clicks the Alipay payment collection button:

2. A payment collection code is generated:

3. The customer opens Alipay app to scan the QR code to complete payment:

Integration Process ¶

1. Process digital signature

2. Integrate with order placement API

3. Receive asynchronous notification

4. Integrate with refund 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.

{
    "is_success": True,
    "response": {
        "amount": "0.10",
        "currency": "HKD", 
        "exchange_rate": "0.881890",
        "out_trade_id": "d2849e8140a6",
        "payment_no": "2018081316331654230251111",
        "status": "INIT",
        "product_info": "Alipay QRCODE Pay",
        "trade_time": "2018-08-13 16:33:16",
        "finish_time": "2018-08-13 16:33:16",
        "trade_type": "NATIVE",
        "qrcode_url": "https://unitradeprod.alipay.com/exterfaceAssign.htm?...&qrcode_width=200&sign_type=RSA", 
    }
}

{
    "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.1488471786017296042153520980"
  }
}

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

Currency Code ¶

Payment Order Status ¶

Refund Status ¶

Refund Code ¶