Refund 查询

Refund 查询 API 用于按退款记录维度检索结果，并可通过 paymentId 关联到同一支付意图下的交易链路。

字段关系

• paymentId：支付意图主键（一个 paymentId 可关联多笔 transactionId）。
• transactionId：退款交易流水号（单次退款交易）。
• originTransactionId：退款关联的原交易流水号。
• status：当前退款 transactionId 的交易状态，沿用 TxnStatusEnum。

ID 传输规则

paymentId 、 transactionId 、 originTransactionId 业务类型均为 Long ，JSON 统一以 String 传输。

API 请求参数

POST

Parameter	Type	Length	Required	Signed	Description
merchantNo	String	20	Yes	Yes	Merchant number assigned by Onerway upon registration, obtained from the Onerway merchant dashboard.
paymentId	String	/	No	Yes	Payment intent ID. Business type is Long, transmitted as String in JSON.
transactionId	String	/	No	Yes	Refund transaction ID. Business type is Long, transmitted as String in JSON.
originTransactionId	String	20	Conditional	Yes	Original transaction ID from Onerway for reference transactions.
startTime	String	/	Conditional	Yes	Start time for the transaction query period filter.
endTime	String	/	Conditional	Yes	End time for the transaction query period filter.
current	String	/	No	Yes	Page number for refund queries.
size	String	/	No	Yes	Page size.
sign	String	/	Yes	No	Digital signature string for request verification and security. Please refer to Signature for signature generation method.

分页规则

• current=0 和 current=1 都表示第一页。
• 响应中的 current 统一返回 1-based 页码（第一页为 1）。
• size 默认 10，最大 100。

响应

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	Refund records list.
└paymentId	String	Payment intent ID. Business type is Long, transmitted as String in JSON.
└originTransactionId	String	Original transaction ID for the refund. Business type is Long, transmitted as String in JSON.
└transactionId	String	Refund transaction ID. Business type is Long, transmitted as String in JSON.
└status	String	Refund transaction status. See TxnStatusEnum .
└reason	String	Refund failure reason (if any).
└amount	String	Refund amount.
└currency	String	Refund currency. See ISO 4217.
└arn	String	Acquirer Reference Number.
└createTime	String	Refund creation time. Format: yyyy-MM-dd HH:mm:ss.
current	String	Current page number in response (1-based).
size	String	Page size.
totalPages	String	Total pages.
totalElements	String	Total records.

API 使用示例

请求

{
  "merchantNo": "10001",
  "current": "1",
  "size": "10",
  "startTime": "2026-01-01 00:00:00",
  "endTime": "2026-03-28 23:59:59",
  "sign": "your_sign_value"
}

响应

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "content": [
      {
        "paymentId": "2031306986167336960",
        "originTransactionId": "2031306986184114176",
        "transactionId": "2032020307921207296",
        "status": "S",
        "reason": null,
        "amount": "1.00",
        "currency": "USD",
        "arn": null,
        "createTime": "2026-03-12 17:06:09"
      }
    ],
    "current": "1",
    "size": 10,
    "totalPages": 1,
    "totalElements": 1
  }
}

实施最佳实践

1. 建议优先按 paymentId 查询并贯通 Payment/Refund/Webhook 对账。
2. 同时落库 originTransactionId 与 transactionId，用于原单与退款单双向追踪。
3. 通过时间窗口 + 分页方式查询，避免全量扫描。

相关文档链接

• Payment 查询
• 申请退款
• 交易 Webhook
• 签名