Cybersource HOP支付请求被拒问题及自定义属性传递咨询

一、必填字段传递仍报错的排查点 #

• 严格匹配字段名大小写：Cybersource的字段名是大小写敏感的，必须完全使用小写格式，比如bill_address1、customer_email，不能出现首字母大写或拼写错误。
• 确认签名生成逻辑正确：
  1. 确保signed_field_names中完整包含所有必填字段，用逗号分隔无空格；
  2. 生成签名时，需将所有签名字段（包括这些必填字段）按字母顺序排序，再按照Cybersource要求的格式拼接（通常是字段名=字段值|字段名=字段值），最后用你的签名密钥生成HMAC签名。如果排序或拼接错误，Cybersource会拒绝接收字段值。
• 检查表单提交配置：
  • 表单必须使用method="POST"提交到正确的Secured Acceptance URL；
  • 隐藏域的name属性必须和字段名完全一致，比如：

    <input type="hidden" name="bill_address1" value="123 Main St">
    <input type="hidden" name="bill_city" value="New York">
    

• 验证字段值非空：确认传递的字段值不是空字符串或null，即使前端做了输入验证，也要在后端再次校验，避免空值被提交。
• 调整Secured Acceptance字段来源设置：在Cybersource后台的Secured Acceptance配置中，找到这些必填字段，将其“来源”设置为Merchant（商家），而不是Customer（用户）。如果设置为Customer，Cybersource会忽略你传递的值，强制要求用户在网关页面输入，从而触发必填错误。

二、传递自定义属性并在支付完成后返回的方法 #

Cybersource提供了专门的字段用于传递自定义数据，支持支付完成后同步/异步返回：

• 使用merchant_defined_data1至merchant_defined_data20字段（具体可用数量取决于你的Secured Acceptance版本），这些字段用于存储商家自定义信息；
• 步骤：
  1. 将需要传递的自定义字段添加到signed_field_names中，比如signed_field_names=...,merchant_defined_data1,merchant_defined_data2；
  2. 在表单中添加对应隐藏域：

  <input type="hidden" name="merchant_defined_data1" value="order_12345">
  <input type="hidden" name="merchant_defined_data2" value="vip_user">
  

  3. 生成签名时包含这些字段，确保签名逻辑正确；
• 支付完成后，Cybersource会在同步返回页面的请求参数以及异步通知（Webhook）的 payload中返回这些merchant_defined_data*字段，你可以直接读取这些值来关联订单或执行后续逻辑。
• 另外，如果你只需要传递订单号类的单一自定义标识，也可以使用reference_number字段，该字段默认会在返回数据中包含，无需额外配置（但需确保加入签名字段）。

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