Guides
Start typing to search…

Open API V2 Upgrade Guide

  • v2 introduces a unified order placement process, a payment method details interface, field renaming, and unified response formatting.

1) Interface Changes

  • New
    • /openapi/v2/order/payment-method: Retrieves details (URL, QR code, variants) of the payment method associated with an order.
  • Merged/Restructured
    • The v1 endpoints /preOrder/create and /order/create are merged in v2, primarily using the single /order/create endpoint. The request body is unified into PreOrderCreateRequestV2.
  • Retained with Behavior/Model Changes
    • /refund/create, /refund/detail, /order/detail, /order/list, /merchant/asset/query, /merchant/asset/log/list, /country/list.

2) Request Parameter Changes

  • Order Creation /openapi/v2/order/create
    • New Required Fields: outerOrderSn, outerUid, orderAmount, goods, orderCurrency, orderDesc, env.
    • Renamed/Deprecated: outerOrder (v1) → outerOrderSn (v2). outerOrder is marked as deprecated in v2.
    • New Fields: buyer (country), redirectUrl, deeplink (required when env is H5 or APP).
    • Removed or No Longer Required: country, language, discountAmount; paymentSuccessRedirectUrl/paymentFailRedirectUrl are replaced by redirectUrl/deeplink.
  • Payment Method Details /openapi/v2/order/payment-method
    • New request body GetPaymentMethodRequest: methodId is required; choose between orderSn and outerOrderSn (oneOf).
  • Order Details /openapi/v2/order/detail
    • Request body remains OrderDetailRequest, but v2 recommends using preSn or outerOrder (outerOrder is deprecated in the response, transitioning to outerOrderSn/orderSn is advised).
  • Order List /openapi/v2/order/list
    • The outerOrderList and time-window query logic are retained; the meaning and default values of pagination fields are described more clearly.
  • Refunds
    • RefundOrderCreateRequest: merchantRefundSn, outerOrderSn, reason are required (format descriptions are consistent with v1 or stricter).

3) Response Parameter Changes

  • Order Placement Response
    • v1: CreateRedotPayOrderResponse (sn, qrcodeId).
    • v2: CreatePayOrderResponse (orderSn, outerOrderSn, h5Url, webUrl, appUrl, paymentMethods); preSn deprecated; new paymentMethods list for custom checkout pages.
  • Order Details OrderDetailResponse
    • Field Renaming/Deprecation:
      • outerOrder → outerOrderSn (former deprecated)
      • coin → cryptoCurrency
      • billCoin → billCurrency
      • paymentDeadline → timeExpire
      • walletName → paymentMethod
      • signer → txAddress
      • digitalAmount deprecated, use cryptoAmount
    • refundSn is an array in v2.
  • Payment Method Details GetPaymentMethodResponse (New in v2)
    • Provides webUrl/h5Url/appUrl, corresponding *QrCode, and paymentVariants (CAMERA_SCAN, REDIRECT, APP_LINK, etc.).
  • Unified Response Wrapper
    • v2 responses are uniformly formatted as code/msg/requestId/data. The data type varies by interface (object, array, or paginated object).

4) Migration Guide (Simplified)

  • Order Placement Logic Update
    • Change outerOrder to outerOrderSn. Add the required env field (H5/WEB/APP).
    • Add handling for buyer, redirectUrl, deeplink (required for H5/APP).
    • Update the frontend to use the returned h5Url/webUrl/appUrl for redirection or build a custom checkout page based on paymentMethods.
  • Add Payment Method Detail Call (Optional)
    • In a custom checkout page, call /order/payment-method to get the URL/QR code/deep link and paymentVariants for a specified methodId.
  • Response Parsing Update
    • Update parsing mappings: use orderSn/outerOrderSn as primary keys, and new fields like cryptoCurrency, billCurrency, timeExpire, paymentMethod, txAddress.
    • Handle the refundSn array; maintain compatibility for reading deprecated fields during transition.
  • Order Query and List
    • Keep the request structure, but adjust parsing for v2's unified wrapper; distinguish between single objects and arrays/paginated results.
  • Account Asset and Country List
    • Interface paths remain the same, but authentication headers need updating; follow v2 documentation for pagination and field meanings.
  • Testing and Deployment
    • Perform end-to-end regression testing on tenv-acquirer.rp-2023app.com: order placement, payment method details, queries, refunds.
    • Incremental deployment and compatibility: temporarily keep reading of old fields, log usage of old fields, and phase them out gradually.
  • Key Breaking Changes
    • Restructured order placement request and response.
    • Field renaming and deprecation cleanup.

Updated 3 minutes ago

Did this page help you?

Updated 2 months ago