Breeze.cash Disputes API

openapi: 3.2.0
info:
  title: Breeze Disputes API
  version: 1.0.0
  description: Breeze payment processing API
  contact:
    email: support@breeze.cash
    url: https://docs.breeze.cash
servers:
- url: https://api.breeze.cash
  description: Breeze API
- url: https://secure.breeze.cash
  description: Breeze Direct Payment API (production)
- url: https://secure-sandbox.breeze.cash
  description: Breeze Direct Payment API (sandbox)
security:
- basicAuth: []
tags:
- name: Disputes
paths:
  /v1/disputes:
    get:
      operationId: listDisputes
      tags:
      - Disputes
      summary: List disputes
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - SUCCEEDED
                  data:
                    $ref: '#/components/schemas/ListDisputesResponse'
                required:
                - status
                - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - received
          - evidence_required
          - evidence_submitted
          - evidence_under_review
          - evidence_acknowledged_by_scheme
          - arbitration_sent_to_scheme
          - expired
          - accepted
          - arbitration_lost
          - lost
          - resolved
          - canceled
          - won
          - arbitration_won
      - name: email
        in: query
        required: false
        schema:
          type: string
      - name: dateRange
        in: query
        required: false
        schema:
          type: object
          properties:
            start:
              type: number
            end:
              type: number
          required:
          - start
          - end
          additionalProperties: false
      - name: pagination
        in: query
        required: false
        schema:
          type: object
          properties:
            offset:
              type: string
            limit:
              type: string
          required:
          - offset
          - limit
          additionalProperties: false
          deprecated: Use {@link CursorBasedPagination }  instead for performance reasons
  /v1/sandbox/disputes:
    post:
      operationId: simulateSandboxDispute
      tags:
      - Disputes
      summary: Simulate a chargeback (sandbox)
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: The simulated dispute
                properties:
                  status:
                    type: string
                    enum:
                    - SUCCEEDED
                  data:
                    $ref: '#/components/schemas/SimulateSandboxDisputeResponse'
                required:
                - status
                - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      description: Creates a simulated Visa chargeback with reason code 10.4 (fraud) on one of your sandbox payment pages. Only sandbox merchants can call this endpoint, and each payment can carry at most one dispute. The dispute appears in `GET /v1/disputes` and triggers the `DISPUTE_STATUS_UPDATE` webhook if you have it enabled.
      x-required-permissions:
      - sandbox.write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulateSandboxDisputeRequest'
components:
  schemas:
    SimulateSandboxDisputeResponse:
      type: object
      properties:
        disputeId:
          type: string
          description: ID of the simulated dispute
        paymentId:
          type: string
          description: ID of the disputed payment
      required:
      - disputeId
      - paymentId
    SimulateSandboxDisputeRequest:
      type: object
      description: The sandbox payment page to raise the simulated chargeback on
      properties:
        pageId:
          type: string
          description: ID of a sandbox payment page with a completed payment
      required:
      - pageId
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - FAILED
        errorCode:
          type: string
        errorMessage:
          type: string
      required:
      - status
      - errorCode
      - errorMessage
    ListDisputesResponse:
      description: List of disputes
      $schema: http://json-schema.org/draft-07/schema#
      type: object
      properties:
        disputes:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              createdAt:
                type: number
              updatedAt:
                type: number
              email:
                type: string
              livemode:
                type: boolean
              sourceUpdatedAt:
                type: number
              paymentPageId:
                type: string
              status:
                type: string
                enum:
                - received
                - evidence_required
                - evidence_submitted
                - evidence_under_review
                - evidence_acknowledged_by_scheme
                - arbitration_sent_to_scheme
                - expired
                - accepted
                - arbitration_lost
                - lost
                - resolved
                - canceled
                - won
                - arbitration_won
            required:
            - id
            - createdAt
            - updatedAt
            - email
            - livemode
            - sourceUpdatedAt
            - paymentPageId
        count:
          type: number
      required:
      - disputes
      - count
      definitions: {}
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: API key as username, empty password
x-provenance:
  method: searched
  source: https://docs.breeze.com/reference
  harvested: '2026-10-28'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.breeze.com/reference/cancelofframprequest.md
  - https://docs.breeze.com/reference/cancelpayoutpage.md
  - https://docs.breeze.com/reference/cancelsubscription.md
  - https://docs.breeze.com/reference/createcustomer.md
  - https://docs.breeze.com/reference/creategatewaypayment.md
  - https://docs.breeze.com/reference/createheadlesspayout.md
  - https://docs.breeze.com/reference/createliquidationaddress.md
  - https://docs.breeze.com/reference/createofframprequest.md
  - https://docs.breeze.com/reference/createpaymentpage.md
  - https://docs.breeze.com/reference/createpayoutpage.md
  - https://docs.breeze.com/reference/createproduct.md
  - https://docs.breeze.com/reference/createproductprice.md
  - https://docs.breeze.com/reference/createsubscription.md
  - https://docs.breeze.com/reference/deletegatewaycustomerpaymentmethod.md
  - https://docs.breeze.com/reference/downloadstatement.md
  - https://docs.breeze.com/reference/expirepaymentpage.md
  - https://docs.breeze.com/reference/getallpaymentattempts.md
  - https://docs.breeze.com/reference/getcustomerbyid.md
  - https://docs.breeze.com/reference/getcustomerbyquery.md
  - https://docs.breeze.com/reference/getfraudreport.md
  - https://docs.breeze.com/reference/getgatewaypayment.md
  - https://docs.breeze.com/reference/getheadlesskycbycustomerreferenceid.md
  - https://docs.breeze.com/reference/getheadlesskycbyid.md
  - https://docs.breeze.com/reference/getinvoice.md
  - https://docs.breeze.com/reference/getliquidationaddress.md
  - https://docs.breeze.com/reference/getliquidationaddresstransaction.md
  - https://docs.breeze.com/reference/getmerchanttaxrate.md
  - https://docs.breeze.com/reference/getofframprequest.md
  - https://docs.breeze.com/reference/getpaymentpage.md
  - https://docs.breeze.com/reference/getpayoutpage.md
  - https://docs.breeze.com/reference/getpayoutpagehistory.md
  - https://docs.breeze.com/reference/getproduct.md
  - https://docs.breeze.com/reference/getrefund.md
  - https://docs.breeze.com/reference/getriskstatus.md
  - https://docs.breeze.com/reference/getsubscription.md
  - https://docs.breeze.com/reference/getsubscriptionbyclientreferenceid.md
  - https://docs.breeze.com/reference/initiateheadlesskyctier3.md
  - https://docs.breeze.com/reference/initiaterefund.md
  - https://docs.breeze.com/reference/listdisputes.md
  - https://docs.breeze.com/reference/listfraudreports.md
  - https://docs.breeze.com/reference/listgatewaycustomerpaymentmethods.md
  - https://docs.breeze.com/reference/listliquidationaddresses.md
  - https://docs.breeze.com/reference/listliquidationaddresstransactions.md
  - https://docs.breeze.com/reference/listpaymentpages.md
  - https://docs.breeze.com/reference/listproducts.md
  - https://docs.breeze.com/reference/liststatements.md
  - https://docs.breeze.com/reference/listsubscriptions.md
  - https://docs.breeze.com/reference/offboardcustomer.md
  - https://docs.breeze.com/reference/releaseofframprequest.md
  - https://docs.breeze.com/reference/releasepayoutpage.md
  - https://docs.breeze.com/reference/resumegatewaypaymentauthentication.md
  - https://docs.breeze.com/reference/sandboxconfirmpayoutpage.md
  - https://docs.breeze.com/reference/simulatesandboxdispute.md
  - https://docs.breeze.com/reference/submitheadlesskycproofofaddresswithupload.md
  - https://docs.breeze.com/reference/submitheadlesskycproofofaddresswithurl.md
  - https://docs.breeze.com/reference/submitheadlesskycwithimageupload.md
  - https://docs.breeze.com/reference/submitheadlesskycwithimageurl.md
  - https://docs.breeze.com/reference/updatecustomer.md
  merge:
    pages: 58
    deduped: 458
    conflicts_kept_first: 0