Increase Card Disputes API

openapi: 3.2.0
info:
  description: Anything that you can achieve with PDFs, presence, and persistence in a bank branch you can do with our API. We've always wanted a fully programmatic bank so we built one. Our API faithfully exposes the data and capabilities of the Federal Reserve, Visa, The Clearing House, depository networks, and accounting tools. It's lovingly boring and exceptionally powerful. If you have any questions or want to get started, don't hesitate to ping us at sales@increase.com. We can't wait to see what you build!
  title: Increase Card Disputes API
  version: 0.0.1
servers:
- url: https://api.increase.com
- url: https://sandbox.increase.com
security:
- bearerAuth: []
tags:
- description: If unauthorized activity occurs on a card, you can create a Card Dispute and we'll work with the card networks to return the funds if appropriate.
  name: Card Disputes
paths:
  /card_disputes:
    get:
      operationId: list_card_disputes
      parameters:
      - in: query
        name: cursor
        required: false
        schema:
          description: Return the page of entries after this one.
          type: string
          x-documentation-priority: low
      - in: query
        name: limit
        required: false
        schema:
          description: Limit the size of the list that is returned. The default (and maximum) is 100 objects.
          minimum: 1
          type: integer
          x-documentation-priority: low
      - in: query
        name: created_at.after
        required: false
        schema:
          description: Return results after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
          format: date-time
          type: string
          x-documentation-priority: low
      - in: query
        name: created_at.before
        required: false
        schema:
          description: Return results before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
          format: date-time
          type: string
          x-documentation-priority: low
      - in: query
        name: created_at.on_or_after
        required: false
        schema:
          description: Return results on or after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
          format: date-time
          type: string
          x-documentation-priority: low
      - in: query
        name: created_at.on_or_before
        required: false
        schema:
          description: Return results on or before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
          format: date-time
          type: string
          x-documentation-priority: low
      - in: query
        name: status.in
        required: false
        schema:
          description: Filter Card Disputes for those with the specified status or statuses. For GET requests, this should be encoded as a comma-delimited string, such as `?in=one,two,three`.
          items:
            enum:
            - user_submission_required
            - pending_user_submission_reviewing
            - pending_user_submission_submitting
            - pending_user_withdrawal_submitting
            - pending_response
            - lost
            - won
            type: string
            x-enum-descriptions:
            - A User Submission is required to continue with the Card Dispute.
            - The most recent User Submission is being reviewed.
            - The most recent User Submission is being submitted to the network.
            - The user's withdrawal of the Card Dispute is being submitted to the network.
            - The Card Dispute is pending a response from the network.
            - The Card Dispute has been lost and funds previously credited from the acceptance have been debited.
            - The Card Dispute has been won and no further action can be taken.
          type: array
          x-documentation-priority: default
        explode: false
      - in: query
        name: idempotency_key
        required: false
        schema:
          description: Filter records to the one with the specified `idempotency_key` you chose for that object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about [idempotency](https://increase.com/documentation/idempotency-keys).
          maxLength: 200
          minLength: 1
          type: string
          x-documentation-priority: default
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card_dispute_list'
          description: Card Dispute List
        4XX:
          $ref: '#/components/responses/errorResponse'
        5XX:
          $ref: '#/components/responses/errorResponse'
      summary: List Card Disputes
      x-sandbox-only: false
      x-tag: Card Disputes
      tags:
      - Card Disputes
    post:
      operationId: create_a_card_dispute
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_a_card_dispute_parameters'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card_dispute'
          description: Card Dispute
        4XX:
          $ref: '#/components/responses/errorResponse'
        5XX:
          $ref: '#/components/responses/errorResponse'
      summary: Create a Card Dispute
      x-sandbox-only: false
      x-tag: Card Disputes
      tags:
      - Card Disputes
  /card_disputes/{card_dispute_id}:
    get:
      operationId: retrieve_a_card_dispute
      parameters:
      - example: card_dispute_h9sc95nbl1cgltpp7men
        in: path
        name: card_dispute_id
        required: true
        schema:
          description: The identifier of the Card Dispute.
          type: string
          x-documentation-priority: default
          x-id-reference-to: Card Disputes
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card_dispute'
          description: Card Dispute
        4XX:
          $ref: '#/components/responses/errorResponse'
        5XX:
          $ref: '#/components/responses/errorResponse'
      summary: Retrieve a Card Dispute
      x-sandbox-only: false
      x-tag: Card Disputes
      tags:
      - Card Disputes
  /card_disputes/{card_dispute_id}/submit_user_submission:
    post:
      operationId: submit_a_user_submission_for_a_card_dispute
      parameters:
      - example: card_dispute_h9sc95nbl1cgltpp7men
        in: path
        name: card_dispute_id
        required: true
        schema:
          description: The identifier of the Card Dispute to submit a user submission for.
          type: string
          x-documentation-priority: default
          x-id-reference-to: Card Disputes
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/submit_a_user_submission_for_a_card_dispute_parameters'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card_dispute'
          description: Card Dispute
        4XX:
          $ref: '#/components/responses/errorResponse'
        5XX:
          $ref: '#/components/responses/errorResponse'
      summary: Submit a User Submission for a Card Dispute
      x-sandbox-only: false
      x-tag: Card Disputes
      tags:
      - Card Disputes
  /card_disputes/{card_dispute_id}/withdraw:
    post:
      operationId: withdraw_a_card_dispute
      parameters:
      - example: card_dispute_h9sc95nbl1cgltpp7men
        in: path
        name: card_dispute_id
        required: true
        schema:
          description: The identifier of the Card Dispute to withdraw.
          type: string
          x-documentation-priority: default
          x-id-reference-to: Card Disputes
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/withdraw_a_card_dispute_parameters'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card_dispute'
          description: Card Dispute
        4XX:
          $ref: '#/components/responses/errorResponse'
        5XX:
          $ref: '#/components/responses/errorResponse'
      summary: Withdraw a Card Dispute
      x-sandbox-only: false
      x-tag: Card Disputes
      tags:
      - Card Disputes
components:
  schemas:
    card_dispute_visa:
      additionalProperties: false
      properties:
        network_events:
          description: The network events for the Card Dispute.
          items:
            $ref: '#/components/schemas/card_dispute_visa_network_event'
          type: array
          x-documentation-priority: default
        required_user_submission_category:
          anyOf:
          - description: The category of the currently required user submission if the user wishes to proceed with the dispute. Present if and only if status is `user_submission_required`. Otherwise, this will be `nil`.
            enum:
            - chargeback
            - merchant_prearbitration_decline
            - user_prearbitration
            type: string
            x-documentation-priority: default
            x-enum-descriptions:
            - A Chargeback User Submission is required.
            - A Merchant Pre Arbitration Decline User Submission is required.
            - A User Initiated Pre Arbitration User Submission is required.
          - type: 'null'
        user_submissions:
          description: The user submissions for the Card Dispute.
          items:
            $ref: '#/components/schemas/card_dispute_visa_user_submission'
          type: array
          x-documentation-priority: default
      required:
      - network_events
      - required_user_submission_category
      - user_submissions
      title: Card Dispute Visa-specific details
      type: object
      x-event-categories:
      - card_dispute.created
      - card_dispute.updated
      x-stainless-empty-object: false
      x-title-plural: Card Dispute Visa-specific details
    card_dispute:
      additionalProperties: false
      description: If unauthorized activity occurs on a card, you can create a Card Dispute and we'll work with the card networks to return the funds if appropriate.
      example:
        amount: 1000
        card_id: card_oubs0hwk5rn6knuecxg2
        created_at: '2020-01-31T23:59:59Z'
        disputed_transaction_id: transaction_uyrp7fld2ium70oa7oi
        id: card_dispute_h9sc95nbl1cgltpp7men
        idempotency_key: null
        loss: null
        network: visa
        status: pending_response
        type: card_dispute
        user_submission_required_by: null
        visa:
          network_events: []
          required_user_submission_category: null
          user_submissions:
          - accepted_at: null
            amount: 1000
            attachment_files: []
            category: chargeback
            chargeback:
              authorization: null
              category: fraud
              consumer_canceled_merchandise: null
              consumer_canceled_recurring_transaction: null
              consumer_canceled_services: null
              consumer_counterfeit_merchandise: null
              consumer_credit_not_processed: null
              consumer_damaged_or_defective_merchandise: null
              consumer_merchandise_misrepresentation: null
              consumer_merchandise_not_as_described: null
              consumer_merchandise_not_received: null
              consumer_non_receipt_of_cash: null
              consumer_original_credit_transaction_not_accepted: null
              consumer_quality_merchandise: null
              consumer_quality_services: null
              consumer_services_misrepresentation: null
              consumer_services_not_as_described: null
              consumer_services_not_received: null
              fraud:
                fraud_type: lost
              processing_error: null
            created_at: '2020-01-31T23:59:59Z'
            explanation: null
            further_information_requested_at: null
            further_information_requested_reason: null
            status: pending_reviewing
            updated_at: '2020-01-31T23:59:59Z'
        win: null
        withdrawal: null
      properties:
        amount:
          description: The amount of the dispute.
          type: integer
          x-documentation-priority: default
        card_id:
          description: The Card that the Card Dispute is associated with.
          type: string
          x-documentation-priority: default
          x-id-reference-to: Cards
        created_at:
          description: The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the Card Dispute was created.
          format: date-time
          type: string
          x-documentation-priority: default
        disputed_transaction_id:
          description: The identifier of the Transaction that was disputed.
          type: string
          x-documentation-priority: default
          x-id-reference-to: Transactions
        id:
          description: The Card Dispute identifier.
          type: string
          x-documentation-priority: default
          x-id-reference-to: Card Disputes
        idempotency_key:
          anyOf:
          - description: The idempotency key you chose for this object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about [idempotency](https://increase.com/documentation/idempotency-keys).
            type: string
            x-documentation-priority: default
          - type: 'null'
        loss:
          anyOf:
          - additionalProperties: false
            description: If the Card Dispute's status is `lost`, this will contain details of the lost dispute.
            example:
              lost_at: '2020-01-31T23:59:59Z'
              reason: user_withdrawn
            properties:
              lost_at:
                description: The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the Card Dispute was lost.
                format: date-time
                type: string
                x-documentation-priority: default
              reason:
                description: The reason the Card Dispute was lost.
                enum:
                - user_withdrawn
                - loss
                type: string
                x-documentation-priority: default
                x-enum-descriptions:
                - The user withdrew the Card Dispute.
                - The Card Dispute was lost according to network rules.
            required:
            - lost_at
            - reason
            title: Card Dispute Card Dispute Loss
            type: object
            x-documentation-priority: default
            x-event-categories: []
            x-stainless-empty-object: false
            x-title-plural: Card Dispute Losses
          - type: 'null'
        network:
          description: The network that the Card Dispute is associated with.
          enum:
          - visa
          - pulse
          type: string
          x-documentation-priority: default
          x-enum-descriptions:
          - 'Visa: details will be under the `visa` object.'
          - 'Pulse: details will be under the `pulse` object.'
        status:
          description: The status of the Card Dispute.
          enum:
          - user_submission_required
          - pending_user_submission_reviewing
          - pending_user_submission_submitting
          - pending_user_withdrawal_submitting
          - pending_response
          - lost
          - won
          type: string
          x-documentation-priority: default
          x-enum-descriptions:
          - A User Submission is required to continue with the Card Dispute.
          - The most recent User Submission is being reviewed.
          - The most recent User Submission is being submitted to the network.
          - The user's withdrawal of the Card Dispute is being submitted to the network.
          - The Card Dispute is pending a response from the network.
          - The Card Dispute has been lost and funds previously credited from the acceptance have been debited.
          - The Card Dispute has been won and no further action can be taken.
        type:
          description: A constant representing the object's type. For this resource it will always be `card_dispute`.
          enum:
          - card_dispute
          type: string
          x-documentation-priority: default
        user_submission_required_by:
          anyOf:
          - description: The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the user submission is required by. Present only if status is `user_submission_required` and a user submission is required by a certain time. Otherwise, this will be `nil`.
            format: date-time
            type: string
            x-documentation-priority: default
          - type: 'null'
        visa:
          anyOf:
          - $ref: '#/components/schemas/card_dispute_visa'
            description: Card Dispute information for card payments processed over Visa's network. This field will be present in the JSON response if and only if `network` is equal to `visa`.
            x-documentation-priority: default
          - type: 'null'
        win:
          anyOf:
          - additionalProperties: false
            description: If the Card Dispute's status is `won`, this will contain details of the won dispute.
            example:
              won_at: '2020-01-31T23:59:59Z'
            properties:
              won_at:
                description: The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the Card Dispute was won.
                format: date-time
                type: string
                x-documentation-priority: default
            required:
            - won_at
            title: Card Dispute Card Dispute Win
            type: object
            x-documentation-priority: default
            x-event-categories: []
            x-stainless-empty-object: false
            x-title-plural: Card Dispute Wins
          - type: 'null'
        withdrawal:
          anyOf:
          - additionalProperties: false
            description: If the Card Dispute has been withdrawn, this will contain details of the withdrawal.
            example:
              explanation: The cardholder requested a withdrawal of the dispute.
            properties:
              explanation:
                anyOf:
                - description: The explanation for the withdrawal of the Card Dispute.
                  type: string
                  x-documentation-priority: default
                - type: 'null'
            required:
            - explanation
            title: Card Dispute Card Dispute Withdrawal
            type: object
            x-documentation-priority: default
            x-event-categories: []
            x-stainless-empty-object: false
            x-title-plural: Card Dispute Withdrawals
          - type: 'null'
      required:
      - type
      - id
      - amount
      - user_submission_required_by
      - status
      - created_at
      - disputed_transaction_id
      - network
      - loss
      - win
      - withdrawal
      - card_id
      - visa
      - idempotency_key
      title: Card Dispute
      type: object
      x-event-categories:
      - card_dispute.created
      - card_dispute.updated
      x-stainless-empty-object: false
      x-tag: Card Disputes
      x-title-plural: Card Disputes
    card_dispute_list:
      additionalProperties: true
      description: A list of Card Dispute objects.
      example:
        data:
        - amount: 1000
          card_id: card_oubs0hwk5rn6knuecxg2
          created_at: '2020-01-31T23:59:59Z'
          disputed_transaction_id: transaction_uyrp7fld2ium70oa7oi
          id: card_dispute_h9sc95nbl1cgltpp7men
          idempotency_key: null
          loss: null
          network: visa
          status: pending_response
          type: card_dispute
          user_submission_required_by: null
          visa:
            network_events: []
            required_user_submission_category: null
            user_submissions:
            - accepted_at: null
              amount: 1000
              attachment_files: []
              category: chargeback
              chargeback:
                authorization: null
                category: fraud
                consumer_canceled_merchandise: null
                consumer_canceled_recurring_transaction: null
                consumer_canceled_services: null
                consumer_counterfeit_merchandise: null
                consumer_credit_not_processed: null
                consumer_damaged_or_defective_merchandise: null
                consumer_merchandise_misrepresentation: null
                consumer_merchandise_not_as_described: null
                consumer_merchandise_not_received: null
                consumer_non_receipt_of_cash: null
                consumer_original_credit_transaction_not_accepted: null
                consumer_quality_merchandise: null
                consumer_quality_services: null
                consumer_services_misrepresentation: null
                consumer_services_not_as_described: null
                consumer_services_not_received: null
                fraud:
                  fraud_type: lost
                processing_error: null
              created_at: '2020-01-31T23:59:59Z'
              explanation: null
              further_information_requested_at: null
              further_information_requested_reason: null
              status: pending_reviewing
              updated_at: '2020-01-31T23:59:59Z'
          win: null
          withdrawal: null
        next_cursor: v57w5d
      properties:
        data:
          description: The contents of the list.
          items:
            $ref: '#/components/schemas/card_dispute'
          type: array
          x-documentation-priority: default
        next_cursor:
          anyOf:
          - description: A pointer to a place in the list. Pass this as the `cursor` parameter to retrieve the next page of results. If there are no more results, the value will be `null`.
            type: string
            x-documentation-priority: default
          - type: 'null'
      required:
      - data
      - next_cursor
      title: Card Dispute List
      type: object
      x-event-categories: []
      x-stainless-empty-object: false
      x-title-plural: Card Dispute Lists
    create_a_card_dispute_parameters:
      additionalProperties: true
      example:
        amount: 100
        disputed_transaction_id: transaction_uyrp7fld2ium70oa7oi
        network: visa
        visa:
          category: fraud
          fraud:
            fraud_type: account_or_credentials_takeover
      properties:
        amount:
          description: The monetary amount of the part of the transaction that is being disputed. This is optional and will default to the full amount of the transaction if not provided. If provided, the amount must be less than or equal to the amount of the transaction.
          minimum: 1
          type: integer
          x-documentation-priority: default
        attachment_files:
          description: The files to be attached to the initial dispute submission.
          items:
            additionalProperties: false
            properties:
              file_id:
                description: The ID of the file to be attached. The file must have a `purpose` of `card_dispute_attachment`.
                type: string
                x-documentation-priority: default
                x-id-reference-to: Files
            required:
            - file_id
            type: object
            x-event-categories: []
            x-stainless-empty-object: false
          type: array
          x-documentation-priority: default
        disputed_transaction_id:
          description: The Transaction you wish to dispute. This Transaction must have a `source_type` of `card_settlement`.
          type: string
          x-documentation-priority: default
          x-id-reference-to: Transactions
        explanation:
          description: The free-form explanation provided to Increase to provide more context for the user submission. This field is not sent directly to the card networks.
          maxLength: 200
          minLength: 1
          type: string
          x-documentation-priority: default
        network:
          description: The network of the disputed transaction. Details specific to the network are required under the sub-object with the same identifier as the network.
          enum:
          - visa
          type: string
          x-documentation-priority: default
          x-enum-descriptions:
          - Visa
        visa:
          additionalProperties: false
          description: The Visa-specific parameters for the dispute. Required if and only if `network` is `visa`.
          properties:
            authorization:
              additionalProperties: false
              description: Authorization. Required if and only if `category` is `authorization`.
              properties:
                account_status:
                  description: Account status.
                  enum:
                  - account_closed
                  - credit_problem
                  - fraud
                  type: string
                  x-documentation-priority: default
                  x-enum-descriptions:
                  - Account closed.
                  - Credit problem.
                  - Fraud.
              required:
              - account_status
              type: object
              x-documentation-priority: default
              x-event-categories: []
              x-stainless-empty-object: false
            category:
              description: Category.
              enum:
              - authorization
              - consumer_canceled_merchandise
              - consumer_canceled_recurring_transaction
              - consumer_canceled_services
              - consumer_counterfeit_merchandise
              - consumer_credit_not_processed
              - consumer_damaged_or_defective_merchandise
              - consumer_merchandise_misrepresentation
              - consumer_merchandise_not_as_described
              - consumer_merchandise_not_received
              - consumer_non_receipt_of_cash
              - consumer_original_credit_transaction_not_accepted
              - consumer_quality_merchandise
              - consumer_quality_services
              - consumer_services_misrepresentation
              - consumer_services_not_as_described
              - consumer_services_not_received
              - fraud
              - processing_error
              type: string
              x-documentation-priority: default
              x-enum-descriptions:
              - Authorization.
              - 'Consumer: canceled merchandise.'
              - 'Consumer: canceled recurring transaction.'
              - 'Consumer: canceled services.'
              - 'Consumer: counterfeit merchandise.'
              - 'Consumer: credit not processed.'
              - 'Consumer: damaged or defective merchandise.'
              - 'Consumer: merchandise misrepresentation.'
              - 'Consumer: merchandise not as described.'
              - 'Consumer: merchandise not received.'
              - 'Consumer: non-receipt of cash.'
              - 'Consumer: Original Credit Transaction (OCT) not accepted.'
              - 'Consumer: merchandise quality issue.'
              - 'Consumer: services quality issue.'
              - 'Consumer: services misrepresentation.'
              - 'Consumer: services not as described.'
              - 'Consumer: services not received.'
              - Fraud.
              - Processing error.
            consumer_canceled_merchandise:
              additionalProperties: false
              description: Canceled merchandise. Required if and only if `category` is `consumer_canceled_merchandise`.
              properties:
                cardholder_cancellation:
                  additionalProperties: false
                  description: Cardholder cancellation.
                  properties:
                    canceled_at:
                      description: Canceled at.
                      format: date
                      type: string
                      x-documentation-priority: default
                    canceled_prior_to_ship_date:
                      description: Canceled prior to ship date.
                      enum:
                      - canceled_prior_to_ship_date
                      - not_canceled_prior_to_ship_date
                      type: string
                      x-documentation-priority: default
                      x-enum-descriptions:
                      - Canceled prior to ship date.
                      - Not canceled prior to ship date.
                    cancellation_policy_provided:
                      description: Cancellation policy provided.
                      enum:
                      - not_provided
                      - provided
                      type: string
                      x-documentation-priority: default
                      x-enum-descriptions:
                      - Not provided.
                      - Provided.
                    reason:
                      description: Reason.
                      maxLength: 200
                      minLength: 1
                      type: string
                      x-documentation-priority: default
                  required:
                  - canceled_at
                  - canceled_prior_to_ship_date
                  - cancellation_policy_provided
                  - reason
                  type: object
                  x-documentation-priority: default
                  x-event-categories: []
                  x-stainless-empty-object: false
                merchant_resolution_attempted:
                  description: Merchant resolution attempted.
                  enum:
                  - attempted
                  - prohibited_by_local_law
                  type: string
                  x-documentation-priority: default
                  x-enum-descriptions:
                  - Attempted.
                  - Prohibited by local law.
                not_returned:
                  additionalProperties: false
                  description: Not returned. Required if and only if `return_outcome` is `not_returned`.
                  properties: {}
                  type: object
                  x-documentation-priority: default
                  x-event-categories: []
                  x-stainless-empty-object: true
                purchase_explanation:
                  description: Purchase explanation.
                  maxLength: 200
                  minLength: 1
                  type: string
                  x-documentation-priority: default
                received_or_expected_at:
                  description: Received or expected at.
                  format: date
                  type: string
                  x-documentation-priority: default
                return_attempted:
                  additionalProperties: false
                  description: Return attempted. Required if and only if `return_outcome` is `return_attempted`.
                  properties:
                    attempt_explanation:
                      description: Attempt explanation.
                      maxLength: 200
                      minLength: 1
                      type: string
                      x-documentation-priority: default
                    attempt_reason:
                      description: Attempt reason.
                      enum:
                      - merchant_not_responding
                      - no_return_authorization_provided
                      - no_return_instructions
                      - requested_not_to_return
                      - return_not_accepted
                      type: string
                      x-documentation-priority: default
                      x-enum-descriptions:
                      - Merchant not responding.
                   

# --- truncated at 32 KB (368 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/increase/refs/heads/main/openapi/increase-card-disputes-api-openapi.yml