Opayo 3DSecure API支付完成请求报错：商户会话密钥/卡标识无效

背景 #

我们的网站使用Opayo的https://live.opayo.eu.elavon.com/api/v1/transactions API处理支付，当前触发1011错误（商户会话密钥或卡片标识符无效），以下是详细流程及请求响应信息：

用户支付流程 #

• 用户进入购买流程并输入卡片信息
• 系统跳转至3DSecure验证门户
• 用户完成银行验证后，我方收到transStatus为"Y"的3DS响应
• 我方尝试发起支付完成请求

请求响应示例（所有GUID为示例值） #

初始请求JSON #

{
  "transactionType": "Payment",
  "paymentMethod": {
    "card": {
      "merchantSessionKey": "75F49481-3826-48F8-9035-9C75EBEE9870",
      "cardIdentifier": "BC794F08-F532-41B0-B524-A2AB25CF4C50",
      "save": "false"
    },
    "threeDSServerTransID": null,
    "acsTransID": null
  },
  "vendorTxCode": "efb2131e-694d-487b-8635-8c2c58a1rrews4",
  "merchantSessionId": "efb2131e-694d-487b-8635-8c2c58a1rrews4",
  "amount": 1,
  "currency": "GBP",
  "description": "01 TEST",
  "apply3DSecure": "Force",
  "customerFirstName": "Test",
  "customerLastName": "Payer 1",
  "billingAddress": {
    "address1": "88",
    "city": "test city",
    "postalCode": "412",
    "country": "GB"
  },
  "entryMethod": "Ecommerce",
  "strongCustomerAuthentication": {
    "notificationURL": "url/Basket/HandleThreeDSResponse?MerchantSessionKey=75F49481-3826-48F8-9035-9C75EBEE9870",
    "browserIP": "ipaddress",
    "browserAcceptHeader": "*/*",
    "browserJavascriptEnabled": true,
    "browserLanguage": "en-GB",
    "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:134.0) Gecko/20100101 Firefox/134.0",
    "challengeWindowSize": "Small",
    "transType": "GoodsAndServicePurchase",
    "browserJavaEnabled": true,
    "browserColorDepth": "1",
    "browserScreenHeight": "400",
    "browserScreenWidth": "400",
    "browserTZ": "0",
    "cReq": "",
    "cRes": null,
    "threeDSNotificationURL": "url/Basket/HandleThreeDSResponse?MerchantSessionKey=75F49481-3826-48F8-9035-9C75EBEE9870"
  }
}

3D响应JSON #

{
  "threeDSServerTransID": "52b845a5-2dad-4530-8f89-8cca9d9bffff",
  "acsTransID": "b3679ed4-f630-452f-a9f6-38e3fe4rtgd3",
  "messageType": "CRes",
  "messageVersion": "2.2.0",
  "transStatus": "Y"
}

完成请求JSON #

{
  "amount": 1,
  "billingAddress": {
    "address1": "88",
    "city": "test city",
    "country": "GB",
    "postalCode": "412"
  },
  "currency": "GBP",
  "customerFirstName": "Test",
  "customerLastName": "Payer 1",
  "description": "01 - TEST",
  "entryMethod": "Ecommerce",
  "transactionType": "Payment",
  "paymentMethod": {
    "card": {
      "merchantSessionKey": "75F49481-3826-48F8-9035-9C75EBEE9870",
      "cardIdentifier": "BC794F08-F532-41B0-B524-A2AB25CF4C50"
    },
    "threeDSServerTransID": "52b845a5-2dad-4530-8f89-8cca9d9bffff",
    "acsTransID": "b3679ed4-f630-452f-a9f6-38e3fe4rtgd3",
    "transStatus": "Y"
  },
  "vendorTxCode": "efb2131e-694d-487b-8635-8c2c58a1rrews4",
  "merchantSessionId": "efb2131e-694d-487b-8635-8c2c58a1rrews4"
}

完成响应JSON #

{"description":"Merchant session key or card identifier invalid","code":1011}

问题核心 #

完成请求中使用了与初始请求完全相同的MerchantSessionKey和CardIdentifier，但未收到任何新值返回，触发1011错误。由于API多次易主，原始文档缺失，需解决该问题。

排查与解决建议 #

1. 检查会话密钥有效期：merchantSessionKey通常存在时间限制（如30分钟），确认3DS验证过程是否超出密钥有效期导致失效。
2. 验证卡片标识符状态：cardIdentifier可能在3DS验证后被标记为一次性使用，需在3DS响应后重新获取有效标识符，而非复用初始请求的旧值。
3. 核对请求参数一致性：对比初始请求与完成请求的vendorTxCode、merchantSessionId是否完全一致，注意描述字段从"01 TEST"变为"01 - TEST"，部分API可能对这类字段的一致性有要求。
4. 检查3DS响应的完整处理：确认是否遗漏3DS响应中的其他参数（如cRes相关值），部分场景下需将cRes内容嵌入完成请求。
5. 切换测试环境验证：使用Opayo沙箱API测试相同流程，排除生产环境的配置问题（如商户权限、API版本兼容性）。
6. 联系Opayo官方支持：提交错误码1011及完整请求响应日志给Opayo技术支持，获取针对性排查指引——文档缺失情况下，官方支持能提供关键信息。

内容的提问来源于stack exchange，提问作者Smithy