Card Disputes

An unavoidable part of running a card issuing program is the need to handle occasional disputes between a merchant and a cardholder about a transaction. Dispute processes are essentially conversations between cardholders and merchants mediated by the network until the cardholder eventually wins or loses the dispute. Most of the complexity of disputes arises from the fact that different dispute types require different required information and rules throughout such a conversation. To help you build a great dispute experience for your cardholders by providing the best possible evidence, Increase’s Card Disputes API fully models these rules for each dispute category the card networks expose.

Starting a Card Dispute

To start a Card Dispute with Increase, you make a POST /card_disputes call with the disputed transaction, the amount you want to dispute, and other required details including any attachments you have as evidence backing your dispute. For example, to start a Card Dispute for a transaction processed with Visa in a case where services weren’t received as promised:

curl -X POST https://api.increase.com/card_disputes
  -d $'{
    "amount": 20000,
    "disputed_transaction_id": "transaction_uyrp7fld2ium70oa7oi",
    "network": "visa",
    "visa": {
      "category": "consumer_services_not_received",
      "consumer_services_not_received": {
        "cancellation_outcome": "merchant_cancellation",
        "last_expected_receipt_at": "2025-11-05",
        "merchant_cancellation": {
          "canceled_at": "2025-11-08"
        },
        "purchase_info_and_explanation": "Contractor was supposed to perform job, then cancelled three days after without refunding"
      }
    }
  }'

200 OK
{
  "id": "card_dispute_h9sc95nbl1cgltpp7men",
  "status": "pending_user_submission_reviewing",
  "visa": {
    "network_events": [],
    "required_user_submission_category": null,
    "user_submissions": [
      {
        "category": "chargeback",
        "chargeback": {
          "category": "consumer_services_not_received",
          "consumer_services_not_received": {
            "cancellation_outcome": "merchant_cancellation",
            "last_expected_receipt_at": "2025-11-05",
            "merchant_cancellation": {
              "canceled_at": "2025-11-08"
            },
            "purchase_info_and_explanation": "Contractor was supposed to perform job, then cancelled three days after without refunding"
          }
        },
        "status": "pending_reviewing",
        // ...
      }
    ]
  },
  // ...
}

Note: card networks generally require the cardholder and merchant to attempt to resolve any dispute between themselves before escalating to starting a Card Dispute. To present the strongest case possible, make sure the cardholder made a reasonable effort to resolve the issue first.

Our API refers to this cardholder-provided evidence as a User Submission. Increase then submits the User Submission to the merchant via the card network. The merchant will then have an opportunity to reply. Our API refers to these replies as Network Events. After they reply, you can then provide the cardholder’s response (as a second User Submission), and this conversation continues back and forth like this until the dispute is won or lost.

Lifecycle of a Card Dispute

User Submissions

To ensure the greatest chance of winning a Dispute, Increase reviews each User Submission before sending it to the merchant via the card network. If further information is needed before submission, such as, say, a copy of a receipt, Increase will request this before continuing with the dispute process.

User Submissions are created when a Card Dispute is first created with POST /card_disputes and when subsequent User Submissions are submitted with POST /card_disputes/:card_dispute_id/submit_user_submission.

User Submissions are card network specific. See for example the API reference for the various User Submissions that can be made for a Visa dispute and the Visa disputes section for more details about when these are used.

User Submission categories

As a dispute progresses, different categories of User Submissions are required. When a Card Dispute is in the user_submission_required status, the category of User Submission required can be determined from the required_user_submission_category property of the network-specific sub-object of the Card Dispute, such as visa.required_user_submission_category.

If Increase requests further information for a User Submission, you should rely on the further_information_requested_reason property of the most recent User Submission to determine the information needed. In this scenario, the category of submission requested from the user will be the exact same as the submission for which information was requested.

User Submission deadlines

Every step of a dispute has a required deadline (enforced by the card network) for when a response from the next party is due. When it’s the cardholder’s turn to reply, this deadline will be populated in the user_submission_required_by property of the Card Dispute. If you do not submit an approved User Submission by the deadline, the cardholder automatically loses the dispute. Note that the merchant may also miss a deadline, in which case the cardholder automatically wins the dispute.

You can also always withdraw an active Card Dispute for a cardholder (causing it to be lost) by calling POST /card_disputes/:card_dispute_id/withdraw.

Network Events

Network Events represent card network level activity by either the cardholder, the merchant or the network itself due to deadlines. These will contain details of the merchant’s response.

Network Events are card network specific. See for example the API reference for the various Network Events that can occur for a Visa dispute and the Visa disputes section for more details about when these are used.

Putting it all together, a typical dispute flow looks like this:

1. User submits a Card Dispute with the initial User Submission by calling POST /card_disputes, which starts out with the status pending_user_submission_reviewing.
2. Increase reviews the User Submission and either accepts the submission (pending_user_submission_submitting), or requests further information from the user (user_submission_required).
   1. The user submits a new User Submission for the Card Dispute with the additional information requested by Increase by calling POST /card_disputes/:card_dispute_id/submit_user_submission, and Increase reviews this new submission as in step 2.
3. Increase submits the submission to the card network, and adds the submission as a Network Event to the Card Dispute. The status is now pending_response, pending response from the network.
4. Once a response comes back from the network, it is added as a Network Event on the Card Dispute.
   1. If the Network Event means that a dispute was either lost or won, Increase will transition the Card Dispute to the appropriate status (lost or won).
   2. If the Network Event needs a response from the user, the Card Dispute transitions back to the pending_user_submission_reviewing status and the process continues from step 2 onwards again. The user relies on the most recent Network Event for details about the merchant’s response, such as any explanation or evidence they may have provided. The user must provide a User Submission in response and have it accepted by a specific deadline.

Dispute Financial Transactions

As a Dispute progresses, money will move as result. When exactly money moves depends on the network and card type. For example, for a Visa credit card transaction, money will immediately be credited to the cardholder when a dispute is submitted to the network. If the merchant responds in disagreement, money will be debited from the cardholder until the next submission from the user is made.

These money movements are represented by Dispute Financial transactions. If a given Network Event has caused money movement, a Dispute Financial transaction will be present by reference in the dispute_financial_transaction_id property on the Network Event.

Example dispute types

Visa broadly categorizes their dispute processes into two types:

• Allocation. This is when a payment was not initiated by a cardholder at all, such as in cases of fraud or unauthorized card-on-file transactions.
• Collaboration. Used for all other disputes such as processing errors and consumer disputes, which are a broad category of dispute related to the merchandise or service rather than the payment itself.

Both processes start by submitting a Card Dispute with chargeback information using POST /card_disputes, but the Network Events and subsequent User Submission categories depend on the process.

The Allocation dispute process

In this process, the cardholder is effectively assumed right from the onset. If the merchant does not agree with the dispute, they must initiate “pre-arbitration”, which has higher fees and evidence requirements.

The flow of User Submissions and Network Events for an Allocation dispute is as follows, ignoring the User Submission review flow with Increase:

See the API reference for more details about the individual Network Events and User Submissions.

The Collaboration dispute process

In this process, the merchant is given the opportunity to fully or partially disagree with the cardholder’s dispute without escalating to pre-arbitration by re-presenting the transaction along with evidence. If the cardholder still disagrees with the merchant at this point, they can initiate pre-arbitration.

The flow of User Submissions and Network Events for a Collaboration dispute is as follows, ignoring the User Submission review flow with Increase:

See the API reference for more details about the individual Network Events and User Submissions.