AlipayHKAlipayHKDOCS

Introduction

Audience

This document targets at the technical person who is intending to integrate with the Barcode Payment solution.

Conventions

Interface

In this context, the interface is the channel that the AlipayHK system provides the relevant service by invoking the corresponding APIs with the required parameter values. Throughout this guide, we might use interface and service interchangeably.

Barcode payment introduction

The barcode/QR Code payment is an offline instant payment solution offered by Alipay for the in-store checkout. Merchants who have business entities in Hong Kong can implement this payment solution. With this payment solution, merchants can collect money by scanning the barcode/QR code that is shown on a customer's app, and both Alipay wallet and AlipayHK wallet apps are supported.

Differences between HK Barcode payment and the standard barcode payment

The target audience for this section is the partners who have already integrated with Alipay Standard Barcode Payment Solution in other regions.

This section will help the partners' product and technical team to have a general idea on the differences between HK Barcode payment solution and the standard barcode payment solution.

Application scenario

Only merchants who have business entities in Hong Kong can apply for the HK barcode payment solution. With this payment solution, merchants can collect money by scanning the barcode or QR code that is shown on a customer's app. In addition, both Alipay wallet and AlipayHK wallet apps are supported. Alipay will settle the fund to the partner or merchant in HKD.

Commission fee

The commission fee is charged in HKD.

API

The following changes are made to APIs of HK barcode payment solution:

alipay.acquire.overseas.spot.pay

  • Remove two response parameters: exchange_rate, trans_amount_cny
  • Add a new error code: NOT_SUPPORT_PAYMENT_INST

This parameter indicates the Alipay wallet type is not supported for this partner ID. For example, making transaction using AlipayHK app's barcode with the standard barcode payment solution will return this error.

  • Add a response parameter: payment_inst = ALIPAYHK or ALIPAYCN

This parameter indicates the Alipay wallet type.

alipay.acquire.overseas.spot.refund

  • The value of the currency parameter cannot be specified as CNY.
  • Remove two response parameters: exchange_rate, trans_amount_cny
  • Add a parameter: is_sync

      This parameter indicates whether it's a sync refund or not.

       Sync Refund vs. Async Refund

Sync refund:

Real-time refund and notify the merchant the result in real time.

Async refund:

Alipay will first reply a SUCCESS result indicating that Alipay has received and recorded the refund request, and then process the request in batch mode starting from 23:00 PM GMT+8.

alipay.acquire.overseas.query

  • Remove two response parameters: exchange_rate, trans_amount_cny
  • Add a response parameter: payment_inst = ALIPAYHK or ALIPAYCN

This parameter indicates the Alipay wallet type. The value is not returned when the payment status is UNKNOW. You can query the wallet type by using the QUERY interface.

Offline reconciliation files

Changes are made in both transaction and settlement files.

The following RMB rate related parameters are removed:

  • Rate
  • Rmb_amount
  • Rmb_settlement

The following parameters are added:

  • Trans_currency
  • Trans_amount
  • Trans_forex_rate
  • payment_inst

Customer Support

For technical questions, please contact Global Merchant Technical Support (overseas_support@service.alibaba.com). 

For non-technical questions, such as how to sign up with AlipayHK, please contact Global Merchant Business Support (global.service@alipay.com).