CyberSource sandbox Payments API 返回 SYSTEM_ERROR

2026-10-24支付小周

明确结论

REST Shared Secret 只能验证请求身份，不能证明 merchant 已经完成支付交易所需的后台配置。

如果同一个新建 sandbox merchant 在以下两种测试中都持续返回 SYSTEM_ERROR：

CyberSource 官方 Java sample；
CyberSource API Console；

问题更可能出在该 sandbox merchant 的 Payments 服务授权、支付处理器配置或测试账户开通状态，而不是 HTTP Signature。

正常情况下，系统会自动为新建测试商户完成基础配置。如果配置没有完成或 provisioning 出现异常，通常只能由 CyberSource 支持团队检查或重新配置，客户端无法靠增加请求参数解决。

凭据正确为什么仍会失败

调用 /pts/v2/payments 至少要通过两层校验：

身份认证
系统使用 Merchant ID、Key ID 和 Shared Secret 验证 HTTP Signature。
商户交易配置
后端还要确认 merchant 已启用 Payments API，并且具备可用的支付处理配置，包括：
- Payments 服务权限；
- sandbox processor profile；
- 支持的支付方式或卡品牌；
- 币种、国家或地区配置；
- merchant 与处理配置之间的关联。

HTTP Signature 明显错误时，通常会返回认证或授权类错误。SERVER_ERROR 和 SYSTEM_ERROR 则更像是请求已经进入服务，但后台未能完成处理。不过，这类错误非常笼统，仅凭响应正文无法确定唯一原因。

建议的排查步骤

1. 使用最小请求验证

先去掉复杂字段、Token、3-D Secure 和设备数据等因素，只发送一次基本授权请求：

{
  "clientReferenceInformation": {
    "code": "sandbox-payment-test-001"
  },
  "processingInformation": {
    "commerceIndicator": "internet"
  },
  "paymentInformation": {
    "card": {
      "number": "4111111111111111",
      "expirationMonth": "12",
      "expirationYear": "2031"
    }
  },
  "orderInformation": {
    "amountDetails": {
      "totalAmount": "10.00",
      "currency": "USD"
    },
    "billTo": {
      "firstName": "John",
      "lastName": "Doe",
      "address1": "1 Market Street",
      "locality": "San Francisco",
      "administrativeArea": "CA",
      "postalCode": "94105",
      "country": "US",
      "email": "test@example.com"
    }
  }
}

测试卡号和预期结果应以 CyberSource 当前的 sandbox 测试数据文档为准。不要在生产环境中使用测试卡。

2. 核对签名覆盖的请求内容

自行构造 HTTP Signature 时，应重点检查：

请求目标是否为 /pts/v2/payments；
Host 是否为 apitest.cybersource.com；
v-c-merchant-id 是否与生成密钥的 merchant 完全一致；
Digest 是否根据实际发送的原始请求体计算；
计算签名后，请求体是否又被格式化或修改；
Date 是否使用有效的 GMT/UTC HTTP 日期；
Key ID 与 Shared Secret 是否属于同一个 merchant；
测试密钥是否误用于生产域名，或生产密钥是否误用于测试域名。

典型的请求头结构如下。签名值必须根据实际请求计算：

POST /pts/v2/payments HTTP/1.1
Host: apitest.cybersource.com
Date: Tue, 15 Sep 2026 08:00:00 GMT
Content-Type: application/json
v-c-merchant-id: YOUR_MERCHANT_ID
Digest: SHA-256=BASE64_DIGEST
Signature: keyid="YOUR_KEY_ID", algorithm="HmacSHA256", headers="host date (request-target) digest v-c-merchant-id", signature="BASE64_SIGNATURE"

不要直接复制示例中的 Date、Digest 或 Signature。

3. 使用 API Console 交叉验证

API Console 可以帮助缩小问题范围：

API Console 成功，但自己的代码失败：检查签名生成、请求头和请求体；
API Console 与官方 sample 都失败：检查 merchant 的后台开通状态；
只有部分币种或支付方式失败：检查 processor、币种和支付方式配置；
所有请求都返回相同的 SYSTEM_ERROR：问题更可能与 merchant provisioning 或 CyberSource sandbox 侧异常有关。

还要确认 API Console 使用的是自己的 merchant 凭据，而不是页面内置的示例账户。

4. 等待新账户配置完成后重试

如果 merchant 刚创建，可以等后台配置完成后再次测试。现有信息无法确定具体需要等待多久，因此不要假设配置会立即生效，也不要认定存在固定的等待时间。

如果多个新账户持续出现同样的问题，继续创建账户通常没有帮助，应直接提交支持请求。

联系 CyberSource 支持时提供的信息

请 CyberSource 检查该 sandbox merchant 是否：

已启用 REST Payments API；
已正确完成测试环境 provisioning；
已关联有效的 sandbox payment processor/profile；
存在账户级或数据中心侧错误。

提交支持请求时，同时提供：

sandbox Merchant ID；
请求发生的 UTC 时间；
请求路径和 HTTP 方法；
HTTP 状态码；
完整错误响应；
响应头中的 correlation/request identifier，例如实际返回的 v-c-correlation-id；
已脱敏的请求体；
API Console 和官方 Java sample 均能复现问题的说明。

不要提交 Shared Secret、完整卡号、CVV 或可直接重放的 Signature。

注意事项

SYSTEM_ERROR 并不表示请求一定正确。仍然要先使用最小请求，排除字段组合和签名问题。但如果官方 sample 与 API Console 对同一个 merchant 都失败，客户端代码就不是首要排查对象。

这类情况通常不是缺少某个公开 API 参数，而是需要确认或修复 sandbox merchant 的服务授权和处理器配置。最终原因应以 CyberSource 根据 correlation ID 查到的服务端日志为准。