Product Introduction ¶

Nowadays, more and more Chinese customers directly shop from the stores of overseas merchants via their shopping apps. Thus, merchants can integrate our mobile payment solution into their apps 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 app.

• The customer clicks the payment button, and Alipay app will be opened on his mobile phone. Then, the customer can log in to complete payment.

• Once payment is successful, the customer returns to the shopping app of the merchant. 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 ¶

This product applies to wireless Android and iOS devices, including mobile phones and tablets. The following takes the mobile with iOS system as an example:

1. The customer shops goods or services through the mobile app:
2. The customer logs in to make payment:
3. Alipay app is called to complete the payment:
4. Payment is successful:
5. Transaction is complete. Customer can check transaction information:

Integration Process ¶

1. Process digital signature

2. Integrate with order placement API

3. Call payment (application SDK) in merchant’s app

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.

Application Demo ¶

To call payment within merchant’s app, the Demo provided by HipoPay is required.

• iOS DEMO: Download

• Android DEMO: Download

{
    "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 App Pay",
        "trade_time": "2018-08-13 16:33:16",
        "finish_time": "2018-08-13 16:33:16",
        "trade_type": "APP",
        "prepay_params": "_input_charset=\"utf-8\"&currency=\"HKD\"&forex_biz=\"FP\"&notify_url=\"http://....&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 ¶