Apple Pay Web 会话

Apple Pay Web 会话 API 使商户能够在 onvalidatemerchant 事件期间向 Apple Pay 验证其域名。当客户在网页上发起 Apple Pay 交易时调用此 API，Apple Pay 要求商户在允许支付继续之前证明其身份。

此 API 返回一个会话对象，必须传递给 completeMerchantValidation 方法以完成 Apple Pay Web 验证过程。

集成前置条件

在实施 Apple Pay Web 会话验证之前，请确保您具备：

• 有效的 Apple Pay 商户账户，且域名验证已完成
• Apple Pay 商户证书已正确配置
• 可访问 Onerway 支付网关 API
• 已在您的网站上实现 Apple Pay Web 集成
• 具备处理异步验证流程的技术能力

Apple Pay Web 会话用途

Apple Pay Web 会话验证是 Apple Pay Web 集成过程中的关键步骤：

1. 域名验证：证明您的域名已获得授权接受 Apple Pay 支付
2. 安全性：确保只有经过验证的商户才能处理 Apple Pay 交易
3. 会话管理：提供临时会话数据以完成 Apple Pay 授权
4. 实时处理：必须在 onvalidatemerchant 事件触发时立即处理

API 请求参数

POST

Parameter	Type	Length	Required	Signed	Description
appId	String	20	Yes	Yes	Merchant application ID assigned by Onerway for website identification.
merchantNo	String	20	Yes	Yes	Merchant number assigned by Onerway upon registration, obtained from the Onerway merchant dashboard.
requestId	String	64	Yes	Yes	Unique request identifier for tracking and deduplication.
sign	String	/	Yes	No	Digital signature string for request verification and security. Please refer to Signature for signature generation method.
verifyUrl	String	256	Yes	Yes	Apple Pay validation URL from the payment session event.
website	String	128	Yes	Yes	Merchant website domain name registered with Apple Pay.

响应

Name	Type	Description
respCode	String	Response code from Onerway
respMsg	String	Response message from Onerway
data	Object	Response data. Refer to object data

data

data 字段包含 Apple Pay 会话信息的 JSON 字符串：

Name	Type	Description
└─ data	String	Apple Pay merchant session data as JSON string. This data should be passed directly to the Apple Pay session completion handler.

集成流程

Apple Pay Web 会话 API 在 Apple Pay Web 集成流程中使用：

集成步骤

1. 初始化 Apple Pay 会话：在网页上创建 Apple Pay 会话
2. 处理验证事件：监听 onvalidatemerchant 事件
3. 调用会话 API：将验证 URL 发送到 Onerway 的 Apple Pay Web 会话 API
4. 完成验证：将返回的会话数据传递给 completeMerchantValidation
5. 继续支付：继续 Apple Pay 支付流程

API 使用示例

请求示例

请求

{
  "appId": "1727880846378401792",
  "merchantNo": "800209",
  "requestId": "ZYRDGXQSDEUMFFXVWEU",
  "sign": "c46ea8b12bcc3392a6b8a58207a71f634442a8ea650d7cdb97494e1ec5f413c9",
  "verifyUrl": "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession",
  "website": "rundown-beret.biz"
}

响应

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": "{\"epochTimestamp\":1752027594903,\"expiresAt\":1752031194903,\"merchantSessionIdentifier\":\"SSHC70E8352BAB64DA1ABD5534864FB1D7D_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24\",\"nonce\":\"493ee68c\",\"merchantIdentifier\":\"A719B735608A23CC132E86CF3C67E22C446673B495D53A28FD2FA671B5B86C87\",\"domainName\":\"rundown-beret.biz\",\"displayName\":\"rundown-beret.biz\",\"signature\":\"308006092a864886f70d010702a0803080020101310d300b0609608648016503040201308006092a864886f70d0107010000a080308203e43082038ba003020102020859d8a1bcaaf4e3cd300a06082a8648ce3d040302307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553301e170d3231303432303139333730305a170d3236303431393139333635395a30623128302606035504030c1f6563632d736d702d62726f6b65722d7369676e5f5543342d53414e44424f5831143012060355040b0c0b694f532053797374656d7331133011060355040a0c0a4170706c6520496e632e310b30090603550406130255533059301306072a8648ce3d020106082a8648ce3d030107034200048230fdabc39cf75e202c50d99b4512e637e2a901dd6cb3e0b1cd4b526798f8cf4ebde81a25a8c21e4c33ddce8e2a96c2f6afa1930345c4e87a4426ce951b1295a38202113082020d300c0603551d130101ff04023000301f0603551d2304183016801423f249c44f93e4ef27e6c4f6286c3fa2bbfd2e4b304506082b0601050507010104393037303506082b060105050730018629687474703a2f2f6f6373702e6170706c652e636f6d2f6f63737030342d6170706c65616963613330323082011d0603551d2004820114308201103082010c06092a864886f7636405013081fe3081c306082b060105050702023081b60c81b352656c69616e6365206f6e207468697320636572746966696361746520627920616e7920706172747920617373756d657320616363657074616e6365206f6620746865207468656e206170706c696361626c65207374616e64617264207465726d7320616e6420636f6e646974696f6e73206f66207573652c20636572746966696361746520706f6c69637920616e642063657274696669636174696f6e2070726163746963652073746174656d656e74732e303606082b06010505070201162a687474703a2f2f7777772e6170706c652e636f6d2f6365727469666963617465617574686f726974792f30340603551d1f042d302b3029a027a0258623687474703a2f2f63726c2e6170706c652e636f6d2f6170706c6561696361332e63726c301d0603551d0e041604140224300b9aeeed463197a4a65a299e4271821c45300e0603551d0f0101ff040403020780300f06092a864886f76364061d04020500300a06082a8648ce3d0403020347003044022074a1b324db4249430dd3274c5074c4808d9a1f480e3a85c5c1362566325fbca3022069369053abf50b5a52f9f6004dc58aad6c50a7d608683790e0a73ad01e4ad981308202ee30820275a0030201020208496d2fbf3a98da97300a06082a8648ce3d0403023067311b301906035504030c124170706c6520526f6f74204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553301e170d3134303530363233343633305a170d3239303530363233343633305a307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b30090603550406130255533059301306072a8648ce3d020106082a8648ce3d03010703420004f017118419d76485d51a5e25810776e880a2efde7bae4de08dfc4b93e13356d5665b35ae22d097760d224e7bba08fd7617ce88cb76bb6670bec8e82984ff5445a381f73081f4304606082b06010505070101043a3038303606082b06010505073001862a687474703a2f2f6f6373702e6170706c652e636f6d2f6f63737030342d6170706c65726f6f74636167332e30370603551d1f0430302e302ca02aa0288626687474703a2f2f63726c2e6170706c652e636f6d2f6170706c65726f6f74636167332e63726c300e0603551d0f0101ff0404030201063010060a2a864886f7636406020e04020500300a06082a8648ce3d040302036700306402303acf7283511699b186fb35c356ca62bff417edd90f754da28ebef19c815e42b789f898f79b599f98d5410d8f9de9c2fe0230322dd54421b0a305776c5df3383b9067fd177c2c216d964fc6726982126f54f87a7d1b99cb9b0989216106990f09921d00003182018830820184020101308186307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553020859d8a1bcaaf4e3cd300b0609608648016503040201a08193301806092a864886f70d010903310b06092a864886f70d010701301c06092a864886f70d010905310f170d3235303730393032313935345a302806092a864886f70d010934311b3019300b0609608648016503040201a10a06082a8648ce3d040302302f06092a864886f70d010904312204206eea5fe324e35a0f4a87d568594a2334f3ad5e52ea2d1ad9b6de048605c83fda300a06082a8648ce3d04030204473045022100eff116376d607a5c43681ffe5ade91eafd5640723b8ff00a0a8f2b934f42d18e022059139c887992a14f6fa5fc61b3f3ba4ed454d1a295a6952d9068e561eb027f70000000000000\",\"operationalAnalyticsIdentifier\":\"rundown-beret.biz:A719B735608A23CC132E86CF3C67E22C446673B495D53A28FD2FA671B5B86C87\",\"retries\":0,\"pspId\":\"A719B735608A23CC132E86CF3C67E22C446673B495D53A28FD2FA671B5B86C87\"}"
}

JavaScript 集成示例

// Apple Pay Web 集成示例
const session = new ApplePaySession(3, paymentRequest);

session.onvalidatemerchant = async (event) => {
  try {
    // 调用 Onerway Apple Pay Web 会话 API
    const response = await fetch('/api/txn/apiCheckApplePay', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        appId: '1727880846378401792',
        merchantNo: '800209',
        requestId: generateRequestId(),
        sign: generateSignature(),
        verifyUrl: event.validationURL,
        website: window.location.hostname
      })
    });

    const result = await response.json();
    
    if (result.respCode === '20000') {
      // 解析会话数据并完成验证
      const sessionData = JSON.parse(result.data);
      session.completeMerchantValidation(sessionData);
    } else {
      session.abort();
    }
  } catch (error) {
    console.error('Apple Pay 验证失败:', error);
    session.abort();
  }
};

session.begin();

常见错误场景

无效域名配置

错误：域名未在 Apple Pay 中注册
原因：website 参数与您的 Apple Pay 商户配置中注册的域名不匹配
解决方案：确保您的域名已在 Apple Pay 中正确注册和验证

验证 URL 过期

错误：Apple Pay 验证 URL 已过期
原因：来自 onvalidatemerchant 事件的 verifyUrl 已过期
解决方案：在事件触发时立即处理验证请求

无效签名

错误：请求签名验证失败
原因：sign 参数不正确或使用错误参数生成
解决方案：验证您的签名生成过程并确保包含所有参数

会话超时

错误：Apple Pay 会话超时
原因：商户验证过程耗时过长
解决方案：优化验证流程以在 Apple Pay 的超时限制内完成

实施最佳实践

1. 立即处理验证：在 onvalidatemerchant 事件触发后立即调用 API
2. 安全域名注册：确保您的域名已在 Apple Pay 中正确注册和验证
3. 错误处理：为验证失败实施健壮的错误处理
4. 会话管理：立即使用返回的会话数据调用 completeMerchantValidation
5. 超时处理：为验证过程实施超时处理
6. 安全性：始终验证签名并对所有通信使用 HTTPS

商户集成检查清单

• 域名已在 Apple Pay 中注册和验证
• Apple Pay 商户证书已配置
• onvalidatemerchant 事件处理程序已实现
• API 集成已配置正确的签名生成
• 验证失败的错误处理已实现
• 会话超时处理已实现
• 所有 Apple Pay 交互均已启用 HTTPS
• 已在 Apple Pay 沙盒环境中完成测试