CHcheckout
Issuing disputes

Create an Issuing dispute

<span style="font-size: 12px; font-weight: 500; color: rgb(0, 0, 0); background-color: rgb(255, 176, 97); border-radius: 4px; padding: 2px 6px" >Beta</span><p></p> Create and submit an Issuing dispute for an Issuing transaction. The dispute is sent to the card scheme for processing. For full guidance, see Manage Issuing disputes. The transaction must already be cleared and not refunded.

post/issuing/disputes

Request

Headers

Cko-Idempotency-Keystring required

An idempotency key for safely retrying requests.

Request body

transaction_idstring required

The transaction's unique identifier.

reasonstring required

The four-digit scheme-specific reason code for the chargeback. Only provide this if Checkout.com is your issuing processor. Checkout.com does not validate this value.

amountnumber

The chargeback amount, in the minor unit of the transaction currency. <br/> If not provided, Checkout.com uses the full amount of the presentment.

presentment_message_idstring

The message's unique Checkout.com identifier.

justificationstring

Your justification for changing the dispute reason.

Allowed characters are:

  • Letters
  • Numbers
  • Spaces
  • The following special characters: ~!@#$%^&*()_+{}|:"<>?,./;'[]-=.

Example request

{
  "transaction_id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
  "reason": "4807",
  "evidence": [
    {
      "name": "evidence.pdf",
      "description": "Goods were not received."
    }
  ],
  "amount": 100,
  "presentment_message_id": "msg_fa6psq242dcd6fdn5gifcq1491",
  "fraud_details": {
    "fraud_type": "card_not_present_fraud",
    "description": "Cardholder confirmed they made no online purchases on this date."
  }
}

Response

Dispute already exists for this transaction/presentment

idstring

The unique identifier for the Issuing dispute.

reasonstring

The four-digit scheme-specific reason code you provide for the chargeback.

status'created' | 'canceled' | 'processing' | 'action_required' | 'won' | 'lost'

The dispute status as returned to the client.

status_reason'' | 'expired' | 'chargeback_pending' | 'chargeback_change_requested' | 'chargeback_evidence_invalid_or_insufficient' | 'chargeback_processed' | 'chargeback_rejected' | 'chargeback_reversal_pending' | 'chargeback_reversed' | 'chargeback_response_accepted' | 'prearbitration_pending' | 'escalation_change_requested' | 'prearbitration_evidence_invalid_or_insufficient' | 'prearbitration_processed' | 'prearbitration_rejected' | 'prearbitration_reversal_pending' | 'prearbitration_reversed' | 'prearbitration_response_accepted' | 'arbitration_pending' | 'arbitration_processed' | 'presentment_reversed'

The status reason as returned to the client. An empty string indicates no status reason currently applies.

transaction_idstring

The transaction's unique identifier.

presentment_message_idstring

The message's unique Checkout.com identifier.

created_onstring date-time

The date and time when the dispute was created, in UTC. <br/>Format – ISO 8601 code <br/>Example – 2025-01-31T10:20:30.456

modified_onstring date-time

The date and time when the dispute was last modified, in UTC. <br/>Format – ISO 8601 code <br/>Example – 2025-01-31T10:20:30.456

Example response

{
  "id": "idsp_fa6psq242dcd6fdn5gifcq1491",
  "reason": "4802",
  "disputed_amount": {
    "amount": 100,
    "currency": "USD"
  },
  "status": "processing",
  "status_reason": "chargeback_processed",
  "transaction_id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
  "presentment_message_id": "msg_fa6psq242dcd6fdn5gifcq1491",
  "merchant": {
    "id": "(*)123456789",
    "name": "Software Company",
    "city": "Paris",
    "country_code": "FR",
    "category_code": "5331",
    "evidence": [
      "file_6lbss42ezvoufcb2beo76rvwly"
    ]
  },
  "chargeback": {
    "submitted_on": "2025-09-10T10:11:12.0000000+00:00",
    "reason": "4802",
    "amount": {
      "amount": 100,
      "currency": "USD"
    },
    "evidence": [
      {
        "file_id": "file_6lbss42ezvoufcb2beo76rvwly",
        "description": "Goods were not received."
      }
    ]
  },
  "representment": {
    "amount": {
      "amount": 100,
      "currency": "USD"
    },
    "evidence": [
      {
        "file_id": "file_6lbss42ezvoufcb2beo76rvwly",
        "description": "Goods were not received."
      }
    ]
  },
  "pre_arbitration": {
    "submitted_on": "2025-09-10T10:11:12.0000000+00:00",
    "evidence": [
      {
        "file_id": "file_6lbss42ezvoufcb2beo76rvwly",
        "description": "Goods were not received."
      }
    ],
    "amount": {
      "amount": 100,
      "currency": "USD"
    },
    "reason_change": {
      "reason": "4807"
    },
    "merchant_evidence": [
      {
        "file_id": "file_6lbss42ezvoufcb2beo76rvwly",
        "description": "Goods were not received."
      }
    ]
  },
  "arbitration": {
    "submitted_on": "2025-09-10T10:11:12.0000000+00:00",
    "amount": {
      "amount": 100,
      "currency": "USD"
    },
    "decided_on": "2025-01-31T10:20:30.0000000+00:00"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.