CyberSource sandbox Payments API 返回 SYSTEM_ERROR

2026-11-04排障赵师傅

结论

新建 sandbox merchant 并取得 Merchant ID、Key ID 和 Shared Secret 后，还需要完成相关后台配置，才能处理支付交易。调用 /pts/v2/payments 需要满足以下条件：

该 merchant 已获得 Payments 服务权限。
已配置 sandbox payment processor 或测试收单连接。
处理器配置支持请求使用的币种、卡类型和交易方式。

仅凭持续出现的 SYSTEM_ERROR，无法判断具体缺少哪项配置。如果同一个 Merchant ID 在官方 Java sample 和 API Console 中也会失败，本地 HTTP Signature 实现出错的可能性较低。此时应先检查 merchant 的服务开通状态和处理器配置。

为什么不像普通的签名错误

HTTP Signature、Merchant ID 或密钥不匹配，通常会导致请求在认证阶段失败。当前响应为：

{
  "status": "SERVER_ERROR",
  "reason": "SYSTEM_ERROR",
  "message": "Error - General system failure."
}

请求已经到达 CyberSource，但后端未能正常完成处理。可以从以下几方面排查：

merchant 尚未获得 Payments API 权限。
merchant 已经创建，但测试处理器配置尚未完成、尚未生效。
merchant 类型仅适用于部分产品，没有支付处理能力。
请求使用的币种、支付方式或交易类型不符合处理器配置。
CyberSource sandbox 当时发生了平台端故障。

SYSTEM_ERROR 是通用错误，不会在响应中指出具体缺失项。要确定原因，仍需由 CyberSource 根据请求关联信息检查后台日志。

建议的处理步骤

1. 确认 API Console 使用的是同一个 Merchant ID

API Console 可能使用预置的示例身份。测试时要确认它使用的是发生问题的 Merchant ID，避免误用 CyberSource 提供的公共演示配置。

如果指定该 merchant 后，API Console 仍返回相同结果，基本可以排除 Java SDK 配置文件、序列化和本地签名代码的问题。

2. 检查 merchant 的支付处理配置

Payments 或 Payment Processing 服务是否已经启用。
是否存在有效的 sandbox processor configuration。
处理器配置是否绑定到当前 Merchant ID。
测试使用的币种和卡品牌是否受支持。
该 merchant 是否仍在等待开通，或配置尚未完成。

生成 REST Shared Secret 只能说明账号可以创建 API 凭据，无法证明 Payments 服务和测试处理器已经配置完成。

3. 使用最小支付请求复测

先选用官方 sample 中与测试处理器匹配的请求，暂时不要加入 tokenization、3-D Secure、商户自定义字段等可选功能。基础请求可参考以下结构：

{
  "clientReferenceInformation": {
    "code": "sandbox-payment-test"
  },
  "processingInformation": {
    "commerceIndicator": "internet"
  },
  "paymentInformation": {
    "card": {
      "number": "<CYBERSOURCE_TEST_CARD_NUMBER>",
      "expirationMonth": "<MM>",
      "expirationYear": "<YYYY>"
    }
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "10.00",
      "currency": "USD"
    },
    "billTo": {
      "firstName": "Test",
      "lastName": "User",
      "address1": "1 Market Street",
      "locality": "San Francisco",
      "administrativeArea": "CA",
      "postalCode": "94105",
      "country": "US",
      "email": "test@example.com"
    }
  }
}

测试卡号应从 CyberSource 为相应 sandbox 处理器提供的测试数据中选择。不要在 sandbox 中使用真实卡号。

对应的 HTTP 请求大致如下：

POST /pts/v2/payments HTTP/1.1
Host: apitest.cybersource.com
Content-Type: application/json
v-c-merchant-id: <MERCHANT_ID>
Date: <HTTP_DATE>
Digest: SHA-256=<BASE64_SHA256_OF_EXACT_BODY>
Signature: keyid="<KEY_ID>", algorithm="HmacSHA256", headers="host date (request-target) digest v-c-merchant-id", signature="<SIGNATURE>"

Digest 和 Signature 必须根据实际发送的请求体字节生成。如果程序在签名后重新格式化 JSON、修改换行或改变字符编码，服务器计算出的摘要就会不同。使用官方 SDK 时，建议由 SDK 生成这些认证头，不要手工覆盖。

4. 保存关联信息并提交支持请求

如果最小请求仍返回相同的 SYSTEM_ERROR，请向 CyberSource Support 提交以下信息：

sandbox Merchant ID。
请求的完整 URL 和 HTTP 方法。
请求发生的 UTC 时间。
HTTP 状态码。
响应头中的 correlation ID、request ID 或类似追踪标识。
已脱敏的请求体和完整错误响应。
API Console 和官方 Java sample 均可复现的情况说明。

可以请支持人员检查：

Please confirm whether Payments REST API entitlement and a sandbox
payment processor configuration are enabled for this merchant ID.

工单、日志和截图中不要包含 Shared Secret、完整 Signature、真实卡号或其他生产凭据。

还需要注意什么

多个 merchant 都出现相同结果，也无法直接认定 CyberSource 平台整体发生了故障。如果这些账号通过同一种注册流程创建，它们可能缺少相同的 Payments 权限或处理器配置。

排查时还要记录实际的 HTTP 状态码。返回 401 或 403 时，应检查认证信息、系统时间、签名头和密钥类型。返回 5xx 且官方工具也能稳定复现时，应由 CyberSource 检查 merchant provisioning 或 sandbox 后端状态。