更新订单

概述

更新订单 API 允许商户在客户通过 SDK 完成支付之前修改交易详情。这对于动态结账流程特别有用,在这种场景下,订单详情可能在创建初始交易后但在提交支付前发生变化。

使用场景

• 应用折扣或促销后更新订单金额
• 根据客户输入修改收货地址信息
• 在提交支付前调整账单信息
• 更新购物车中的商品数量或选择

前置要求

1. 必须已使用下单 API 创建交易
2. 必须在 SDK 集成中实现自定义支付按钮
3. 此 API 只能在客户通过 SDK 提交支付之前调用

集成流程

API 请求参数

POST

Name	Type	Length	Required	Signature	Description
merchantNo	String	20	Yes	Yes	Unique merchant identifier assigned by Onerway during registration.
merchantTxnId	String	64	Conditional	Yes	Merchant-generated transaction identifier. Either merchantTxnId or transactionId must be provided to identify the transaction.
transactionId	String	20	Conditional	Yes	Onerway-generated transaction identifier returned from the original transaction creation. Either transactionId or merchantTxnId must be provided.
newMerchantTxnId	String	64	Conditional	Yes	New merchant transaction identifier to update the original merchantTxnId.
orderAmount	String	19	Yes	Yes	Updated transaction amount with maximum two decimal places.
billingInformation	String		No	Yes	Updated billing details as a JSON string. See TransactionInformation for structure.
shippingInformation	String		No	Yes	Updated shipping details as a JSON string. See TransactionInformation for structure.
sign	String		Yes	No	Request signature for authentication and data integrity. See Signature documentation for generation method.

TransactionInformation

Name	Type	Length	Required	Signature	Description
firstName	String	64	No	No	Customer first name.
lastName	String	64	No	No	Customer last name.
jpFirstName	String	64	No	No	First name in Japanese Katakana.
jpLastName	String	64	No	No	Last name in Japanese Katakana.
phone	String	32	No	No	Customer phone number in international format.
email	String	256	Yes	No	Customer email address.
postalCode	String	32	No	No	Postal/ZIP code.
address	String	256	No	No	Full address in a single field.
country	String	64	Yes	No	Country in ISO 3166-1 alpha-2 format. See ISO 3166.
province	String	64	Conditional	No	Province/State code. Required when country is US or CA. See ISO 3166.
city	String	64	No	No	City name.
street	String	64	No	No	Street name.
number	String	64	No	No	House/Building number.
identityNumber	String	64	No	No	Government-issued ID number.
birthDate	String	64	No	No	Birth date in yyyy-MM-dd format.

API 使用示例

Request

{
  "merchantNo": "800209",
  "transactionId": "1919352261407277056", // doTransaction 响应返回的 transactionId
  "orderAmount": "20", // 更新后的订单金额
  "sign": "d1db1166ec3db7a8b9e8e731f22b17c7e0998702690fdfa0808378f44551d239"
}

Response

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "1919352261407277056",
    "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": "e1decc2edac78b1c3ca7a842195bcf57b9d44f07c8bf8ccdeb9c21aaa60db9ee"
  }
}

详细实现

1. 创建初始交易

首先,使用下单 API 创建交易

2. 使用自定义支付按钮初始化 SDK

要使用更新订单 API,必须通过在 SDK 配置中设置 showPayButton: false 来初始化带有自定义支付按钮的 SDK。这允许您在潜在订单更新后控制何时提交支付。

3. 集成工作流程

集成更新订单 API 的关键步骤:

1. 检测变更:识别何时需要更新订单详情(例如,用户更改地址、应用优惠券、更新数量)

2. 准备参数:仅包含需要更新的参数,以避免覆盖现有值

3. 调用更新 API:使用必要的参数和签名向 Onerway 发送更新请求

4. 验证响应:在继续之前检查更新是否成功

5. 提交支付:当客户准备完成购买时,使用 SDK 的 submit() 方法处理更新后详情的支付

4. 实现注意事项

• 服务端实现:出于安全考虑,更新订单 API 通常应从服务器调用,而不是直接从客户端调用

• 签名生成:根据要更新的参数,按照 Onerway 的签名规则生成签名

• 多次更新:如有需要,可以在提交支付前多次更新订单

• 错误处理:实现适当的错误处理来管理更新失败的情况

限制与注意事项

1. 时间约束:此 API 只能在提交支付前使用。一旦开始处理支付,就无法再进行更新。

2. 部分更新:在请求中仅包含需要更新的字段。包含的任何字段都将覆盖原始交易中的相应值。

3. 空值:切勿发送 null 或空字符串,因为它们会覆盖现有值。省略不需要更新的字段。

4. 自定义按钮要求:此 API 需要实现自定义支付按钮,因为它需要在提交支付前更新交易。

5. 交易标识:必须提供 merchantTxnId 或 transactionId 来标识要更新的交易。建议使用 transactionId 以获得更可靠的标识。如果需要更新商户交易标识符本身,请使用 newMerchantTxnId 字段。

6. 签名生成:记得根据更新的参数重新计算签名,遵循标准的签名规则。

实现最佳实践

1. 选择性更新:仅更新实际发生变化的字段,以最小化处理开销。

2. 验证:在调用更新订单 API 之前,在服务器上验证所有更新的值。

3. 错误处理:实现健壮的错误处理,以优雅地管理更新失败。

4. 订单一致性:确保 UI 中显示的订单详情与您通过 API 更新的内容匹配。

5. 响应验证:在继续支付前,始终验证 API 响应以确认更新已成功应用。

6. 日志记录:维护所有更新操作的日志,以便进行故障排查和审计。

相关文档链接

Onerway 文档

• 支付意向创建:创建初始交易和获取 transactionId
• 自定义支付按钮:实现自定义支付按钮的详细说明
• 签名:签名生成规则和方法