• Ethoca 预警查询
  • 功能说明
    • 预警类型
  • 接口定义
  • 请求参数
  • 响应参数
    • data
    • content 中的对象
  • 请求及响应示例
  • 预警处理流程
  • 注意事项

Ethoca 预警查询

本文档介绍如何查询 Ethoca 预警信息。通过该接口，您可以查询特定时间范围内的预警详情，包括交易争议、欺诈风险等预警信息。

功能说明

预警查询接口允许商户：

• 分页查询预警信息
• 按多个维度筛选预警记录
• 查看预警的详细信息和处理状态
• 跟踪预警从产生到处理的全流程

预警类型

预警类型主要包括：

• CustomerDispute - 客户争议
• FraudAlert - 欺诈预警
• ChargebackAlert - 拒付预警

接口定义

GET

请求参数

名称	类型	长度	必填	签名	描述
merchantNo	String	20	Yes	Yes	商户编号，用于标识商户身份
ethocaId	String	64	No	Yes	Ethoca 预警唯一标识
alertTypes	String	32	No	Yes	预警类型： CustomerDispute - 客户争议 FraudAlert - 欺诈预警 ChargebackAlert - 拒付预警
alertTimeStart	String	32	No	Yes	预警生成时间范围起始值，格式：yyyy-MM-dd HH:mm:ss
alertTimeEnd	String	32	No	Yes	预警生成时间范围结束值，格式：yyyy-MM-dd HH:mm:ss
txnTimeStart	String	32	No	Yes	原交易时间范围起始值，格式：yyyy-MM-dd HH:mm:ss
txnTimeEnd	String	32	No	Yes	原交易时间范围结束值，格式：yyyy-MM-dd HH:mm:ss
outcomeUpdatedTimeStart	String	32	No	Yes	预警处理状态更新时间范围起始值，格式：yyyy-MM-dd HH:mm:ss
outcomeUpdatedTimeEnd	String	32	No	Yes	预警处理状态更新时间范围结束值，格式：yyyy-MM-dd HH:mm:ss
billDesc	String	128	No	Yes	商户账单描述信息，用于匹配交易
resellerSubMerchantId	String	20	No	Yes	代理商子商户编号，代理商为其子商户查询时必填
outcomeList	String	32	No	Yes	预警处理状态列表，多个状态使用英文逗号分隔： stopped - 订单已停止 partially_stopped - 订单部分停止 previously_cancelled - 交易已被取消 missed - 已过期（订单已发货或服务已消费） notfound - 未找到相关订单 account_suspended - 账户已被暂停 in_progress - 正在处理该请求 shipper_contacted - 已联系发货方并尝试拦截货物 other - 其他未列出的情况 resolved - 已解决 previously_refunded - 已退款 unresolved_dispute - 未解决的争议
current	String	8	Yes	Yes	分页页码，从 1 开始
sign	String	/	Yes	No	请求签名，详见签名说明

响应参数

名称	类型	描述
respCode	String	来自 Onerway 的响应码
respMsg	String	来自 Onerway 的响应信息
data	Object	响应数据。 请参阅对象 data

data

名称	签名	类型	描述
content	Yes	Array	预警记录列表
current	Yes	String	当前页码
size	Yes	Number	每页记录数
totalPages	Yes	Number	总页数
totalElements	Yes	Number	总记录数

content 中的对象

名称	签名	类型	描述
merchantNo	Yes	String	商户编号
ethocaId	Yes	String	Ethoca 预警唯一标识
alertTime	Yes	String	预警生成时间
alertAge	Yes	String	预警时效期限
initiatedBy	Yes	String	预警发起方（卡组织）
liability	Yes	String	责任方判定结果
billDesc	Yes	String	商户账单描述信息
ethocaMerchantId	Yes	String	Ethoca 平台商户标识
resellerSubMerchantId	Yes	String	代理商子商户编号
integratorMemberId	Yes	String	集成商会员编号
issuer	Yes	String	发卡机构标识
cardNumber	Yes	String	交易卡号（脱敏）
arn	Yes	String	收单参考号（ARN）
txnTime	Yes	String	原交易时间
mcc	Yes	String	商户类别代码（MCC）
txnAmount	Yes	String	原交易金额
txnCurrency	Yes	String	原交易币种，符合 ISO 4217 标准
transactionType	Yes	String	交易类型，如：eCommerce
authCode	Yes	String	原交易授权码
transactionId	Yes	String	原交易流水号
chargebackReasonCode	Yes	String	拒付原因代码
chargebackAmount	Yes	String	拒付金额
chargebackCurrency	Yes	String	拒付币种，符合 ISO 4217 标准
outcome	Yes	String	预警处理结果
refundStatus	Yes	String	退款状态
outcomeUpdatedTime	Yes	String	预警处理状态更新时间
alertType	Yes	String	预警类型，见预警类型
sign	No	String	响应签名，详见签名说明

请求及响应示例

GET

请求参数

{
  "alertTimeEnd": "2025-04-03 13:22:26",
  "alertTimeStart": "2025-02-02 13:22:26",
  "alertTypes": "CustomerDispute",
  "billDesc": null,
  "current": "1",
  "ethocaId": "",
  "merchantNo": "800209",
  "outcomeList": null,
  "outcomeUpdatedTimeEnd": "2025-04-03 13:22:26",
  "outcomeUpdatedTimeStart": "2025-02-02 13:22:26",
  "resellerSubMerchantId": "",
  "sign": "f4dfb7d8c43bd3dd85000006a4be178c78ab2733c96f4a165413ee2dca37ae1a",
  "txnTimeEnd": "2025-04-03 13:22:26",
  "txnTimeStart": "2025-02-02 13:22:26"
}

响应示例

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "content": [
            {
                "merchantNo": "800209",
                "ethocaId": "nIlSfB1HCC-wDyC93-8a8",
                "alertTime": null,
                "alertAge": null,
                "initiatedBy": "jcb",
                "liability": "no",
                "billDesc": "ONERWAY 400-139-8889 CN 83036",
                "ethocaMerchantId": "347646",
                "resellerSubMerchantId": "965566",
                "integratorMemberId": "37453014",
                "issuer": "CARD_ISSUER",
                "cardNumber": "4000000000002701",
                "arn": "928916809996637803",
                "txnTime": "2025-03-28 15:26:33",
                "mcc": "5629",
                "txnAmount": null,
                "txnCurrency": "USD",
                "transactionType": "eCommerce",
                "authCode": "111047",
                "transactionId": "1905524191839780864",
                "chargebackReasonCode": "10",
                "chargebackAmount": null,
                "chargebackCurrency": "USD",
                "outcome": "resolved",
                "refundStatus": "refunded",
                "outcomeUpdatedTime": "2025-03-28 16:32:25",
                "alertType": "CustomerDispute",
                "sign": null
            }
        ],
        "current": "1",
        "size": 10,
        "totalPages": 1,
        "totalElements": 1
    }
}

预警处理流程

注意事项

注意事项

1. 建议合理设置查询条件，避免返回过多数据
2. 请求参数需要按照签名规则进行签名

最佳实践

1. 定期查询未处理的预警信息
2. 对高风险预警及时处理
3. 保存预警ID，便于后续跟踪处理结果
4. 合理使用筛选条件提高查询效率