下单参数更新（updateSession）

端点

环境	地址
生产	`POST https://api.futurepay.global/checkout/updateSession`
沙箱	`POST https://api.futurepay-develop.com/checkout/updateSession`

鉴权与签名方式和 newSession 完全一致。

语义

PATCH：只传需要修改的字段，未传的字段保持原值。空字符串同样视为"未传"，

不支持把已有值清空——需要清空请重新下单。

请求参数

定位

sessionToken 与 reference 至少传一个；两个都传时必须指向同一笔订单，否则报错。

字段	必填	类型	说明
`sessionToken`	C	String	newSession 返回的会话 token
`reference`	C	String	商户订单号。本身不可修改，仅用于定位

可更新字段

字段	类型	说明
`amount.value`	Integer	支付金额，最小货币单位，必须大于 0。传 `amount` 时该字段必填
`amount.currency`	String	支付币种，ISO 4217。不传则沿用原币种
`productName`	String	订单标题，最长 100 字符
`productDetail`	String	订单描述
`shopImgLink`	String	商品图片地址，最长 255 字符
`returnUrl`	String	支付完成跳转地址，最长 500 字符
`webhookUrl`	String	订单结果回调地址，最长 500 字符
`sessionTime`	Long	会话有效期（毫秒），上限 604800000（7 天）。传入后从当前时刻重新计时
`statementDescriptor`	String	Apple Pay / Google Pay 账单上显示的商户名
`billingAddressCollection`	Boolean	是否收集账单地址
`maxRetries`	Integer	首次付款之后允许的重试次数，不能为负
`isexchange`	Boolean	是否开启换汇
`directReturn`	Boolean	是否跳过成功页直接跳转 returnUrl
`processingCurrency`	String	处理币种，ISO 4217
`paymentMethod.type`	String	默认支付方式
`paymentMethod.displayName`	String	支付方式展示名
`paymentMethod.shopperEmail`	String	消费者邮箱
`paymentMethod.firstName`	String	消费者名
`paymentMethod.lastName`	String	消费者姓
`paymentMethod.telephoneNumber`	String	消费者电话
`paymentMethod.taxType`	String	证件类型
`paymentMethod.personalTaxId`	String	证件号
`paymentMethod.threeDsMode`	String	`ENABLED` / `DISABLED` / `DYNAMIC`
`paymentMethod.captureMethod`	String	`automatic` / `manual`

不可更新字段

以下字段传入即报错（而不是被静默忽略），需要变更请重新下单：

字段	原因
`reference`	幂等键与对账链路依赖它
`origin`	与 Apple Pay 域名校验绑定
`countryCode`	由收银台前端在支付时提交，服务端改了也不会生效
`shopperReference`	与绑卡链路绑定
`enableOneClick`	与绑卡链路绑定

允许更新的条件

以下任一条件不满足即拒绝更新：

会话仍在有效期内；
会话属于当前签名商户；
该商户订单号下所有订单都还停留在预支付状态——已经产生成功订单的会话不能再修改；
消费者一次支付都还没发起过。

响应

字段	类型	说明
`code`	String	`0` 表示成功
`msg`	String	响应消息
`success`	Boolean	是否成功
`data.sessionToken`	String	会话 token
`data.reference`	String	商户订单号
`data.checkOutUrl`	String	收银台地址，与下单时下发的一致，原链接继续有效
`data.amount`	Object	更新后的金额
`data.sessionTime`	Long	会话剩余有效期（毫秒）
`data.updatedFields`	Array	本次实际发生变更的字段名；传入值与原值相同的字段不会出现在这里
`serverTime`	Long	服务器时间戳（毫秒）

示例

请求：

{
  "reference": "ORDER-20260910-001",
  "amount": {
    "currency": "USD",
    "value": 2500
  },
  "productName": "Annual plan (upgraded)"
}

响应：

{
  "code": "0",
  "msg": "succeeded",
  "success": true,
  "data": {
    "sessionToken": "0a1b2c3d-4e5f-6789-abcd-ef0123456789",
    "reference": "ORDER-20260910-001",
    "checkOutUrl": "https://checkout.futurepay.global/?token=0a1b2c3d-4e5f-6789-abcd-ef0123456789",
    "amount": { "currency": "USD", "value": 2500 },
    "sessionTime": 6840000,
    "updatedFields": ["amount.value", "productName"]
  },
  "serverTime": 1789012345678
}

错误码

场景	错误码
sessionToken 与 reference 都未传	缺少参数
传入不可更新字段、取值非法、两个定位字段互相矛盾	参数值错误
订单不存在，或不属于当前商户	订单号不存在
会话已过期	session 过期
订单已不是预支付，或消费者已发起支付	订单状态错误
同一会话上有并发的更新请求	其他原因（提示稍后重试）