# Query Ethoca alerts

> Query Ethoca alert records by alert identifier, alert type, time range, billing descriptor, or outcome.

```yaml
openapi: 3.1.0
info:
  title: Query Ethoca alerts
  version: 1.0.0
  description: Query Ethoca alert records by alert identifier, alert type, time
    range, billing descriptor, or outcome.
paths:
  /ethoca/agency-cw/detail-page:
    post:
      summary: Query Ethoca alerts
      description: Query Ethoca alert records by alert identifier, alert type, time
        range, billing descriptor, or outcome.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantNo:
                  type: string
                  description: Merchant number assigned by Onerway. It limits the query to one
                    merchant account.
                ethocaId:
                  type: string
                  description: Unique Ethoca alert identifier. Submit it to query one alert
                    precisely.
                alertTypes:
                  type: string
                  description: Alert type filter. Different alert types represent customer
                    dispute, fraud, or chargeback risk sources.
                  enum:
                    - CustomerDispute
                    - FraudAlert
                    - ChargebackAlert
                  x-enum-descriptions:
                    CustomerDispute: Customer dispute alert.
                    FraudAlert: Fraud alert.
                    ChargebackAlert: Chargeback alert.
                alertTimeStart:
                  type: string
                  description: Start of the alert creation time range, in `yyyy-MM-dd HH:mm:ss`
                    format.
                  x-onerway-condition:
                    - Provide this field when filtering by alert creation time
                      range.
                alertTimeEnd:
                  type: string
                  description: End of the alert creation time range, in `yyyy-MM-dd HH:mm:ss`
                    format.
                  x-onerway-condition:
                    - Provide this field when filtering by alert creation time
                      range.
                txnTimeStart:
                  type: string
                  description: Start of the original transaction time range, in `yyyy-MM-dd
                    HH:mm:ss` format.
                  x-onerway-condition:
                    - Provide this field when filtering by original transaction
                      time range.
                txnTimeEnd:
                  type: string
                  description: End of the original transaction time range, in `yyyy-MM-dd
                    HH:mm:ss` format.
                  x-onerway-condition:
                    - Provide this field when filtering by original transaction
                      time range.
                outcomeUpdatedTimeStart:
                  type: string
                  description: Start of the alert outcome update time range, in `yyyy-MM-dd
                    HH:mm:ss` format.
                  x-onerway-condition:
                    - Provide this field when filtering by alert outcome update
                      time range.
                outcomeUpdatedTimeEnd:
                  type: string
                  description: End of the alert outcome update time range, in `yyyy-MM-dd
                    HH:mm:ss` format.
                  x-onerway-condition:
                    - Provide this field when filtering by alert outcome update
                      time range.
                billDesc:
                  type: string
                  description: Merchant billing descriptor used to filter alert records.
                resellerSubMerchantId:
                  type: string
                  description: Sub-merchant identifier assigned by the agency operator.
                  x-onerway-required: conditional
                  x-onerway-condition:
                    - Required when an agency operator queries alert records for
                      its sub-merchants.
                outcomeList:
                  type: string
                  description: Alert outcome filter, used to distinguish handled and pending
                    alerts.
                  enum:
                    - stopped
                    - partially_stopped
                    - previously_cancelled
                    - missed
                    - notfound
                    - account_suspended
                    - in_progress
                    - shipper_contacted
                    - other
                    - resolved
                    - previously_refunded
                    - unresolved_dispute
                  x-enum-descriptions:
                    stopped: Order stopped.
                    partially_stopped: Order partially stopped.
                    previously_cancelled: Transaction previously cancelled.
                    missed: Expired; the order has shipped or the service has been consumed.
                    notfound: Related order not found.
                    account_suspended: Account suspended.
                    in_progress: Request in progress.
                    shipper_contacted: Shipper contacted to attempt shipment interception.
                    other: Other situation not listed.
                    resolved: Resolved.
                    previously_refunded: Previously refunded.
                    unresolved_dispute: Unresolved dispute.
                  x-onerway-constraints:
                    - kind: rule
                      text: Submit one or more outcomes. Separate multiple values with commas.
                current:
                  type: string
                  description: Query page number, starting from `1`.
                sign:
                  type: string
                  description: Request signature string. See [Request
                    signing](/payments/get-started/request-signing) for how to
                    generate it.
              required:
                - merchantNo
                - current
                - sign
            examples:
              query-ethoca-alerts:
                summary: Query Ethoca alerts
                value:
                  alertTypes: ChargebackAlert
                  current: "1"
                  merchantNo: replace_with_merchant_no
                  outcomeList: in_progress,previously_refunded
                  sign: "{{SIGN}}"
      responses:
        "200":
          description: Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  respCode:
                    type: string
                    description: "`20000` means the query request was processed successfully. Other
                      values are error codes. See [Response
                      codes](/payments/api-reference/response-codes)."
                  respMsg:
                    type: string
                    description: Human-readable message for the response code.
                  data:
                    type: object
                    properties:
                      content:
                        type: array
                        description: Ethoca alert records matching the query conditions. Each record
                          includes original transaction information and alert
                          handling information.
                        items:
                          type: object
                          properties:
                            merchantNo:
                              type: string
                              description: Merchant number assigned by Onerway, identifying the merchant
                                account.
                            ethocaId:
                              type: string
                              description: Unique Ethoca alert identifier. Submit this value when reporting an
                                alert outcome.
                            alertTime:
                              type:
                                - string
                                - "null"
                              description: Alert creation time.
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Can return `null`.
                                  zh: 可能返回 `null`。
                            alertAge:
                              type:
                                - string
                                - "null"
                              description: Alert response time limit. Complete order matching and handling
                                within this window to intervene before a formal
                                chargeback occurs.
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Can return `null`.
                                  zh: 可能返回 `null`。
                            initiatedBy:
                              type: string
                              description: Alert initiator, usually a card network or issuer-related network
                                identifier.
                            liability:
                              type: string
                              description: Liability assessment result for the alert or dispute. Treat it as
                                supporting information, not a replacement for
                                reviewing `alertType`, `outcome`, and refund
                                status.
                            billDesc:
                              type: string
                              description: Merchant billing descriptor.
                            ethocaMerchantId:
                              type: string
                              description: Ethoca merchant identifier.
                            resellerSubMerchantId:
                              type:
                                - string
                                - "null"
                              description: Agency sub-merchant identifier.
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value for agency sub-merchant alert records. Regular merchant records
                                    can return `null`.
                                  zh: 代理运营商子商户预警记录中有值；普通商户记录可能为空。
                            integratorMemberId:
                              type: string
                              description: Integrator member ID.
                            issuer:
                              type: string
                              description: Issuer identifier.
                            cardNumber:
                              type: string
                              description: Masked transaction card number.
                            arn:
                              type: string
                              description: Acquirer Reference Number (ARN).
                            txnTime:
                              type: string
                              description: Original transaction time.
                            mcc:
                              type: string
                              description: Merchant Category Code (MCC).
                            txnAmount:
                              type:
                                - string
                                - "null"
                              description: Original transaction amount.
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Can return `null`.
                                  zh: 可能返回 `null`。
                            txnCurrency:
                              type: string
                              description: Original transaction currency, using a three-letter [ISO
                                4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)
                                currency code.
                            transactionType:
                              type: string
                              description: Transaction type returned for the original transaction.
                            authCode:
                              type: string
                              description: Authorization code of the original transaction.
                            transactionId:
                              type: string
                              description: Original transaction identifier.
                            chargebackReasonCode:
                              type:
                                - string
                                - "null"
                              description: Chargeback reason code.
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Usually has a value for chargeback-related alerts; can be empty outside a
                                    chargeback context.
                                  zh: 拒付相关预警中通常有值；非拒付语境可能为空。
                            chargebackAmount:
                              type:
                                - string
                                - "null"
                              description: Chargeback amount.
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Can return `null`.
                                  zh: 可能返回 `null`。
                            chargebackCurrency:
                              type:
                                - string
                                - "null"
                              description: Chargeback currency, using a three-letter [ISO
                                4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)
                                currency code.
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Usually has a value for chargeback-related alerts; can be empty outside a
                                    chargeback context.
                                  zh: 拒付相关预警中通常有值；非拒付语境可能为空。
                            outcome:
                              type:
                                - string
                                - "null"
                              description: Alert outcome reported by the merchant.
                              enum:
                                - stopped
                                - partially_stopped
                                - previously_cancelled
                                - missed
                                - notfound
                                - account_suspended
                                - in_progress
                                - shipper_contacted
                                - other
                                - resolved
                                - previously_refunded
                                - unresolved_dispute
                                - null
                              x-enum-descriptions:
                                stopped: Order stopped.
                                partially_stopped: Order partially stopped.
                                previously_cancelled: Transaction previously cancelled.
                                missed: Expired; the order has shipped or the service has been consumed.
                                notfound: Related order not found.
                                account_suspended: Account suspended.
                                in_progress: Request in progress.
                                shipper_contacted: Shipper contacted to attempt shipment interception.
                                other: Other situation not listed.
                                resolved: Resolved.
                                previously_refunded: Previously refunded.
                                unresolved_dispute: Unresolved dispute.
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Can be empty before the alert is handled or before the outcome is
                                    synchronized back.
                                  zh: 预警尚未处理或处理结果未回填时可能为空。
                            refundStatus:
                              type:
                                - string
                                - "null"
                              description: Refund status corresponding to the alert outcome.
                              enum:
                                - refunded
                                - not refunded
                                - not settled
                                - null
                              x-enum-descriptions:
                                refunded: Refund completed.
                                not refunded: No refund was issued.
                                not settled: Refund is processing.
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Can be empty before the alert is handled or before refund status is
                                    synchronized back.
                                  zh: 预警尚未处理或退款状态未回填时可能为空。
                            outcomeUpdatedTime:
                              type:
                                - string
                                - "null"
                              description: Alert outcome update time.
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Can be empty before the alert outcome is updated.
                                  zh: 预警处理状态尚未更新时可能为空。
                            alertType:
                              type: string
                              description: Alert type identifying the risk source of this alert.
                              enum:
                                - CustomerDispute
                                - FraudAlert
                                - ChargebackAlert
                              x-enum-descriptions:
                                CustomerDispute: Customer dispute alert.
                                FraudAlert: Fraud alert.
                                ChargebackAlert: Chargeback alert.
                            sign:
                              type:
                                - string
                                - "null"
                              description: Record-level response signature string.
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Can return `null`.
                                  zh: 可能返回 `null`。
                      current:
                        type: string
                        description: Current returned page number, using 1-based numbering.
                      size:
                        type: number
                        description: Page size. The current page size is fixed at 10 records.
                      totalPages:
                        type: number
                        description: Total number of pages based on the current page size.
                      totalElements:
                        type: number
                        description: Total number of Ethoca alert records matching the query conditions.
                    description: Business data object containing Ethoca alerts and pagination
                      information.
```