Open API V2 升级指引

概览

  • v2 引入统一下单、支付方法详情接口、字段重命名与响应包装一致化。

1)接口改动对比

  • 新增
    • /openapi/v2/order/payment-method:获取订单关联的支付方法详情(URL、QR、变体)。
  • 合并/重构
    • v1 的 /preOrder/create/order/create 在 v2 以单一 /order/create 为主;请求体统一到 PreOrderCreateRequestV2
  • 保留但行为/模型变更
    • /refund/create/refund/detail/order/detail/order/list/merchant/asset/query/merchant/asset/log/list/country/list

2)请求参数改动

  • 订单创建 /openapi/v2/order/create
    • 新必填:outerOrderSnouterUidorderAmountgoodsorderCurrencyorderDescenv
    • 重命名/弃用:outerOrder(v1)→ outerOrderSn(v2),outerOrder 在 v2 标记为 deprecated。
    • 新增:buyeremailcountry)、redirectUrldeeplink(当 env 为 H5/APP 必填)。
    • 移除或不再必填:countrylanguagediscountAmountpaymentSuccessRedirectUrl/paymentFailRedirectUrl 替换为 redirectUrl/deeplink
  • 支付方法详情 /openapi/v2/order/payment-method
    • 新接口请求体 GetPaymentMethodRequest:必填 methodIdorderSnouterOrderSn 二选一(oneOf)。
  • 订单详情 /openapi/v2/order/detail
    • 请求体仍是 OrderDetailRequest,但 v2 推荐使用 preSnouterOrderouterOrder 在响应中 deprecated,建议过渡到 outerOrderSnorderSn)。
  • 订单列表 /openapi/v2/order/list
    • outerOrderList 与时间窗查询逻辑保留;分页字段含义、默认值在描述中更清晰。
  • 退款
    • RefundOrderCreateRequest:必填 merchantRefundSnouterOrderSnreason(与 v1 一致或更严格的格式描述)。

3)响应参数改动

  • 下单响应
    • v1:CreateRedotPayOrderResponsesnqrcodeId)。
    • v2:CreatePayOrderResponseorderSnouterOrderSnh5UrlwebUrlappUrlpaymentMethods);preSn deprecated;新增可用于自建收银台的 paymentMethods 列表。
  • 订单详情 OrderDetailResponse
    • 字段重命名/弃用:
      • outerOrderouterOrderSn(前者 deprecated)
      • coincryptoCurrency
      • billCoinbillCurrency
      • paymentDeadlinetimeExpire
      • walletNamepaymentMethod
      • signertxAddress
      • digitalAmount deprecated,使用 cryptoAmount
    • refundSn 在 v2 为数组。
  • 支付方法详情 GetPaymentMethodResponse(v2 新增)
    • 提供 webUrl/h5Url/appUrl、对应 *QrCode、以及 paymentVariantsCAMERA_SCANREDIRECTAPP_LINK 等)。
  • 统一响应包装
    • v2 统一为 code/msg/requestId/datadata 类型按接口可能为对象、数组或分页对象。

4)升级指引(精简)

  • 下单逻辑改造
    • outerOrder 改为 outerOrderSn;补充必填 env(H5/WEB/APP)。
    • 新增处理 buyerredirectUrldeeplink(H5/APP 必填)。
    • 前端改为使用返回的 h5Url/webUrl/appUrl 跳转或基于 paymentMethods 自建收银台。
  • 新增支付方法详情调用(可选)
    • 在自建收银台中调用 /order/payment-method 获取指定 methodId 的 URL/QR/深链与 paymentVariants
  • 响应解析更新
    • 替换解析映射:orderSn/outerOrderSn 为主键,cryptoCurrencybillCurrencytimeExpirepaymentMethodtxAddress 等新字段。
    • 处理 refundSn 数组;兼容 deprecated 字段的过渡读取。
  • 订单查询与列表
    • 保持请求结构,校正解析为 v2 的统一包装;区分单对象与数组/分页。
  • 账户资产与国家列表
    • 接口路径不变但需更新鉴权头;分页与字段含义按 v2 文档。
  • 测试与发布
    • tenv-acquirer.rp-2023app.com 进行端到端回归:下单、支付方法详情、查询、退款。
    • 增量发布与兼容:短期内保留对旧字段的读取,日志标记旧字段使用,逐步下线。
  • 重点破坏性变更
    • 下单请求与响应结构重构。
    • 字段重命名与 deprecated 清理。