Payments

简体中文

English

简体中文

English

主题

拒付订单查询 ​

重要说明

调用此接口之前，需先联系我们开通查询拒付权限。

拒付订单查询API允许商户检索其交易中发生的拒付信息。拒付是指持卡人因欺诈、产品质量或未收到商品等问题向发卡机构对交易提出争议并要求退款。

API请求参数 ​

POST

关键参数

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

  • merchantTxnIds - 通过商户交易ID查询
  • originTransactionIds - 通过Onerway原始交易ID查询
  • chargebackIds - 通过拒付ID查询
  • importTimeStart 和 importTimeEnd - 通过Onerway接收拒付的时间范围查询

注意

  • 所有 JSON 字段必须在提交前进行字符串化处理
  • 嵌套对象必须序列化为 JSON 字符串格式
  • JSON 字段不能包含未转义的特殊字符
  • JSON 中的数组应该正确格式化
  • JSON 字符串字段示例：
json
{
  "object": "{\"obj-key1\":\"v1\",\"obj-key2\":\"v2\"}",
  "complex": "{\"k1\":\"v1\",\"array\":\"[{\\\"obj-key3\\\":\\\"v3\\\",\\\"obj-key4\\\":\\\"v4\\\"}]\"}"
}
ParameterTypeLengthRequiredSignedDescription

chargebackIds

String

/

Conditional

Yes

Multiple Onerway chargeback IDs for batch queries, separated by commas.



current

String

/

Yes

Yes

Current page number for paginated query results.



importTimeEnd

String

/

Conditional

Yes

End time when Onerway received the chargeback transaction.



importTimeStart

String

/

Conditional

Yes

Start time when Onerway received the chargeback transaction.



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.



originTransactionIds

String

/

Conditional

Yes

Multiple Onerway original 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.

响应 ​

NameTypeDescription

respCode

String

Response code from Onerway


respMsg

String

Response message from Onerway


data

Object

Response data. Refer to object data


data ​

NameTypeDescription

content

List

List of chargeback information


└merchantNo

String

Merchant number assigned by Onerway



└chargebackId

String

Chargeback transaction ID created by Onerway



└importTime

String

Time when Onerway received the chargeback transaction



Format: yyyy-MM-dd HH:mm:ss


└merchantTxnId

String

Merchant transaction ID of the original transaction



└originTransactionId

String

Original transaction ID from Onerway



└txnAmount

String

Original transaction amount in settlement currency



└txnCurrency

String

Settlement currency of the original transaction



See ISO 4217


└txnTime

String

Original transaction completion time



Format: yyyy-MM-dd HH:mm:ss


└paymentMethod

String

Payment method used in the original transaction



└chargebackAmount

String

Chargeback amount



└chargebackCurrency

String

Chargeback amount currency



See ISO 4217


└chargebackSettleAmount

String

Chargeback amount converted to settlement currency



└chargebackSettleCurrency

String

Settlement currency for the chargeback amount



See ISO 4217


└chargebackDate

String

Chargeback occurrence date



Format: yyyy-MM-dd


└chargebackStatus

String

Chargeback status



See

ChargebackStatusEnum

└chargebackReason

String

Chargeback reason description



└chargebackArn

String

Acquirer Reference Number (ARN)



└appealDueTime

String

Appeal deadline



Format: yyyy-MM-dd HH:mm:ss


└chargebackCode

String

Chargeback reason code



current

String

Current page number



size

String

Page size



totalPages

String

Total number of pages



totalElements

String

Total number of records



集成流程 ​

拒付查询集成流程包含简单的请求-响应流程：

在此流程中：

  • 商户系统发送带有适当过滤参数的查询请求
  • Onerway处理请求并检索匹配的拒付记录
  • Onerway向商户返回分页的拒付数据
  • 商户处理拒付数据进行争议管理

API使用示例 ​

按拒付ID查询 ​

当您需要检索特定拒付的信息时使用此方法：

json
{
  "chargebackIds": "1952311952441475072",        // 指定要查询的拒付ID
  "current": "1",                               // 页码
  "merchantNo": "800209",                       // 商户号
  "merchantTxnIds": "",                         // 按拒付ID查询时为空
  "originTransactionIds": "",                   // 按拒付ID查询时为空
  "sign": "e7304f610541b07fe197cfe9f4408ede1d7c46c4c8286cb8edc9744d51bb6285"  // 请求签名
}
json
{
  "respCode": "20000",                          // 成功响应码
  "respMsg": "Success",                         // 响应消息
  "data": {
    "content": [
      {
        "merchantNo": "800209",                  // 商户号
        "chargebackId": "1952311952441475072",   // 拒付ID
        "importTime": "2025-08-04 18:13:36",     // 导入时间
        "merchantTxnId": "1754043971000",        // 原始商户交易ID
        "originTransactionId": "1951227977069363200", // 原始Onerway交易ID
        "txnAmount": "50.00",                    // 原始交易金额
        "txnCurrency": "USD",                    // 原始交易币种
        "txnTime": "2025-08-01 18:26:36",        // 原始交易时间
        "paymentMethod": "VISA",                 // 支付方式
        "chargebackAmount": "50.00",             // 拒付金额
        "chargebackCurrency": "USD",             // 拒付币种
        "chargebackSettleAmount": null,          // 结算金额（同币种时为null）
        "chargebackSettleCurrency": null,        // 结算币种（同币种时为null）
        "chargebackDate": "2025-08-04",          // 拒付发生日期
        "chargebackReason": "未提供服务或未收到商品Merchandise/Services Not Recieved", // 拒付原因
        "chargebackArn": "test-015",             // 收单行参考号
        "chargebackCode": "13.1",                // 拒付代码
        "appealDueTime": "2025-08-12 18:13:36",  // 关键申诉截止时间
        "chargebackStatus": "NEW"                // 当前拒付状态
      }
    ],
    "current": "1",                            // 当前页码
    "size": 10,                               // 页面大小
    "totalPages": 1,                          // 总页数
    "totalElements": 1                        // 总记录数
  }
}

按时间范围查询 ​

当您需要检索特定时间段内接收的所有拒付时使用此方法：

json
{
  "chargebackIds": null,                        // 不按特定ID查询
  "current": "0",                               // 页码（从0开始）
  "importTimeEnd": "2025-08-11 18:13:36",       // 查询范围结束时间
  "importTimeStart": "2025-08-03 00:00:00",     // 查询范围开始时间
  "merchantNo": "800209",                       // 商户号
  "merchantTxnIds": "",                         // 按时间范围查询时为空
  "originTransactionIds": "",                   // 按时间范围查询时为空
  "sign": "4e55f0b62ddffc647800907a6e0fcfe1431a668662184d2fcdcd8e0c078e0a21"  // 请求签名
}
json
{
  "respCode": "20000",                          // 成功响应码
  "respMsg": "Success",                         // 响应消息
  "data": {
    "content": [
      {
        "merchantNo": "800209",                  // 商户号
        "chargebackId": "1952311952441475072",   // 拒付ID
        "importTime": "2025-08-04 18:13:36",     // 查询范围内的导入时间
        "merchantTxnId": "1754043971000",        // 原始商户交易ID
        "originTransactionId": "1951227977069363200", // 原始Onerway交易ID
        "txnAmount": "50.00",                    // 原始交易金额
        "txnCurrency": "USD",                    // 原始交易币种
        "txnTime": "2025-08-01 18:26:36",        // 原始交易时间
        "paymentMethod": "VISA",                 // 支付方式
        "chargebackAmount": "50.00",             // 拒付金额
        "chargebackCurrency": "USD",             // 拒付币种
        "chargebackSettleAmount": null,          // 结算金额（同币种时为null）
        "chargebackSettleCurrency": null,        // 结算币种（同币种时为null）
        "chargebackDate": "2025-08-04",          // 拒付发生日期
        "chargebackReason": "未提供服务或未收到商品Merchandise/Services Not Recieved", // 拒付原因
        "chargebackArn": "test-015",             // 收单行参考号
        "chargebackCode": "13.1",                // 拒付代码
        "appealDueTime": "2025-08-12 18:13:36",  // 关键申诉截止时间
        "chargebackStatus": "NEW"                // 当前拒付状态
      }
    ],
    "current": "1",                            // 当前页码
    "size": 10,                               // 页面大小
    "totalPages": 1,                          // 总页数
    "totalElements": 1                        // 总记录数
  }
}

重要提示

  • 查询的最大时间范围为 90 天
  • 必须提供至少一个过滤参数（merchantTxnIds、originTransactionIds、chargebackIds 或 时间范围）
  • 您必须先联系Onerway获取拒付查询权限

常见错误场景和解决方案 ​

实施最佳实践 ​

  1. 定期监控：实施例行流程，每日或每周检查新的拒付，以便及时识别和解决问题

  2. 交易关联：将拒付数据与您的原始交易记录关联，以便进行调查和响应

  3. 申诉管理：仔细跟踪申诉截止时间（appealDueTime），因为必须在指定时间内对拒付提出争议

  4. 证据收集：维护有组织的交易证据记录（发货确认、客户沟通等），以便在响应拒付时快速获取

  5. 风险分析：分析拒付模式，识别高风险交易类型、产品或客户群体

  6. 通知系统：实施新拒付的自动警报，以确保及时响应

  7. 文档记录：保存所有拒付解决的详细记录，包括提交的证据和结果

商户集成检查清单 ​

在生产环境中实施拒付查询API之前，请确保您已：

  • 已向Onerway申请并获得拒付查询权限
  • 拒付数据的安全存储
  • 将拒付与原始交易关联的流程
  • 新拒付的警报系统
  • 处理和申诉拒付的清晰工作流程
  • 定期监控计划
  • 在沙盒环境中进行充分测试