> ## Documentation Index > Fetch the complete documentation index at: https://waffo.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Chargeback list > Query chargebacks by creation time range, status and life cycle. Note: this API does not return the message and evidence objects; use Chargeback inquiry to retrieve them. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/chargeback/list openapi: 3.1.0 info: title: acquiring-order description: 接口文档 termsOfService: https://www.waffo.com version: 1.0.0 servers: [] security: [] tags: - name: Subscription inquiry description: Subscription inquiry api description - name: Subscription manage description: > This API allows the merchant to request a subscription management URL from Waffo Waffo will generate a subscription management URL which merchant can redirect user to this URL for managing subscription details (e.g. view subscription detail and cancel subscription). This management URL has a fixed expiration time (e.g., 1 day). - name: Subscription change inquiry description: > This API allows merchants to query the status of a subscription change (upgrade/downgrade) request. 此接口允许商户查询订阅升降级请求的状态。 - name: Subscription update description: ' Subscription update api description' - name: Order inquiry description: Order inquiry api description - name: Payout inquiry description: Payout inquiry api description - name: Order create description: ' Order create api description' - name: Pay Method Config Inquiry description: Pay Method Config Inquiry api description - name: Order cancel description: Order cancel api description - name: Order capture description: Order capture api description - name: Chargeback list description: Chargeback list api description - name: Payout create description: Payout create api description - name: Chargeback file download description: Chargeback file download api description - name: Subscription change description: > This API allows merchants to upgrade or downgrade a user's subscription plan. The change request will create a new subscription based on the original subscription, applying any remaining amount from the original subscription. 此接口允许商户升级或降级用户的订阅计划。升降级请求将基于原订阅创建新订阅，并将原订阅的剩余金额应用到新订阅中。 - name: Chargeback accept description: Chargeback accept api description - name: Chargeback file upload description: Chargeback file upload api description - name: Chargeback update description: Chargeback update api description - name: Wallet inquiry description: Wallet inquiry api description - name: Order refund description: Order refund api description - name: Refund inquiry description: Refund inquiry api description - name: Subscription cancel description: > Cancel an active subscription when the merchant no longer wishes to continue the recurring billing cycle. This endpoint can only be invoked when the subscription status is active - name: Merchant config inquiry description: Merchant config inquiry api description - name: Chargeback inquiry description: Chargeback inquiry api description - name: Subscription create description: Subscription create api description - name: Reported Fraud list description: Reported Fraud list api description paths: /api/v1/chargeback/list: post: tags: - Chargeback list summary: Chargeback list description: >- Query chargebacks by creation time range, status and life cycle. Note: this API does not return the message and evidence objects; use Chargeback inquiry to retrieve them. operationId: chargebackList requestBody: content: application/json: schema: $ref: '#/components/schemas/ChargebackListRequest' required: true responses: '200': description: OK content: '*/*': schema: $ref: >- #/components/schemas/ResponseApiPageResponseChargebackQueryResponse components: schemas: ChargebackListRequest: type: object description: >- Chargeback list request. Note: this API does not return the message and evidence objects. Call the chargeback inquiry API on a specific chargebackId to retrieve them. properties: merchantId: type: string default: '1000000201' description: Merchant Id assigned by Waffo example: 1000000201 maxLength: 64 minLength: 0 chargebackStatus: type: array description: >- Chargeback status filter. Multiple values are combined with OR. Accepted values: **ACTION_REQUIRED**, **UNDER_REVIEW**, **SECOND_CYCLE_RESPONSE_REQUIRED**, **ESCALATE_TO_2ND_CYCLE**, **CASE_WON**, **CANCELED**, **SETTLED**, **CASE_LOST**, **ACCEPTED**, **EXPIRED**. Refer to chargebackStatus in the response for the meaning of each value. Records in Waffo's internal pending status are never returned by this API, regardless of this filter. items: type: string lifeCycle: type: string description: >- Chargeback life cycle filter **FIRST_CYCLE** (First round of the chargeback dispute) **SECOND_CYCLE** (Second round (Pre-Arbitration), escalated from First Cycle) Not specified means both. startTime: type: string format: date-time description: >- Start time. Filters on the time the chargeback record was created by Waffo, NOT on the time its status was last updated. The range between startTime and endTime must be within 3 months. x-gen: DATETIME_ISO endTime: type: string format: date-time description: >- End time. Filters on the time the chargeback record was created by Waffo, NOT on the time its status was last updated. The range between startTime and endTime must be within 3 months. x-gen: DATETIME_ISO pageNum: type: integer format: int32 description: Page number, starting from 1 example: 1 minimum: 1 pageSize: type: integer format: int32 description: 'Number of records per page. Maximum: 100' example: 20 maximum: 100 minimum: 1 required: - endTime - merchantId - pageNum - pageSize - startTime ResponseApiPageResponseChargebackQueryResponse: type: object description: response data properties: code: type: string example: 0 msg: type: string example: success data: $ref: '#/components/schemas/ApiPageResponseChargebackQueryResponse' ApiPageResponseChargebackQueryResponse: type: object description: Paged data properties: records: type: array description: >- Records of the current page, empty array when nothing matches the query items: $ref: '#/components/schemas/ChargebackQueryResponse' total: type: integer format: int64 description: Total number of records matching the query example: 125 size: type: integer format: int64 description: Page size, echoes pageSize in the request example: 20 current: type: integer format: int64 description: Current page number, starts from 1 example: 1 pages: type: integer format: int64 description: Total number of pages, derived from total and size example: 7 ChargebackQueryResponse: type: object description: ChargebackQueryResponse properties: chargebackId: type: string description: Chargeback order Id assigned by Waffo originalOrderId: type: string description: >- Waffo original order Id, i.e. the acquiring order this chargeback was raised against originalPaymentRequestId: type: string description: >- Original payment request ID sent from merchant when the disputed order was created. Returned for non-subscription chargebacks only merchantId: type: string description: Merchant Id assigned by Waffo merchantOrderId: type: string description: >- Merchant order ID sent from merchant when the disputed order was created. Returned for non-subscription chargebacks only lifeCycle: type: string description: >- Chargeback life cycle **FIRST_CYCLE** (First round of the chargeback dispute) **SECOND_CYCLE** (Second round (Pre-Arbitration), escalated from First Cycle) relevantChargebackId: type: string description: >- The associated chargeback ID between First Cycle and Second Cycle. On a FIRST_CYCLE record it points to the Second Cycle chargeback it was escalated to; on a SECOND_CYCLE record it points back to the originating First Cycle chargeback chargebackStatus: type: string description: >- Chargeback status **ACTION_REQUIRED** (Submit evidence before expiryDateTime. Amount and fee are debited now) **UNDER_REVIEW** (Evidence submitted, under channel review) **SECOND_CYCLE_RESPONSE_REQUIRED** (Second Cycle, Pre-Arbitration. Defend or accept; evidence is not accepted. Only the fee is debited) **ESCALATE_TO_2ND_CYCLE** (Escalated to Second Cycle. No further debit) **CASE_WON** (Channel ruled for merchant. Amount refunded, fee retained) **CANCELED** (Withdrawn by the channel or payer. Amount refunded, fee retained) **SETTLED** (Settled offline. Amount refunded, fee retained) **CASE_LOST** (Channel ruled against merchant. Not refunded) **ACCEPTED** (Merchant accepted the chargeback. Not refunded) **EXPIRED** (No evidence submitted before expiryDateTime. Not refunded) Funds are debited when the chargeback is created, not when it closes. If it later closes in the merchant's favour the amount is refunded and the fee is retained. A case escalated to Second Cycle is not debited twice. CASE_LOST, ACCEPTED and EXPIRED can still change afterwards, so treat the latest notification as authoritative amount: type: string description: >- Chargeback order amount. Usually the original transaction amount, but it can be less when only part of the order is disputed currency: type: string description: Chargeback amount currency, ISO 4217, e.g. IDR feeAmount: type: string description: Chargeback fee amount charged by Waffo feeCurrency: type: string description: Chargeback fee currency, ISO 4217. May differ from currency reasonCode: type: string description: Chargeback reason code returned by the payment channel reason: type: string description: Chargeback reason returned by the payment channel description: type: string description: Chargeback description information chargebackDateTime: type: string description: >- The time the chargeback was created by the channel. ISO 8601 with millisecond precision, in UTC, e.g. 2026-04-01T03:00:00.000Z expiryDateTime: type: string description: >- Evidence collection deadline. Evidence submitted after this time is rejected. ISO 8601 with millisecond precision, in UTC, e.g. 2026-04-01T03:00:00.000Z merchantUserId: type: string description: Merchant user id of the user who made the disputed payment subscriptionInfo: $ref: '#/components/schemas/ChargebackQueryResponse.SubscriptionInfo' description: >- The associated subscription info. Present when the chargeback is linked to a subscription payment order. ChargebackQueryResponse.SubscriptionInfo: type: object description: The associated subscription info properties: subscriptionId: type: string description: The associated Waffo subscription ID period: type: string description: Which period the subscription payment belong to. For example 2 merchantRequest: type: string description: >- Legacy alias of subscriptionRequest, carrying the same value. Retained for backward compatibility; new integrations should read subscriptionRequest subscriptionRequest: type: string description: >- Subscription request id sent from Merchant when the subscription was created. It is also used for the subscription idempotent check required: - merchantRequest - period - subscriptionId - subscriptionRequest ````