支付宝sdk是否支持对接香港支付宝支付？

2026-10-24支付老李

结论

支付宝 SDK 可以接入香港地区的相关支付能力，但”香港支付宝支付”通常包含两种场景，安装 SDK 并不等于已经开通服务：

接受 AlipayHK（支付宝香港）钱包付款，通常需要申请 Alipay+ 跨境收单，或通过支持 AlipayHK 的收单机构接入。
香港商户接入支付宝付款，需要申请面向港澳或国际商户开放的支付宝产品，并以相应主体完成签约。

能否使用以及需要调用哪套 API，取决于商户注册地区、签约产品、收单渠道和支付场景。中国内地支付宝商户已有的 app_id，默认不包含 AlipayHK 收款权限。

接入前需要准备什么

商户及签约资料

通常需要准备以下资料：

香港公司注册证明、商业登记证等主体材料；
法定代表人、董事或最终受益人的身份资料；
商户经营网站、App、门店信息及业务说明；
商品或服务类别、预计交易金额和交易地区；
香港或收单机构认可的结算银行账户；
客服联系方式、退款政策及隐私政策；
PCI DSS 等合规材料，仅在商户直接处理银行卡信息等特定场景下需要。

个人商户、香港公司和中国内地公司需要提交的材料可能不同，具体以支付宝或实际收单机构提供的审核清单为准。

技术参数

完成签约并创建应用后，一般需要取得或确认以下参数：

商户号或合作伙伴编号；
应用标识，例如 app_id 或客户端标识；
API 网关地址；
商户私钥；
支付平台公钥或平台证书；
签名算法，常见的是 RSA2，具体以接入文档为准；
异步通知地址 notify_url；
支付完成后的跳转地址 return_url，仅部分网页支付场景需要；
支持的交易币种和结算币种，例如 HKD；
产品代码、支付场景或钱包类型；
沙箱及生产环境配置。

不同开放平台使用的字段名称并不完全相同，不能直接把中国内地支付宝开放平台的参数名称套用到 Alipay+ 接口。

推荐的接入步骤

1. 先确定实际支付场景

先向业务方确认以下信息：

付款人使用 AlipayHK，还是中国内地支付宝；
商户主体注册在香港、中国内地还是其他地区；
通过 App、H5、网页、二维码还是线下 POS 收款；
订单以 HKD、CNY 还是其他币种计价；
由支付宝直接收单，还是通过银行、支付服务商或聚合支付平台收单。

这些信息决定了需要签约的产品、使用的 API 和 SDK，以及具体的结算方式。

2. 申请对应产品并完成审核

在支付宝国际业务平台、Alipay+ 或授权收单机构申请相应产品。审核通过后，还要确认合同或商户后台明确包含 AlipayHK 钱包，而非仅支持中国内地支付宝。

如果商户后台没有对应的产品权限，即使 SDK 初始化和签名均无误，请求仍可能遭到拒绝。

3. 创建应用并配置密钥

生产环境应单独生成 RSA 密钥，并妥善保管私钥。不要把私钥提交到 Git 仓库、写入前端代码或直接硬编码到源码中。

下面是一份通用的 Java 配置示例。类名和构造参数仅适用于使用支付宝开放平台 Java SDK 的接口。如果签约的是 Alipay+ 产品，需要改用对应的 SDK 和配置方式。

String appId = System.getenv("ALIPAY_APP_ID");
String merchantPrivateKey = System.getenv("ALIPAY_PRIVATE_KEY");
String alipayPublicKey = System.getenv("ALIPAY_PUBLIC_KEY");
String gatewayUrl = System.getenv("ALIPAY_GATEWAY_URL");

AlipayClient alipayClient = new DefaultAlipayClient(
    gatewayUrl,
    appId,
    merchantPrivateKey,
    "json",
    "UTF-8",
    alipayPublicKey,
    "RSA2"
);

网关地址、产品代码和接口名称应从已签约产品的开发文档或商户后台获取，不要自行猜测。

4. 创建支付订单

创建订单时，至少需要维护以下信息：

商户订单号；
订单金额；
订单币种；
商品或服务描述；
支付场景；
支付结果通知地址；
订单有效期；
商户或门店信息。

业务层的通用请求数据可以抽象为：

{
  "merchantOrderNo": "HK202609090001",
  "amount": {
    "currency": "HKD",
    "value": "100.00"
  },
  "subject": "订单商品",
  "notifyUrl": "https://merchant.example.com/payment/notify"
}

这只是业务层示例，并不是某个具体支付宝接口的完整请求。实际字段名、金额单位和嵌套结构必须遵循所签约接口的规定。有些接口使用字符串表示金额，有些则使用最小货币单位，两者不能混用。

5. 验证异步通知并主动查询订单

支付成功页面只用于改善用户体验，不能作为最终到账依据。服务端收到异步通知后，应执行以下检查：

验证通知签名；
检查通知中的商户号或应用标识；
核对商户订单号；
核对金额和币种；
检查支付状态；
对订单进行幂等更新；
必要时调用订单查询接口复核结果。

伪代码如下：

public String handleNotify(Map<String, String> params) {
    boolean signatureValid = verifySignature(params);

    if (!signatureValid) {
        return "failure";
    }

    Order order = orderService.findByOrderNo(params.get("merchant_order_no"));
    if (order == null) {
        return "failure";
    }

    if (!amountAndCurrencyMatched(order, params)) {
        return "failure";
    }

    if (isPaymentSucceeded(params)) {
        orderService.markPaidIdempotently(order);
    }

    return "success";
}

通知字段和需要返回的确认字符串由具体接口定义，不能直接照搬示例中的名称。

常见误区

SDK 可用不等于产品权限已开通

SDK 主要用于封装请求、签名和验签。商户能否接受 AlipayHK 付款，取决于已签约的产品和商户权限。

AlipayHK 与中国内地支付宝不是同一个钱包

两者属于不同的钱包和运营体系。即使用户界面相似，支持范围、币种、风控、清算方式和接口产品也可能不同。

不要强制指定未经授权的钱包类型

如果产品通过收银台自动展示可用的付款方式，通常应由平台根据用户、地区和合同权限决定展示内容。只有接口文档明确支持时，才能传入指定钱包或支付方式的参数。

注意币种与汇率

接入时需要确认交易币种、扣款币种和结算币种是否一致，还要明确汇率由商户、收单机构还是支付平台提供。退款也应使用原交易币种，并关联原支付订单信息。

沙箱结果不能代表生产权限

沙箱主要用于验证接口流程。生产环境仍需完成商户审核、产品签约、域名配置、证书配置和风控检查。

接入前，应先向支付宝或收单服务商确认三项信息：商户主体可以签约哪项产品、该产品是否明确支持 AlipayHK，以及应使用哪套 API 文档和 SDK。取得正式产品名称后，再按照对应文档准备参数并实施代码。