--- title: "Amend an Issuing dispute" method: POST path: "/issuing/disputes/{disputeId}/amend" tags: ["Issuing disputes"] --- # Amend an Issuing dispute `POST /issuing/disputes/{disputeId}/amend` ## Request - Base URL: `https://{prefix}.api.sandbox.checkout.com` - URL: `https://{prefix}.api.sandbox.checkout.com/issuing/disputes/{disputeId}/amend` - Auth: OAuth 2 - Client credentials - Token URL: `string` scopes: `issuing:disputes-write` - TypeScript: (a function with typed inputs; its response is checked against the schema) Beta

Amend an [Issuing dispute](https://www.checkout.com/docs/card-issuing/manage-cardholder-transactions/manage-issuing-disputes) 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` string, required: The unique identifier for the Issuing dispute. ## Headers - `Cko-Idempotency-Key` string, required ## Request body - AmendDisputeRequest: 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` string: The updated four-digit scheme-specific [reason code](https://www.checkout.com/docs/developer-resources/codes/chargeback-codes#Mastercard). If a value is not provided, the existing reason code is retained. - `amount` number: The updated disputed amount, in the [minor unit](https://www.checkout.com/docs/payments/accept-payments/format-the-payment-amount) of the transaction currency. If not provided, the existing amount is retained. - `evidence` IssuingDisputeEvidence[]: The updated or additional evidence requested by the Dispute Resolution team. Follow the [card scheme's requirements](https://www.checkout.com/docs/card-issuing/manage-cardholder-transactions/manage-issuing-disputes#Evidence_file_requirements). - `name` string, required: The complete file name, including the extension. - `content` string, required: The base64-encoded string that represents a single JPG, PDF, TIFF, or ZIP file. ZIP files can contain multiple JPG, PDF, or TIFF files. - `description` string: A brief description of the evidence. - `fraud_details` IssuingDisputeFraudDetails: Fraud-related information required when the dispute reason code is fraud-related. - `fraud_type` 'card_lost' | 'card_stolen' | 'card_never_received' | 'fraudulent_account' | 'counterfeit_card' | 'account_takeover' | 'card_not_present_fraud' | 'merchant_misrepresentation' | 'cardholder_manipulation' | 'incorrect_processing' | 'other', required: The type of fraud the cardholder is asserting. This can be one of: - `card_lost`: The cardholder does not have the physical card and cannot explain how it was lost. - `card_stolen`: The cardholder does not have the physical card and provided an explanation as to how it was lost. For example, their wallet was stolen. - `card_never_received`: The card was issued and mailed but was not received by the cardholder. - `fraudulent_account`: The account was opened fraudulently using a stolen, fake, or synthetic identity. - `counterfeit_card`: The cardholder has their physical card but a duplicate or altered card was used in an unauthorized card-present transaction. - `account_takeover`: A fraudster gained control of the cardholder's account or credentials. For example, they may have changed the registered address, ordered a new card, or provisioned the card to a digital wallet. - `card_not_present_fraud`: The cardholder still has the card but the card details were used in an unauthorized card-not-present transaction. For example, it was used in an ecommerce transaction, or in a mail order/telephone order (MOTO) payment. - `merchant_misrepresentation`: The merchant deliberately misled the cardholder. For example, the goods provided were sub-standard, there were hidden charges, or the services advertised were fake. - `cardholder_manipulation`: The cardholder was tricked into authorizing the transaction themselves. For example, due to a scam, an impersonation, or authorized push payment (APP) fraud. - `incorrect_processing`: A security check failed and made fraudulent activity possible. For example, a card verification value (CVV) check was not performed, or the EMV cryptogram was not validated. - `other`: The confirmed fraud does not fit any of the other fraud type categories, or there were multiple fraud types applicable to the same transaction. - `description` string: A description of the fraud circumstances, for internal reference. This is not forwarded to the scheme. - `reason_change_justification` string: 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. Allowed characters are: - Letters - Numbers - Spaces - The following special characters: `~!@#$%^&*()_+{}|:"<>?,./;'[]-=`. - `action_response` string: Free-form text that you can use to explain your choices, provide additional context, or ask questions about the requested changes. ## Response `200` Your corrections were accepted; the dispute continues processing. - GetDisputeResponse: The client's dispute view. - `id` string: The unique identifier for the Issuing dispute. - `reason` string: The four-digit scheme-specific [reason code](https://www.checkout.com/docs/developer-resources/codes/chargeback-codes#Mastercard) you provide for the chargeback. - `disputed_amount` IssuingTransactionAmount - `amount` number: The amount is provided in the minor currency unit. - `currency` string, ISO4217: The issuing currency, as a three-letter ISO currency code. - `status` 'created' | 'canceled' | 'processing' | 'action_required' | 'won' | 'lost': The [dispute status](https://www.checkout.com/docs/developer-resources/codes/issuing-dispute-codes) 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_id` string: The transaction's unique identifier. - `presentment_message_id` string: The message's unique Checkout.com identifier. - `merchant` IssuingDisputeMerchant - `id` string: The merchant's identifier. This can vary from one acquirer to another. - `name` string: The merchant's name. - `city` string: The city where the merchant is located. - `state` string: The state where the merchant is located (US only). - `country_code` string: The two-digit [country code](https://www.checkout.com/docs/developer-resources/codes/country-codes) where the merchant is located. - `category_code` string: The merchant's [category code](https://www.checkout.com/docs/developer-resources/testing/codes/merchant-category-codes) for the disputed transaction. - `evidence` IssuingFileId[]: Any evidence submitted by the merchant during the dispute lifecycle. - `created_on` string, date-time: The date and time when the dispute was created, in UTC.
Format – ISO 8601 code
Example – `2025-01-31T10:20:30.456` - `modified_on` string, date-time: The date and time when the dispute was last modified, in UTC.
Format – ISO 8601 code
Example – `2025-01-31T10:20:30.456` - `action_details` IssuingDisputeActionDetails: Provides instructions on the amendments required before the dispute can proceed, if the dispute `status` is `action_required`. Use the Amend an Issuing dispute endpoint to submit your amendments. Use the correct endpoint to send your updates as requested. - `instructions` string: The amendments required before the dispute can proceed. For example, if you need to provide a reason code, or update the submitted evidence. - `last_action_response` string: Specifies whether the dispute was previously amended and an action response was provided. - `chargeback` IssuingDisputeChargeback: The dispute details at the chargeback stage. - `submitted_on` string, date-time: The date and time when the chargeback was successfully submitted to the card scheme, in UTC.
Format – ISO 8601 code
Example – `2025-01-31T10:20:30.456` - `reason` string: The four-digit scheme-specific [reason code](https://www.checkout.com/docs/developer-resources/codes/chargeback-codes#Mastercard) you provide for the chargeback. - `amount` IssuingTransactionAmount - `amount` number: The amount is provided in the minor currency unit. - `currency` string, ISO4217: The issuing currency, as a three-letter ISO currency code. - `evidence` object[]: Your evidence for the chargeback. - `file_id` string, required: The unique Checkout.com identifier for the uploaded file. - `description` string: A brief description of the evidence. - `justification` string: A brief description of why the dispute is being raised. This is forwarded to the scheme. - `representment` IssuingDisputeSecondPresentment: The information provided by the merchant when they reject the chargeback and send a representment. - `received_on` string, date-time: The date and time when you received the representment, in UTC.
Format – ISO 8601 code
Example – `2025-01-31T10:20:30.456` - `amount` IssuingTransactionAmount - `amount` number: The amount is provided in the minor currency unit. - `currency` string, ISO4217: The issuing currency, as a three-letter ISO currency code. - `evidence` object[]: The evidence provided by the merchant against the chargeback. - `file_id` string, required: The unique Checkout.com identifier for the uploaded file. - `description` string: A brief description of the evidence. - `pre_arbitration` IssuingDisputePreArbitration: The dispute details at the pre-arbitration stage. - `submitted_on` string, date-time: The date and time when the pre-arbitration was successfully escalated to the card scheme, in UTC.
Format – ISO 8601 code
Example – `2025-01-31T10:20:30.456` - `evidence` object[]: The evidence relating to the Issuing dispute provided at the pre-arbitration stage. - `file_id` string, required: The unique Checkout.com identifier for the uploaded file. - `description` string: A brief description of the evidence. - `amount` IssuingTransactionAmount - `amount` number: The amount is provided in the minor currency unit. - `currency` string, ISO4217: The issuing currency, as a three-letter ISO currency code. - `reason_change` IssuingDisputeReasonChange: The change to the dispute reason and your justification for changing it. - `reason` string, required: The updated four-digit scheme-specific [reason code](https://www.checkout.com/docs/developer-resources/codes/chargeback-codes) for the chargeback. - `justification` string, required: Your justification for changing the dispute reason. Allowed characters are: - Letters - Numbers - Spaces - The following special characters:
`~!@#$%^&*()_+{}|:"<>?,./;'[]-=`. - `justification` string: Your justification for escalating the dispute to pre-arbitration. - `merchant_responded_on` string, date-time: The date and time when the merchant provided evidence against the pre-arbitration, in UTC.
Format – ISO 8601 code
Example – `2025-01-31T10:20:30.456` - `merchant_evidence` object[] - `file_id` string, required: The unique Checkout.com identifier for the uploaded file. - `description` string: A brief description of the evidence. - `arbitration` IssuingDisputeArbitration: The dispute details during the arbitration stage. - `submitted_on` string, date-time: The date and time when the arbitration was successfully escalated to the card scheme, in UTC.
Format – ISO 8601 code
Example – `2025-01-31T10:20:30.456` - `amount` IssuingTransactionAmount - `amount` number: The amount is provided in the minor currency unit. - `currency` string, ISO4217: The issuing currency, as a three-letter ISO currency code. - `justification` string: Your justification for escalating the dispute to arbitration. - `decided_on` string, date-time: The date and time when the card scheme decided the arbitration case, in UTC.
Format – ISO 8601 code
Example – `2025-01-31T10:20:30.456` - `_links` object: The links related to the dispute. - `self` IssuingLink - `href` string, required: The link URL. - `actions` string[], required: The HTTP Methods that can be performed on the link. - `types` string[], required: The Content Types for the link to the resource - `card` IssuingLink - `href` string, required: The link URL. - `actions` string[], required: The HTTP Methods that can be performed on the link. - `types` string[], required: The Content Types for the link to the resource - `cardholder` IssuingLink - `href` string, required: The link URL. - `actions` string[], required: The HTTP Methods that can be performed on the link. - `types` string[], required: The Content Types for the link to the resource - `transaction` IssuingLink - `href` string, required: The link URL. - `actions` string[], required: The HTTP Methods that can be performed on the link. - `types` string[], required: The Content Types for the link to the resource - `amend` IssuingLink - `href` string, required: The link URL. - `actions` string[], required: The HTTP Methods that can be performed on the link. - `types` string[], required: The Content Types for the link to the resource - `escalate` IssuingLink - `href` string, required: The link URL. - `actions` string[], required: The HTTP Methods that can be performed on the link. - `types` string[], required: The Content Types for the link to the resource - `cancel` IssuingLink - `href` string, required: The link URL. - `actions` string[], required: The HTTP Methods that can be performed on the link. - `types` string[], required: The Content Types for the link to the resource ## Other responses - `401`: Unauthorized Request - `404`: Issuing dispute not found - `409`: This dispute is not in a state that accepts corrections (e.g. not action_required). - `422`: Request is missing required information — for example, `fraud_details` for a fraud reason code, or `reason_change_justification` when changing the reason code at the escalation stage. --- [API](https://skmtc.dev/checkout/apis/checkout-com-api-reference.md) - [All operations](https://skmtc.dev/checkout/apis/checkout-com-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/checkout/apis/checkout-com-api-reference/revisions/0f1abdb1c3e9?raw)