AlipayHKAlipayHKDOCS

Base API

POST  /api/open/alipay/intl/promotion/order/contractCardSync

Environment

Domain

Production

open.alipay.hk

Testing

open-id-pre.alipay.com

Use this interface to send performance notification service request to AlipayHK.

Request

Headers

Please check API Structure for basics.

Body

Name

Description

Type

Sample

bizDate

required

Business event occurrence timestamp, used for sequential control of order status or rapidly changing data to prevent disorder.

Number

1632833743000

command
required

Operation commands for performance notifications, valid input includes:

  • SEND
    • Generates a new notification if not exists or invalid
    • Returns UN_SUPPORT_BUSINESS otherwise
  • UPDATE
    • Updates information of notification if exists and valid
    • Ignores if notification is invalid
    • Returns ORDER_NOT_FOUND otherwise

String

"SEND"

syncDataInfo
required

An extended object information for updating the notification.

Please reference to the datainfo below.

SyncDataInfo

See SyncDataInfo.

merchantBizNo
required

An order ID specified by merchant, must be consistent to reference the same notification.

String

"20240524000001"

orderStatus
required

Status of the order.

Please reference to each business domain.

String

"WAIT_PAY"

productTemplateCode
required

A notification template code provided by AlipayHK.

  • AIR_TICKET_DEFAULT
  • FINANCE_ORDER_DEFAULT
  • MOVIE_TICKET_DEFAULT
  • PAYMENT_ORDER_DEFAULT
  • RIDE_HAILING_DEFAULT
  • TRAIN_TICKET_DEFAULT

String

"PAYMENT_ORDER_DEFAULT"

requestId
required

An unique request ID (uuid) to identify this API request.

String

"d1c221e1-5993-4162-bdbf-f06f33389472"

endDate

A timestamp indicates the expiry date of notification, 24 hours from created for each order by default.

Number

1632833743000

openId

conditional

Authorization ID of AlipayHK user for merchant.

required to provide either openId or userId.

String

userId
conditional

ID of AlipayHK user.

required to provide either openId or userId.

String

"2160xxxxxxxxxxxx"

SyncDataInfo

Name

Description

Type

Sample

languageBusinessInfo
required

An object providing business dedicated display information of different locale, key must be zh_HK or en_US.

Performance notifications will be hided if user switched to a language not provided.

BusinessInfo

{

"zh_HK": "JSONString(BusinessInfo)",

"en_US": "JSONString(BusinessInfo)"

}

amount

Total amount of the order in cents. 

(1 for $0.01, 100 for $1)

Number

100000

amountCurrency
conditional

required if amount is provided, support HKD or CNY.

String

"HKD"

merchantOrderDetailUrl

The URL reference of the order details.

String

"alipayhk://platformapi/startapp?appId=2102020185475244&page=pages/alipay/orderDetail/index?orderCode=20240421389609183133&query="

payAmount

Actual paying amount in cents.

(1 for HKD 0.01, 100 for 1 HKD)

Number

10000

payAmountCurrency
conditional

required if payAmount is provided, support HKD or CNY.

String

"HKD"

tinyAppId

ID of merchant's miniprogram.

String

"2102020185475244"

tradeNo

Transaction number of this order from AlipayHK.

String

Example

copy
{
    "merchantId": "216022000000xxx",
    "userId": "2160220044640xxx",
    "requestId": "1111110000000000001",
    "command": "SEND",
    "merchantBizNo": "GDBJ0529000000000001",
    "orderStatus": "WAIT_PAY",
    "bizDate": 1632833743000,
    "productTemplateCode": "PAYMENT_ORDER_DEFAULT",
    "syncDataInfo": {
        "tinyAppId": "12333",
        "languageBusinessInfo": "{\"zh_HK\":{\"bill_desc\":\"煤氣十月賬單已發出\",\"bill_name\":\"煤氣賬單\",\"bill_moth_time\":\"2024-10\",\"bill_due_time\":\"2024-10-15\",\"bill_amount\":\"57000\",\"bill_amount_currency\":\"HKD\",\"action_url\":\"alipayhk://platformapi/startapp?appId=2102020185475244&page=pages/alipay/orderDetail/index?orderCode=20240421389609183133\",\"order_Url\":\"alipayhk://platformapi/startapp?appId=2102020185475244&page=pages/alipay/orderDetail/index?orderCode=20240421389609183133\"},\"en_US\":{\"bill_desc\":\"OCT Gas Bill Issued\",\"bill_name\":\"Gas BILL\",\"bill_moth_time\":\"2024-10\",\"bill_due_time\":\"2024-10-15\",\"bill_amount\":\"57000\",\"bill_amount_currency\":\"HKD\",\"action_url\":\"alipayhk://platformapi/startapp?appId=2102020185475244&page=pages/alipay/orderDetail/index?orderCode=20240421389609183133\",\"order_Url\":\"alipayhk://platformapi/startapp?appId=2102020185475244&page=pages/alipay/orderDetail/index?orderCode=20240421389609183133\"}}"
    }
}

For languageBusinessInfo, please check the relevant business scenario.

Response

Headers

Please check API Structure for basics.

Body

Please check API Structure for basics.

Example

copy
{
   "result":{
      "resultStatus":"S",
      "resultCode":"SUCCESS",
      "resultMessage":"success"
   }
}

Error Handling

Result Codes

Result Code

Result Status

Remarks

SUCCESS

S

Request is successful.

ORDER_NOT_FOUND

F

The merchantBizNo is invalid.

ORDER_STATUS_INVALID

F

Order status is invalid, please refer to the relevant business scenario.

PARAM_ILLEGAL

F

Request is invalid, usually missing parameters.

UNKNOWN_EXCEPTION

F

Unknown exception, please check with support.

UN_SUPPORT_BUSINESS

F

Service is not available, please check with support.