Create an Issuing dispute

​

Beta

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.

Headers
  • Cko-Idempotency-Key
    Type: string
    min length:  
    1
    max length:  
    256    Pattern: ^[A-Za-z0-9._-]+$
    required

    An idempotency key for safely retrying requests.

Body·
required
application/json
  • transaction_id
    Type: string ·
    min length:  
    30
    max length:  
    30    Pattern: ^trx_[a-z0-9]{26}$
    required

    The transaction's unique identifier.

  • reason
    Type: string
    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.

  • evidence
    Type: array object[] ·

    Your evidence for raising the chargeback, in line with the card scheme's requirements.

  • amount
    Type: number

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

  • presentment_message_id
    Type: string ·
    min length:  
    30
    max length:  
    30    Pattern: ^msg_[a-z0-9]{26}$

    The unique identifier for the disputed presentment message.

    If the transaction has multiple presentments, you must provide this field to specify the presentment you want to dispute.

    If the transaction has only one presentment, you do not need to provide this field because Checkout.com uses that presentment automatically.

  • fraud_details
    Type: object ·

    Contains all fraud-related information to be sent with the chargeback.

    This field is required if the dispute has a fraud-related reason code.

  • justification
    Type: string
    max length:  
    100

    Short justification for raising this dispute, to be sent to the scheme.

Responses
  • application/json
  • application/json
  • 406

    Not Acceptable

  • 415

    Unsupported Media Type

  • application/json
  • 429

    Too Many Requests

Request Example for post/issuing/disputes
curl 'https://{prefix}.api.sandbox.checkout.com/issuing/disputes' \
  --request POST \
  --header 'Cko-Idempotency-Key: 7c1b9f96-4f2e-4b1a-bc2b-3d0f1a2e9f3a' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "transaction_id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
  "reason": "4807",
  "evidence": [
    {
      "name": "evidence.pdf",
      "content": "",
      "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."
  },
  "justification": ""
}'

{
  "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",
    "state": "",
    "country_code": "FR",
    "category_code": "5331",
    "evidence": [
      "file_6lbss42ezvoufcb2beo76rvwly"
    ]
  },
  "created_on": "2026-09-23T13:52:07.856Z",
  "modified_on": "2026-09-23T13:52:07.856Z",
  "action_details": {
    "instructions": "string",
    "last_action_response": "string"
  },
  "chargeback": {
    "submitted_on": "2025-09-10T10:11:12Z",
    "reason": "4802",
    "amount": {
      "amount": 100,
      "currency": "USD"
    },
    "evidence": [
      {
        "file_id": "file_6lbss42ezvoufcb2beo76rvwly",
        "description": "Goods were not received."
      }
    ],
    "justification": "string"
  },
  "representment": {
    "received_on": "2026-09-23T13:52:07.856Z",
    "amount": {
      "amount": 100,
      "currency": "USD"
    },
    "evidence": [
      {
        "file_id": "file_6lbss42ezvoufcb2beo76rvwly",
        "description": "Goods were not received."
      }
    ]
  },
  "pre_arbitration": {
    "submitted_on": "2025-09-10T10:11:12Z",
    "evidence": [
      {
        "file_id": "file_6lbss42ezvoufcb2beo76rvwly",
        "description": "Goods were not received."
      }
    ],
    "amount": {
      "amount": 100,
      "currency": "USD"
    },
    "reason_change": {
      "reason": "4807",
      "justification": "string"
    },
    "justification": "string",
    "merchant_responded_on": "2026-09-23T13:52:07.856Z",
    "merchant_evidence": [
      {
        "file_id": "file_6lbss42ezvoufcb2beo76rvwly",
        "description": "Goods were not received."
      }
    ]
  },
  "arbitration": {
    "submitted_on": "2025-09-10T10:11:12Z",
    "amount": {
      "amount": 100,
      "currency": "USD"
    },
    "justification": "string",
    "decided_on": "2025-01-31T10:20:30Z"
  },
  "_links": {
    "self": {
      "href": "string",
      "actions": [
        "GET"
      ],
      "types": [
        "string"
      ]
    },
    "card": {
      "href": "string",
      "actions": [
        "GET"
      ],
      "types": [
        "string"
      ]
    },
    "cardholder": {
      "href": "string",
      "actions": [
        "GET"
      ],
      "types": [
        "string"
      ]
    },
    "transaction": {
      "href": "string",
      "actions": [
        "GET"
      ],
      "types": [
        "string"
      ]
    },
    "amend": {
      "href": "string",
      "actions": [
        "GET"
      ],
      "types": [
        "string"
      ]
    },
    "escalate": {
      "href": "string",
      "actions": [
        "GET"
      ],
      "types": [
        "string"
      ]
    },
    "cancel": {
      "href": "string",
      "actions": [
        "GET"
      ],
      "types": [
        "string"
      ]
    }
  }
}

Dispute already exists for this transaction/presentment