AlipayHKAlipayHKDOCS

Quick integration

Prerequisites                           

Before you integrate with the Auto-Debit payment method, complete the following steps:

  1. Sign contracts with AlipayHK and get the clientID and a merchantID assigned by AlipayHK per contract.
  2. Generate your own SHA1WithRSA key pairs and use it to exchange for AlipayHK public key. You need to send your key pairs to AlipayHK though an offline channel, and AlipayHK will return the AlipayHK public key to you after corresponding configurations are made accordingly.

Implementing API List 

AlipayHK does not recommend any order for implementing the APIs. However, AlipayHK requires that all APIs listed in the following sections need to be implemented.

Interfaces for the in-app payment service

alipay.intl.acquiring.cashier.wap.pay

With the alipay.intl.acquiring.cashier.wap.pay interface, merchants can use JSAPI TradePay to place an order.

Interfaces for the auto-debit service

alipay.intl.oauth.auth.prepareForRedirect

You can use this interface to get a URL to start the oAuth flow. 

In general, the authSite (AlipayHK server) returns a URL to which the customer will be directed for further authentication purpose.

Request Key Parameters：

  • merchantRedirectUrl: can be used by merchants to specify the redirect URL in the prepareForRedirect API call. After user’s successful authorization, merchants will be notified of this one-time authCode via the merchantRedirectUrl field. Merchants can use this authCode to apply for the AccessToken. 
  • authMerchantId: auth merchant ID. The auth merchant is the merchant that is authorized by users to access user resources. 
  • agreementPayAuthInfo: pay authorization information. In auto-debit binding process, merchants need to generate the unique merchantAgreementID and maintain the agreement status. 

Response Key parameters:

authSiteURL: returned by AlipayHK auth site as the redirect URL after user’s signing request. Users will be redirected to the authSiteURL for authorization via merchant web view.

alipay.intl.oauth.auth.applyToken

You can use this interface to get access token from the authSite. To invoke this interface, you need to use the authCode obtained from the alipay.intl.oauth.auth.prepareForRedirect interface.

Request Key Parameters:

  • authCode: authorization code, generated by the authSite to return back to merchants. The authCode is a one-time authorization code from the authSite and expires in 10 minutes. If the authorization code expired, the signing process needs to be re-initiated and ask users for authorization again.

Response Key Parameters:

  • accessToken: returned after a successful applyToken request and will be used for calling the alipay.intl.acquiring.agreement.pay interface.

alipay.intl.oauth.auth.cancelByAuthInfo

You can use this interface to cancel an existing oAuth authorization.

alipay.intl.oauth.auth.queryByAuthInfo

You can use this interface to query the details of an oAuth authorization.

alipay.intl.acquiring.agreement.pay

You can use this interface to make an automatic deduction from the binded account, by using the correct accessToken.

Request Key Parameters：

  • accessToken: the authorization between the user and merchant. The merchant needs to provide the correct accessToken for each alipay.intl.acquiring.agreement.pay request. 

Response Key Parameters：

  • acquirementId: the unique AlipayHK transaction ID and can be used as the cancel and refund transaction ID when needed. 

alipay.intl.acquiring.common.payQuery

You can use this interface to query the payment result.

alipay.intl.acquiring.common.payCancel

You can use this interface to cancel a transaction. 

alipay.intl.acquiring.common.refund

You can use this interface to refund an existing payment.

Testing in Sandbox Environment.

You can get a sandbox testing account per your need by contacting AlipayHK technical support team.