调用Square退款接口未传order.returns仍报只读字段无法设置如何解决

该报错并非你主动传入了order.returns字段导致，属于Square接口内部处理逻辑的校验触发问题，核心触发场景是：你发起退款的payment_id关联的支付绑定了Square Orders API创建的订单，你直接调用/v2/refunds端点发起退款时，Square会自动尝试同步更新对应订单的退款关联数据，当对应订单处于已关闭/已完成状态，或请求未明确携带订单标识参数时，内部生成的更新数据误包含了只读字段order.returns，进而触发校验报错。

按优先级推荐以下三种解决方案：

• 补充订单关联参数后重试
  先调用GET /v2/payments/{payment_id}接口，从返回结果中获取该支付绑定的order_id值，再调用GET /v2/orders/{order_id}接口获取该订单当前的version值，将这两个参数补充到你的退款请求体中即可，修改后的请求体示例如下：

  {
    "amount_money":{"currency":"USD","amount":3000},
    "reason":"requested_by_customer",
    "payment_id":"BwC...",
    "idempotency_key":"083bba8fabb9df88cf50fa1c489db275",
    "order_id": "你的对应订单ID",
    "version": 你的订单当前版本号
  }
  

• 改用Orders API发起退款
  如果你需要退款操作和订单数据强关联，直接调用POST /v2/orders/{order_id}/refund端点发起订单维度的退款，该接口不会触发该类只读字段校验错误。
• 升级Square SDK版本
  若你是通过官方SDK发起的请求，部分旧版本SDK存在内部自动补全冗余字段的问题，升级到对应语言的最新版SDK后重试即可。

内容的提问来源于stack exchange，提问作者Juan Camilo Duque Delgado