交易订单查询

交易订单查询 API 允许商户检索详细的交易数据和订单详情，用于交易状态对账、争议管理和报告目的。

API 请求参数

POST

关键参数

在请求参数中，必须提供以下参数之一：

• merchantTxnIds - 用于按商户交易 ID 查询
• transactionIds - 用于按 Onerway 交易 ID 查询
• startTime 和 endTime - 用于按时间范围查询（最大 90 天间隔）

注意

• 所有 JSON 字段必须在提交前进行字符串化处理
• 嵌套对象必须序列化为 JSON 字符串格式
• JSON 字段不能包含未转义的特殊字符
• JSON 中的数组应该正确格式化
• JSON 字符串字段示例：

{
  "object": "{\"obj-key1\":\"v1\",\"obj-key2\":\"v2\"}",
  "complex": "{\"k1\":\"v1\",\"array\":\"[{\\\"obj-key3\\\":\\\"v3\\\",\\\"obj-key4\\\":\\\"v4\\\"}]\"}"
}

Parameter	Type	Length	Required	Signed	Description
current	String	/	Yes	Yes	Current page number for paginated query results.
endTime	String	/	Conditional	Yes	End time for the transaction query period filter.
merchantNo	String	20	Yes	Yes	Merchant number assigned by Onerway upon registration, obtained from the Onerway merchant dashboard.
merchantTxnIds	String	/	Conditional	Yes	Multiple merchant transaction IDs for batch queries, separated by commas.
sign	String	/	Yes	No	Digital signature string for request verification and security. Please refer to Signature for signature generation method.
startTime	String	/	Conditional	Yes	Start time for the transaction query period filter.
transactionIds	String	/	Conditional	Yes	Multiple Onerway transaction IDs for batch queries, separated by commas.
txnTypes	String	/	No	Yes	Multiple transaction types for filtering queries, separated by commas. See TxnTypeEnum for available options.

响应

Name	Type	Description
respCode	String	Response code from Onerway
respMsg	String	Response message from Onerway
data	Object	Response data. Refer to object data

data

Name	Type	Description
content	List	Transaction information list
└transactionId	String	Transaction order number created by Onerway, corresponds to merchant's order number
└merchantTxnId	String	Merchant transaction order number created by the merchant. Different order numbers are considered different transactions
└merchantTxnOriginalId	String	Original merchant transaction order number, same as the request parameter field
└txnTime	String	Transaction completion time
└txnTimeZone	String	Transaction time zone, format: +/-HH:mm
└originTransactionId	String	Original transaction order number from Onerway. Present for refund, void, and capture transactions
└productType	String	Product type, please refer to ProductTypeEnum
└subProductType	String	Sub-product type, please refer to SubProductTypeEnum
└txnType	String	Transaction type, please refer to TxnTypeEnum
└status	String	Transaction processing result. Please refer to TxnStatusEnum
└contractId	String	Subscription contract number: Identifies which subscription it is, an important parameter for completing subscription repurchase
└tokenId	String	Subscription/card binding token ID, returned for subscription/card binding transactions.
└userPaymentStatus	String	User payment status true: paid false: unpaid
└cardType	String	Card type, such as VISA, MASTERCARD, etc.
└paymentMethod	String	Specific payment method, including card and local payment types
└orderAmount	String	Order amount in base units.
└settleRate	String	Exchange rate. Calculation formula: txnAmount = orderAmount * settleRate
└orderCurrency	String	Transaction order currency. Please refer to ISO 4217 currency codes
└txnAmount	String	Order amount converted to the settlement currency
└txnCurrency	String	Settlement currency. Please refer to ISO 4217 currency codes
└customsDeclarationAmount	String	Amount available for customs declaration
└customsDeclarationCurrency	String	Currency corresponding to the amount available for customs declaration. Please refer to ISO 4217 currency codes
└arn	String	ARN (Acquirer Reference Number)
└appId	String	Merchant application ID. When a merchant registers a website, OnerWay creates an application ID for the merchant
└website	String	Transaction website
└cardBinCountry	String	Country of card bin
└cardNumber	String	Transaction card number (masked)
└walletTypeName	String	Brand name of the wallet
└reason	String	Transaction failure reason. Contains details when status is not successful
└holderName	String	Cardholder name
└eci	String	Liability shift, parameter required for 3D Secure
└email	String	Customer email address
└creditCard	Object	Credit card information. Please refer to CreditCardEnum
└channelRequestId	String	Unique identifier for the payment channel request
current	String	Current page number, 10 records per page
size	String	Current page size
totalPages	String	Total number of pages
totalElements	String	Total number of records

VerificationResult

Name	Description
version	3ds version
authenticationFlow	3ds flow
chargebackLiability	3ds chargeback liability When transStatus is [N,R], chargebackLiability cannot use UNKNOWN.
transStatus	3ds transaction status
transStatusReason	3ds transaction status reason
eci	eci (Electronic Commerce Indicator)
cvvResult	cvv verification result See CvvResultEnum for all possible result codes.
avsFullResult	avs address verification service result See AvsFullResultEnum for all possible result codes.
cavvResult	3ds authentication return (CAVV)

集成流程

交易订单查询集成流程包含一个简单的请求-响应流程：

在此流程中：

• 商户系统发送带有适当过滤参数的查询请求
• Onerway 处理请求并检索匹配的交易记录
• Onerway 将分页的交易数据返回给商户
• 商户处理交易数据用于对账或报告目的

API 使用示例

根据交易 ID 查询

当您需要通过 Onerway 交易 ID 检索特定交易时使用此方法：

请求

{
  "current": "1",
  "endTime": "2025-10-27 12:00:00",
  "merchantNo": "800314",
  "merchantTxnIds": null,
  "sign": "f62e37c34867c7497075ee852f0225915015f0d6c8e238d6590dac48f4383360",
  "startTime": "2025-10-27 10:00:00",
  "transactionIds": "1982651780785643520",
  "txnTypes": null
}

响应

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "content": [
      {
        "transactionId": "1982651780785643520",
        "merchantTxnId": "138653794309390",
        "merchantTxnOriginalId": null,
        "txnTime": "2025-10-27 11:33:15",
        "txnTimeZone": "+08:00",
        "txnCompletionTime": "2025-10-27 11:33:20",
        "originTransactionId": null,
        "productType": "CARD",
        "subProductType": "DIRECT",
        "txnType": "SALE",
        "status": "S",
        "contractId": null,
        "tokenId": null,
        "userPaymentStatus": null,
        "cardType": "VISA",
        "paymentMethod": "VISA",
        "orderAmount": "110.00",
        "settleRate": "1",
        "orderCurrency": "USD",
        "txnAmount": "110.00",
        "txnCurrency": "USD",
        "customsDeclarationAmount": null,
        "customsDeclarationCurrency": null,
        "arn": null,
        "appId": "1858387695237468160",
        "website": "www.314worldpay.com",
        "cardBinCountry": "PL",
        "cardNumber": "491761******0000",
        "walletTypeName": null,
        "reason": null,
        "holderName": "TAO YUN",
        "eci": null,
        "email": "111144@QQ.COM",
        "creditCard": {
          "holderName": "TAO YUN",
          "year": "2026",
          "month": "03",
          "verificationResult": {
            "version": null,
            "authenticationFlow": null,
            "authenticationCode": "578660",
            "chargebackLiability": null,
            "transStatus": null,
            "transStatusReason": null,
            "veresEnrolled": null,
            "eci": null,
            "cvvResult": null,
            "avsFullResult": null,
            "cavvResult": null
          },
          "cardType": "VISA",
          "productCategory": null,
          "issuer": "发卡行测试-接口",
          "cardNumber": "491761******0000"
        },
        "channelRequestId": "8003141982651789446615041"
      }
    ],
    "current": "1",
    "size": 10,
    "totalPages": 1,
    "totalElements": 1
  }
}

重要提示

按交易类型查询时，startTime 和 endTime 参数都是必需的。
允许的最大时间范围为 90 天。

常见错误场景和解决方案

常见错误代码

实施最佳实践

1. 分页查询
   对于大型数据集，使用 current 参数实现分页逻辑来处理多页结果

2. 高效查询
   为您的用例使用最具体的可用参数：

   • 在查找特定交易时按交易 ID 查询
   • 在与您自己的系统对账时按商户交易 ID 查询
   • 仅在批量处理必要时按时间范围查询

3. 数据同步
   实施定期同步流程以对账您的系统和 Onerway 之间的交易状态

4. 错误处理
   实施适当的 API 错误处理，包括临时故障的重试逻辑

5. 交易状态
   特别注意交易状态字段以识别成功、待处理和失败的交易

商户集成检查清单

在生产环境中实施交易订单查询 API 之前，请确保您具备：

• 交易记录的安全数据存储
• 适当的错误处理机制
• 大型结果集的分页处理
• 数据对账流程
• 在沙箱环境中进行彻底测试