# 更新 SDK 订单

> 在客户确认支付前，更新 SDK 交易的订单金额、账单信息或配送信息。

```yaml
openapi: 3.1.0
info:
  title: 更新 SDK 订单
  version: 1.0.0
  description: 在客户确认支付前，更新 SDK 交易的订单金额、账单信息或配送信息。
paths:
  /v1/sdkTxn/updateOrder:
    post:
      summary: 更新 SDK 订单
      description: 在客户确认支付前，更新 SDK 交易的订单金额、账单信息或配送信息。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                billingInformation:
                  type: string
                  description: 更新后的交易账单信息，包含客户账单地址和联系信息。仅在账单信息需要变更时传入；已包含的字段会覆盖原交易中的对应值，对象内部字段原有的必填条件仍然生效。
                  contentMediaType: application/json
                  contentSchema:
                    type: object
                    properties:
                      firstName:
                        type: string
                        description: 客户名字。
                      lastName:
                        type: string
                        description: 客户姓氏。
                      jpFirstName:
                        type: string
                        description: 日语片假名格式的名字；仅日本支付方式和日本发行的卡需要。
                      jpLastName:
                        type: string
                        description: 日语片假名格式的姓氏；仅日本支付方式和日本发行的卡需要。
                      phone:
                        type: string
                        description: 客户电话号码，仅填本地号码（不含国家码）；国家码请单独传入 `phoneCountryCode`，二者组合为完整号码。Onerway
                          当前不强校验格式。
                      phoneCountryCode:
                        type: string
                        description: 客户电话号码的国家拨号码，纯数字、不含 `+`；与 `phone` 组合为完整号码。
                      email:
                        type: string
                        description: 客户邮箱地址，用于交易确认和争议处理。
                      postalCode:
                        type: string
                        description: 邮政编码；许多地区的 AVS 验证需要此字段。
                      address:
                        type: string
                        description: 完整地址字段，可替代街道、门牌号和城市等拆分字段；不建议用于 AVS 验证。
                      country:
                        type: string
                        description: "[ISO 3166-1
                          alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alph\
                          a-2) 国家或地区代码。"
                      province:
                        type: string
                        description: "[ISO
                          3166-2](https://en.wikipedia.org/wiki/ISO_3166-2#Current_code\
                          s) 省/州代码。"
                        x-onerway-required: conditional
                        x-onerway-condition:
                          - 当 `country` 为 `US` 或 `CA` 时必填。
                      city:
                        type: string
                        description: 城市名称。开启 AVS 或需要完整账单地址时建议传入，用于补充地址完整性、授权率和风控判断；不同发卡行和地区的实际校验维度可能不同。
                      street:
                        type: string
                        description: 街道名称。开启 AVS 时建议与 `number`、`postalCode`、`city`
                          拆分传入，作为账单地址验证相关信息；不要仅用完整 `address` 字段替代拆分地址。
                      number:
                        type: string
                        description: 门牌号或建筑号。开启 AVS 时建议与 `street`、`postalCode`、`city` 拆分传入，作为账单地址验证相关信息。
                      identityNumber:
                        type: string
                        description: 政府颁发的身份标识，通常用于特定本地支付方式；可能是身份证号码，也可能是个人税号。
                      birthDate:
                        type: string
                        description: 出生日期，格式为 `yyyy/MM/dd`。
                    required:
                      - email
                      - country
                  x-onerway-constraints:
                    - kind: rule
                      text: 不要用 `null` 或空字符串覆盖已有信息；不需要变更的字段直接省略。
                  x-onerway-format: json_string
                merchantNo:
                  type: string
                  description: Onerway 分配的商户号；获取方式参见[接入准备](/zh/payments/get-started/setup#获取凭证)。
                merchantTxnId:
                  type: string
                  description: 要更新订单的商户交易标识，必须与原下单请求中提交的 `merchantTxnId` 一致。
                  x-onerway-required: conditional
                  x-onerway-condition:
                    - "`merchantTxnId` 与 `transactionId` 至少提供一个。"
                  x-onerway-constraints:
                    - kind: consistency
                      text: 同时传入 `merchantTxnId` 和 `transactionId` 时，两者必须指向同一笔原始交易。
                newMerchantTxnId:
                  type: string
                  description: 用于替换原订单 `merchantTxnId` 的新商户交易标识。不修改商户交易标识时省略；更新成功后，后续请求应使用新的标识。
                orderAmount:
                  type: string
                  description: 当前订单金额，以原交易币种计价，使用十进制字符串。格式要求详见[币种与金额校验](/zh/payments/get-started/currency-and-amount)。
                  x-onerway-constraints:
                    - kind: rule
                      text: 始终必填。即使只更新账单或配送信息，也必须重复提交当前订单金额。
                shippingInformation:
                  type: string
                  description: 更新后的交易配送信息，包含客户配送地址和联系信息。仅在配送信息需要变更时传入；已包含的字段会覆盖原交易中的对应值，对象内部字段原有的必填条件仍然生效。
                  contentMediaType: application/json
                  contentSchema:
                    type: object
                    properties:
                      firstName:
                        type: string
                        description: 客户名字。
                      lastName:
                        type: string
                        description: 客户姓氏。
                      jpFirstName:
                        type: string
                        description: 日语片假名格式的名字；仅日本支付方式和日本发行的卡需要。
                      jpLastName:
                        type: string
                        description: 日语片假名格式的姓氏；仅日本支付方式和日本发行的卡需要。
                      phone:
                        type: string
                        description: 客户电话号码，仅填本地号码（不含国家码）；国家码请单独传入 `phoneCountryCode`，二者组合为完整号码。Onerway
                          当前不强校验格式。
                      phoneCountryCode:
                        type: string
                        description: 客户电话号码的国家拨号码，纯数字、不含 `+`；与 `phone` 组合为完整号码。
                      email:
                        type: string
                        description: 客户邮箱地址，用于交易确认和争议处理。
                      postalCode:
                        type: string
                        description: 邮政编码；许多地区的 AVS 验证需要此字段。
                      address:
                        type: string
                        description: 完整地址字段，可替代街道、门牌号和城市等拆分字段；不建议用于 AVS 验证。
                      country:
                        type: string
                        description: "[ISO 3166-1
                          alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alph\
                          a-2) 国家或地区代码。"
                      province:
                        type: string
                        description: "[ISO
                          3166-2](https://en.wikipedia.org/wiki/ISO_3166-2#Current_code\
                          s) 省/州代码。"
                        x-onerway-required: conditional
                        x-onerway-condition:
                          - 当 `country` 为 `US` 或 `CA` 时必填。
                      city:
                        type: string
                        description: 城市名称。开启 AVS 或需要完整账单地址时建议传入，用于补充地址完整性、授权率和风控判断；不同发卡行和地区的实际校验维度可能不同。
                      street:
                        type: string
                        description: 街道名称。开启 AVS 时建议与 `number`、`postalCode`、`city`
                          拆分传入，作为账单地址验证相关信息；不要仅用完整 `address` 字段替代拆分地址。
                      number:
                        type: string
                        description: 门牌号或建筑号。开启 AVS 时建议与 `street`、`postalCode`、`city` 拆分传入，作为账单地址验证相关信息。
                      identityNumber:
                        type: string
                        description: 政府颁发的身份标识，通常用于特定本地支付方式；可能是身份证号码，也可能是个人税号。
                      birthDate:
                        type: string
                        description: 出生日期，格式为 `yyyy/MM/dd`。
                    required:
                      - email
                      - country
                  x-onerway-constraints:
                    - kind: rule
                      text: 不要用 `null` 或空字符串覆盖已有信息；不需要变更的字段直接省略。
                  x-onerway-format: json_string
                sign:
                  type: string
                  description: 请求签名字符串；生成方式详见[请求签名](/zh/payments/get-started/request-signing)。
                transactionId:
                  type: string
                  description: 要更新订单的 Onerway 交易标识，必须与原下单响应返回的 `transactionId` 一致。
                  x-onerway-required: conditional
                  x-onerway-condition:
                    - "`transactionId` 与 `merchantTxnId` 至少提供一个。"
                  x-onerway-constraints:
                    - kind: consistency
                      text: 同时传入 `transactionId` 和 `merchantTxnId` 时，两者必须指向同一笔原始交易。
              required:
                - merchantNo
                - orderAmount
                - sign
            examples:
              update-order-amount:
                summary: 更新订单金额
                value:
                  merchantNo: replace_with_merchant_no
                  orderAmount: "25.00"
                  sign: replace_with_calculated_signature
                  transactionId: example_transaction_id_update
              update-addresses:
                summary: 更新账单与配送信息
                value:
                  billingInformation: '{"country":"US","email":"customer@example.com","province":"CA"}'
                  merchantNo: replace_with_merchant_no
                  merchantTxnId: example_sdk_txn_001
                  orderAmount: "1"
                  shippingInformation: '{"country":"US","email":"customer@example.com","province":"CA"}'
                  sign: replace_with_calculated_signature
              update-merchant-txn-id:
                summary: 更换商户交易标识
                value:
                  merchantNo: replace_with_merchant_no
                  merchantTxnId: example_sdk_txn_001
                  newMerchantTxnId: example_sdk_txn_001_v2
                  orderAmount: "1"
                  sign: replace_with_calculated_signature
      responses:
        "200":
          description: 订单更新已受理
          content:
            application/json:
              schema:
                type: object
                properties:
                  respCode:
                    type: string
                    description: 响应码；`20000`
                      表示请求处理成功，其余为错误码。完整码表见[响应码](/zh/payments/api-reference/response-codes)。
                  respMsg:
                    type: string
                    description: 响应码对应的可读说明。
                  data:
                    type: object
                    properties:
                      transactionId:
                        type: string
                        description: 被更新订单的 Onerway 交易标识。
                      responseTime:
                        type:
                          - string
                          - "null"
                        description: 接口响应时间，格式 `yyyy-MM-dd HH:mm:ss`。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: Returned as `null` in the update order acknowledgement response.
                            zh: 更新订单确认响应中返回 `null`。
                      txnTime:
                        type:
                          - string
                          - "null"
                        description: 交易完成时间，格式 `yyyy-MM-dd HH:mm:ss`。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: Returned as `null` in the update order acknowledgement response; payment has
                              not completed at this stage.
                            zh: 更新订单确认响应中返回 `null`；该阶段支付尚未完成。
                      txnTimeZone:
                        type:
                          - string
                          - "null"
                        description: 交易时区偏移量，格式 `±HH:mm`。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: Returned as `null` in the update order acknowledgement response.
                            zh: 更新订单确认响应中返回 `null`。
                      orderAmount:
                        type:
                          - string
                          - "null"
                        description: 订单金额，以交易币种计价。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: Returned as `null` in the update order acknowledgement response; after a
                              success response, the amount submitted in the
                              update request is authoritative.
                            zh: 更新订单确认响应中返回 `null`；成功响应后以商户请求中的更新金额为准。
                      orderCurrency:
                        type:
                          - string
                          - "null"
                        description: 下单币种，[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 三位字母货币代码。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: Returned as `null` in the update order acknowledgement response.
                            zh: 更新订单确认响应中返回 `null`。
                      txnAmount:
                        type:
                          - string
                          - "null"
                        description: 旧版到账金额字段，本接口不返回有效值。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: Returned as `null` in the update order acknowledgement response.
                            zh: 更新订单确认响应中返回 `null`。
                      txnCurrency:
                        type:
                          - string
                          - "null"
                        description: 旧版结算币种字段，本接口不返回有效值。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: Returned as `null` in the update order acknowledgement response.
                            zh: 更新订单确认响应中返回 `null`。
                      status:
                        type:
                          - string
                          - "null"
                        description: 交易处理状态。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: Returned as `null` in the update order acknowledgement response; the order
                              update itself does not change the transaction
                              processing status.
                            zh: 更新订单确认响应中返回 `null`；订单更新本身不改变交易处理状态。
                      redirectUrl:
                        type:
                          - string
                          - "null"
                        description: 当前 Web SDK 使用 `paymentId` 初始化，不消费本字段。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: Returned as `null` in the update order acknowledgement response.
                            zh: 更新订单确认响应中返回 `null`。
                      contractId:
                        type:
                          - string
                          - "null"
                        description: 订阅合约号，本接口不返回有效值。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: Returned as `null` in the update order acknowledgement response.
                            zh: 更新订单确认响应中返回 `null`。
                      tokenId:
                        type:
                          - string
                          - "null"
                        description: 支付 token 标识，本接口不返回有效值。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: Returned as `null` in the update order acknowledgement response.
                            zh: 更新订单确认响应中返回 `null`。
                      eci:
                        type:
                          - string
                          - "null"
                        description: 电子商务指示符（ECI），本接口不返回有效值。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: Returned as `null` in the update order acknowledgement response.
                            zh: 更新订单确认响应中返回 `null`。
                      periodValue:
                        type:
                          - string
                          - "null"
                        description: 分期付款期数，本接口不返回有效值。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: Returned as `null` in the update order acknowledgement response.
                            zh: 更新订单确认响应中返回 `null`。
                      codeForm:
                        type:
                          - string
                          - "null"
                        description: 支付码信息对象，本接口不返回有效值。
                        contentMediaType: application/json
                        contentSchema:
                          type: object
                          properties:
                            {}
                        x-onerway-value:
                          nullable: true
                          when:
                            en: Returned as `null` in the update order acknowledgement response.
                            zh: 更新订单确认响应中返回 `null`。
                        x-onerway-format: json_string
                      presentContext:
                        type:
                          - string
                          - "null"
                        description: 供渲染支付界面元素的附加上下文，本接口不返回有效值。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: Returned as `null` in the update order acknowledgement response.
                            zh: 更新订单确认响应中返回 `null`。
                      actionType:
                        type:
                          - string
                          - "null"
                        description: 需执行的后续动作类型，本接口不返回有效值。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: Returned as `null` in the update order acknowledgement response.
                            zh: 更新订单确认响应中返回 `null`。
                      subscriptionManageUrl:
                        type:
                          - string
                          - "null"
                        description: 订阅管理地址，本接口不返回有效值。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: Returned as `null` in the update order acknowledgement response.
                            zh: 更新订单确认响应中返回 `null`。
                      sign:
                        type: string
                        description: 响应签名字符串；当前不建议商户对响应验签。
                    description: 更新订单确认响应的业务数据对象。成功响应只表示订单更新已受理，不代表支付结果；最终支付状态以服务端支付 Webhook
                      或交易查询为准。
              examples:
                update-accepted:
                  summary: 订单更新已受理
                  value:
                    respCode: "20000"
                    respMsg: Success
                    data:
                      transactionId: example_transaction_id_update
                      responseTime: null
                      txnTime: null
                      txnTimeZone: null
                      orderAmount: null
                      orderCurrency: null
                      txnAmount: null
                      txnCurrency: null
                      status: null
                      redirectUrl: null
                      contractId: null
                      tokenId: null
                      eci: null
                      periodValue: null
                      codeForm: null
                      presentContext: null
                      actionType: null
                      subscriptionManageUrl: null
                      sign: replace_with_response_signature
```