Amend an Issuing dispute

Beta

Amend an Issuing dispute that has been blocked from proceeding. This endpoint is used when the dispute's submission could not go through — either because the DR team requested changes before sending to the card scheme, or because the card scheme returned the submission for a fixable reason (in which case the DR team reviews the rejection and instructs the consumer via action_details).

This endpoint is only applicable when status is action_required and the status_reason is one of chargeback_change_requested, chargeback_evidence_invalid_or_insufficient, escalation_change_requested,prearbitration_evidence_invalid_or_insufficient. The _links.amend link in the GET response is present whenever an amendment is required.

Check action_details.instructions in GET /issuing/disputes/{id} for the specific changes required before calling this endpoint.

Chargeback stage (`status_reason: chargeback_change_requested`, `chargeback_evidence_invalid_or_insufficient`)

Address changes required before the chargeback can proceed. This covers two scenarios:

issuing rejection: The Disputes Resolution team reviews the submission and rejects providing corrective instructions via action_details.
Scheme rejection: The card scheme returned the chargeback for a fixable reason.

Escalation stage (`status_reason: escalation_change_requested`, `prearbitration_evidence_invalid_or_insufficient`)

Address changes required before the escalation (pre-arbitration or arbitration) can proceed. The same two scenarios apply as at the chargeback stage. reason_change_justification is required when changing the reason at this stage.

Path Parameters

disputeId
Type: string ·
min length:
31
max length:
31Pattern: ^idsp_[a-z0-9]{26}$
required

The unique identifier for the Issuing dispute.

Headers

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

An idempotency key for safely retrying requests.

Body·

application/json

Submit an amendment to a dispute that is currently blocked from proceeding. This endpoint handles both chargeback-stage and escalation-stage amendments using the same flat payload as the server determines the context from the dispute's current state.

Refer to the action_details returned in the Get issuing dispute endpoint to view the instructions provided by the Dispute Resolution team and the deadline by which you must submit amendments.

If reason specifies a fraud-related dispute, you must provide fraud_details. If you change the reason at the escalation stage, you must provide reason_change_justification.

reason
Type: string

The updated four-digit scheme-specific reason code. If a value is not provided, the existing reason code is retained.
amount
Type: number

The updated disputed amount, in the minor unit of the transaction currency. If not provided, the existing amount is retained.
evidence
Type: array object[] ·

The updated or additional evidence requested by the Dispute Resolution team. Follow the card scheme's requirements.
fraud_details
Type: object ·

Provides the fraud category, and additional context if available.

This field is required if reason specifies a fraud-related dispute.
reason_change_justification
Type: string
max length:
13000

Explains the justification for the reason change. This is shared with the Dispute Resolution review team and may be submitted to the card scheme. This field is required if you change the reason at the escalation stage.
action_response
Type: string
max length:
1000

Free-form text that you can use to explain your choices, provide additional context, or ask questions about the requested changes.

Responses

application/json

post/issuing/disputes/{disputeId}/amend

curl 'https://{prefix}.api.sandbox.checkout.com/issuing/disputes/idsp_fa6psq242dcd6fdn5gifcq1491/amend' \
  --request POST \
  --header 'Cko-Idempotency-Key: 7c1b9f96-4f2e-4b1a-bc2b-3d0f1a2e9f3a' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "reason": "4853",
  "evidence": [
    {
      "name": "cardholder_signed_declaration.pdf",
      "content": "JVBERi0xLjQKJeLjz9M...",
      "description": "Signed cardholder declaration as requested by DR team."
    }
  ],
  "action_response": "Updated reason to 4853 as requested. New evidence meets scheme requirements."
}'

Show Schema

{
  "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"
      ]
    }
  }
}

Your corrections were accepted; the dispute continues processing.