Open API V2 升级指引
概览
- v2 引入统一下单、支付方法详情接口、字段重命名与响应包装一致化。
1)接口改动对比
- 新增
/openapi/v2/order/payment-method:获取订单关联的支付方法详情(URL、QR、变体)。
- 合并/重构
- v1 的
/preOrder/create与/order/create在 v2 以单一/order/create为主;请求体统一到PreOrderCreateRequestV2。
- v1 的
- 保留但行为/模型变更
/refund/create、/refund/detail、/order/detail、/order/list、/merchant/asset/query、/merchant/asset/log/list、/country/list。
2)请求参数改动
- 订单创建
/openapi/v2/order/create- 新必填:
outerOrderSn、outerUid、orderAmount、goods、orderCurrency、orderDesc、env。 - 重命名/弃用:
outerOrder(v1)→outerOrderSn(v2),outerOrder在 v2 标记为 deprecated。 - 新增:
buyer(email、country)、redirectUrl、deeplink(当env为 H5/APP 必填)。 - 移除或不再必填:
country、language、discountAmount;paymentSuccessRedirectUrl/paymentFailRedirectUrl替换为redirectUrl/deeplink。
- 新必填:
- 支付方法详情
/openapi/v2/order/payment-method- 新接口请求体
GetPaymentMethodRequest:必填methodId;orderSn与outerOrderSn二选一(oneOf)。
- 新接口请求体
- 订单详情
/openapi/v2/order/detail- 请求体仍是
OrderDetailRequest,但 v2 推荐使用preSn或outerOrder(outerOrder在响应中 deprecated,建议过渡到outerOrderSn/orderSn)。
- 请求体仍是
- 订单列表
/openapi/v2/order/listouterOrderList与时间窗查询逻辑保留;分页字段含义、默认值在描述中更清晰。
- 退款
RefundOrderCreateRequest:必填merchantRefundSn、outerOrderSn、reason(与 v1 一致或更严格的格式描述)。
3)响应参数改动
- 下单响应
- v1:
CreateRedotPayOrderResponse(sn、qrcodeId)。 - v2:
CreatePayOrderResponse(orderSn、outerOrderSn、h5Url、webUrl、appUrl、paymentMethods);preSndeprecated;新增可用于自建收银台的paymentMethods列表。
- v1:
- 订单详情
OrderDetailResponse- 字段重命名/弃用:
outerOrder→outerOrderSn(前者 deprecated)coin→cryptoCurrencybillCoin→billCurrencypaymentDeadline→timeExpirewalletName→paymentMethodsigner→txAddressdigitalAmountdeprecated,使用cryptoAmount
refundSn在 v2 为数组。
- 字段重命名/弃用:
- 支付方法详情
GetPaymentMethodResponse(v2 新增)- 提供
webUrl/h5Url/appUrl、对应*QrCode、以及paymentVariants(CAMERA_SCAN、REDIRECT、APP_LINK等)。
- 提供
- 统一响应包装
- v2 统一为
code/msg/requestId/data,data类型按接口可能为对象、数组或分页对象。
- v2 统一为
4)升级指引(精简)
- 下单逻辑改造
- 将
outerOrder改为outerOrderSn;补充必填env(H5/WEB/APP)。 - 新增处理
buyer、redirectUrl、deeplink(H5/APP 必填)。 - 前端改为使用返回的
h5Url/webUrl/appUrl跳转或基于paymentMethods自建收银台。
- 将
- 新增支付方法详情调用(可选)
- 在自建收银台中调用
/order/payment-method获取指定methodId的 URL/QR/深链与paymentVariants。
- 在自建收银台中调用
- 响应解析更新
- 替换解析映射:
orderSn/outerOrderSn为主键,cryptoCurrency、billCurrency、timeExpire、paymentMethod、txAddress等新字段。 - 处理
refundSn数组;兼容 deprecated 字段的过渡读取。
- 替换解析映射:
- 订单查询与列表
- 保持请求结构,校正解析为 v2 的统一包装;区分单对象与数组/分页。
- 账户资产与国家列表
- 接口路径不变但需更新鉴权头;分页与字段含义按 v2 文档。
- 测试与发布
- 在
tenv-acquirer.rp-2023app.com进行端到端回归:下单、支付方法详情、查询、退款。 - 增量发布与兼容:短期内保留对旧字段的读取,日志标记旧字段使用,逐步下线。
- 在
- 重点破坏性变更
- 下单请求与响应结构重构。
- 字段重命名与 deprecated 清理。
Updated 2 months ago
