Paysafe API test mode 支付错误 3027 和 5068

2026-10-24支付阿杰

结论

这两个错误发生在不同环节：

3027：请求已经到达外部处理网关，但触发了额度或频率限制。仅凭错误码无法判断具体限制，需要结合测试账户配置、交易金额、币种、卡片和请求频率排查。最终原因通常要由 Paysafe 支持团队根据交易记录确认。
5068：请求字段校验失败。当前原因已经明确：billingDetails.country 不能填写国家名称 Canada，必须使用 ISO 3166-1 alpha-2 国家代码 CA。

先修复所有 5068 字段错误，再排查 3027，以免无效请求干扰判断。

处理错误 5068

错误详情已经指出了问题字段：

field: billingDetails.country
invalid value 'Canada'

将请求中的：

{
  "billingDetails": {
    "country": "Canada"
  }
}

改为：

{
  "billingDetails": {
    "country": "CA"
  }
}

常见国家代码示例：

国家或地区	正确值
加拿大	`CA`
美国	`US`
英国	`GB`
中国	`CN`
澳大利亚	`AU`

不要把用户输入的国家名称直接发送给 Paysafe。应用层应先将国家名称转换为两位国家代码，并在提交前进行验证。

<?php

$countryCodes = [
    'Canada' => 'CA',
    'United States' => 'US',
    'United Kingdom' => 'GB',
    'China' => 'CN',
    'Australia' => 'AU',
];

$countryInput = 'Canada';

if (!isset($countryCodes[$countryInput])) {
    throw new InvalidArgumentException('Unsupported country value');
}

$billingDetails = [
    'country' => $countryCodes[$countryInput],
];

如果前端使用国家选择器，可以显示国家名称，但将提交值设为国家代码：

<select name="country">
  <option value="CA">Canada</option>
  <option value="US">United States</option>
  <option value="GB">United Kingdom</option>
</select>

5068 不只会出现在国家字段中。遇到这个错误时，应逐项检查响应里的 details：

确认所有必填字段都已提供。
检查字段类型、长度、枚举值和大小写。
国家字段应使用两位国家代码，不能填写国家全名。
检查邮编、州或省代码、电话号码、金额和币种是否符合对应字段的格式要求。
不要把空字符串作为有效字段提交。
以当前 Paysafe API 的官方字段定义为准，不要只依赖前端的显示格式。

排查错误 3027

3027 表示外部处理网关检测到某项限制已被超过，但错误本身没有说明限制类型。可以从以下方向排查：

测试账户、商户账户或处理通道的交易额度限制；
单笔金额、累计金额或交易次数限制；
短时间内提交了过多相同或相似的交易；
测试卡或测试场景有特定使用限制；
账户配置的币种、地区或支付方式与请求不匹配；
测试环境的风控或网关规则阻止了交易。

这些只是可能的方向，不能单凭 3027 确定具体原因。

建议按以下顺序检查：

确认使用了 Paysafe 提供的测试凭据、测试端点和测试卡数据。
使用文档中的标准测试金额和最简请求重试。
检查金额是否采用接口要求的最小货币单位。例如，如果接口要求以分表示，10.00 CAD 通常应写成 1000。具体规则以所用 API 文档为准。
降低请求频率，避免重复使用相同的交易标识。
确保每次支付使用唯一的 merchant reference、请求 ID 或幂等键。具体字段名称取决于所调用的 Paysafe API。
检查测试账户是否已启用当前币种、卡品牌、地区和支付处理能力。
换用官方提供的另一组测试卡或测试场景，确认问题是否只与某张测试卡有关。
如果最简请求仍然返回 3027，将交易标识和请求时间提供给 Paysafe 支持团队，请他们查询网关日志。

提交给支持团队的信息

3027 来自外部处理网关，支持团队通常需要先定位具体交易。建议提供以下信息：

API 产品和请求端点；
test mode 账户或商户标识；
请求时间和明确的时区；
transaction ID、merchant reference、request ID 或 correlation ID；
HTTP 状态码和完整错误响应；
金额和币种；
使用的测试卡场景，但不要发送完整卡号、CVV、API secret 或 Authorization 头；
已脱敏的请求体；
错误是否能稳定复现，以及大致的请求频率。

请求示例

下面仅展示与问题有关的结构。实际必填字段应以具体 Paysafe API 产品的文档为准：

{
  "amount": 1000,
  "currencyCode": "CAD",
  "merchantRefNum": "test-payment-20260829-001",
  "billingDetails": {
    "street": "123 Test Street",
    "city": "Toronto",
    "state": "ON",
    "country": "CA",
    "zip": "M5V 2T6"
  }
}

提交前可以加入基础校验：

const ISO_COUNTRY_CODE = /^[A-Z]{2}$/;

function validatePaymentRequest(request) {
  const country = request.billingDetails?.country;

  if (!ISO_COUNTRY_CODE.test(country ?? "")) {
    throw new Error(
      "billingDetails.country must be a two-letter country code, such as CA"
    );
  }

  if (!Number.isInteger(request.amount) || request.amount <= 0) {
    throw new Error("amount must be a positive integer");
  }

  if (!/^[A-Z]{3}$/.test(request.currencyCode ?? "")) {
    throw new Error("currencyCode must be a three-letter currency code");
  }
}

正则表达式只能检查国家代码的格式，不能确认代码是否真实存在。生产环境还应通过允许列表验证，例如确认 CA 在接口支持的国家代码集合中。

注意事项

不要反复重试 5068。只要请求格式没有改变，重试就不会成功。
不要对 3027 进行无上限自动重试，否则可能进一步触发频率限制。最多进行少量带退避的重试，并记录每次请求的标识。
日志必须脱敏，尤其不能记录 CVV、完整卡号、API 密钥或 Authorization 信息。
测试环境成功不代表生产环境采用相同配置。上线前还要核对生产账户支持的币种、地区和交易限额。
如果将 country 修正为 "CA" 后仍然收到 5068，应根据新响应中的 details 继续检查。响应可能会指出下一个不合规字段。