Mobile Browser (H5) - Alipay HK

AlipayHK WAP (Wireless Application Protocol) payment is a solution designed for mobile payment on the mobile browser. Customers can use their account and payment password to pay a bill from the mobile browser. After integrating the AlipayHK WAP payment service, both the Alipay and AlipayHK wallet are supported. You should present both the Alipay payment button and the AlipayHK payment button on your website for the buyers to complete the payment.

Step 0. Authentication

How to obtain access token Authentication Reference

Step 1. Initialize a Payment Intent

Create a Payment Intent with the Create a Payment API.

If you provide return_url when creating the Payment Intent to redirect shoppers back to your website, please make sure the domain of your return_url is the same as or a subdomain of the domain name you submitted in the H5 application. The WeChat Pay app will fail to be invoked if these domains are inconsistent. For example, if you submitted yourwebsite.com as your domain name when applying for H5, https://shop.yourwebsite.com/orders?id=123456 is acceptable as shop.yourwebsite.com is a subdomain of yourwebsite.com.

POST /mch-api/v1/pa/payment_intents/create

• Example Request

{
  "amount": "1",
  "currency": "HKD",
  "merchant_order_id": "P9297895081903",
  "payment_method": {
    "type": "alipayhk",
    "wechat": {
      "flow": "mobile_web",
      "payment_method": "ALIPAYCN"
    }
  },
  "description": "App Payment",
  "notify_url": "https://put_your_site_here/example_url"
}

• Request

REQUEST BODY	Details	Type	Required	Example
amount	Payment amount. This is the order amount you would like to charge your customer	string(32)	required
currency	Amount currency (alipay hk only support HKD)	string(32)	required	HKD
merchant_order_id	The order ID created in merchant's order system that corresponds to this PaymentIntent. Maximum length is 32.	string(32)	required
description	The description of the order	string	required
notify_url	The URL that is used to receive the payment result notification from CBTIS	string	optional
payment_method		object	required
- type	Specific this payment channel (alipayhk)	string	required	alipayhk
- alipayhk		object	required
-- flow	Specific the payment flow	string	required	mobile_web
-- payment_method	The wallet you want to payment with. The complete list of valid values: ALIPAYCN or ALIPAYHK	string	required	ALIPAYCN

You will get a response similar to the following.

{
  "code": 0,
  "data": {
    "order_id": "C991289984923795789123",
    "merchant_order_id": "P9297895081903",
    "amount": "1",
    "currency": "HKD",
    "create_time": "2023-08-31T04:44:05.928696203+08:00",
    "next_action": {
      "type": "redirect",
      "url": "https://intlmapi.alipay.com/gateway.do?_input_charset=UTF-8&body=order+description&currency=HKD"
    },
    "status": "PENDING"
  },
  "message": "ok",
  "rid": "3647575c0e1049439e484a231864da2c"
}

You should redirect the shopper to the WeChat Pay page with the next_action.url returned in the Payment response.

Node

• WeChat Pay will verify if the shopper is being redirected from an authorized website before invoking the app, so please make sure the domain of the mobile website that you plan to provide service to the shopper is the same as or a subdomain of the domain you submitted in the H5 application.

• Redirect the shopper from mobile app Webview to WeChat Pay H5 page is not officially supported by WeChat Pay. Please use mobile_app when integrating WeChat Pay with your mobile app.

Step 2. Get payment notify

Once you fill in the notify_url field when creating an order, after the user completes the payment, our system will prompt you with information about the user's completed payment.

How to verify our notify message Webhook Verify Reference

• Example Webhook

{
  "notify_type": "payment_success",
  "data": {
    "order_id": "C991289984923795789123",
    "merchant_order_id": "P9297895081903"
  }
}

Step 3. Retrieve a payment

Retrieve a Refund by ID.

POST /mch-api/v1/pa/payment_intents/query

• Example Request

{
  "order_id": "P991289984923795789123",
  "merchant_order_id": "P9297895081903"
}

• Request

REQUEST BODY	Details	Type	Required	Example
order_id	Platform order id from payment request.	string(32)	conditional (required if merchant_order_id is empty)
merchant_order_id	Merchant order id from your creation of payment.	string(32)	conditional (required if order_id is empty)

• Example Response

{
  "code": 0,
  "data": {
    "order_id": "C991289984923795789123",
    "merchant_order_id": "P9297895081903",
    "amount": "50",
    "currency": "TWD",
    "status": "SUCCEEDED",
    "create_time": "2023-08-31T04:44:05.928696203+08:00",
    "pay_time": "2023-08-31T04:44:05.928696203+08:00"
  },
  "message": "ok",
  "rid": "3647575c0e1049439e484a231864da2c"
}

• Explain of status

STATUS CODE	Details
PENDING	The Payment is pending the final result from the provider. No further action is required.
SUCCEEDED	The Payment has succeeded. The payment transaction is complete.
CANCELLED	Payment canceled or timeout, user has not completed the payment and the order has been closed.