--- title: "Create an Issuing dispute" method: POST path: "/issuing/disputes" tags: ["Issuing disputes"] --- # Create an Issuing dispute `POST /issuing/disputes` ## Request - Base URL: `https://{prefix}.api.sandbox.checkout.com` - URL: `https://{prefix}.api.sandbox.checkout.com/issuing/disputes` - 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

Create and submit an [Issuing dispute](https://www.checkout.com/docs/card-issuing/manage-cardholder-transactions/manage-issuing-disputes) for an Issuing transaction. The dispute is sent to the card scheme for processing. For full guidance, see [Manage Issuing disputes](https://www.checkout.com/docs/card-issuing/manage-cardholder-transactions/manage-issuing-disputes). The transaction must already be cleared and not refunded. ## Headers - `Cko-Idempotency-Key` string, required ## Request body - CreateDisputeRequest - `transaction_id` string, required: The transaction's unique identifier. - `reason` string, required: The four-digit scheme-specific [reason code](https://www.checkout.com/docs/developer-resources/codes/chargeback-codes#Mastercard) for the chargeback. Only provide this if Checkout.com is your issuing processor. Checkout.com does not validate this value. - `evidence` IssuingDisputeEvidence[]: Your evidence for raising the chargeback, in line with 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. - `amount` number: The chargeback amount, in the [minor unit](https://www.checkout.com/docs/payments/accept-payments/format-the-payment-amount) of the transaction currency.
If not provided, Checkout.com uses the full amount of the presentment. - `presentment_message_id` string: The message's unique Checkout.com identifier. - `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. - `justification` string: Your justification for changing the dispute reason. Allowed characters are: - Letters - Numbers - Spaces - The following special characters: `~!@#$%^&*()_+{}|:"<>?,./;'[]-=`. ## Response `200` Dispute already exists for this transaction/presentment - 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 - `201`: Dispute created successfully - `401`: Unauthorized Request - `406`: Not Acceptable - `415`: Unsupported Media Type - `422`: Dispute is ineligble - `429`: Too Many Requests --- [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)