Checkout.com API logo

Issuing disputes

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.

SecurityOAuth2: OAuth
Request
header Parameters
Cko-Idempotency-Key
required
string [ 1 .. 256 ] characters ^[A-Za-z0-9._-]+$

An idempotency key for safely retrying requests.

Example: 7c1b9f96-4f2e-4b1a-bc2b-3d0f1a2e9f3a
Request Body schema: application/json
required
transaction_id
required
string (IssuingTransactionId) = 30 characters ^trx_[a-z0-9]{26}$

The transaction's unique identifier.

reason
required
string

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.

Array of objects (IssuingDisputeEvidence)

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

amount
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
string = 30 characters ^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.

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
string <= 100 characters

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

Responses
200

Dispute already exists for this transaction/presentment

201

Dispute created successfully

401

Unauthorized Request

406

Not Acceptable

415

Unsupported Media Type

422

Dispute is ineligble

429

Too Many Requests

post/issuing/disputes
Request samples
application/json
{
  • "transaction_id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
  • "reason": "4807",
  • "evidence": [
    ],
  • "amount": 100,
  • "presentment_message_id": "msg_fa6psq242dcd6fdn5gifcq1491",
  • "fraud_details": {
    },
  • "justification": "string"
}
Response samples
application/json
{
  • "id": "idsp_fa6psq242dcd6fdn5gifcq1491",
  • "reason": "4802",
  • "disputed_amount": {
    },
  • "status": "processing",
  • "status_reason": "chargeback_processed",
  • "transaction_id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
  • "presentment_message_id": "msg_fa6psq242dcd6fdn5gifcq1491",
  • "merchant": {
    },
  • "created_on": "2019-08-24T14:15:22Z",
  • "modified_on": "2019-08-24T14:15:22Z",
  • "action_details": {
    },
  • "chargeback": {
    },
  • "representment": {
    },
  • "pre_arbitration": {
    },
  • "arbitration": {
    },
  • "_links": {
    }
}

Get an Issuing dispute

Beta

Retrieve the details of an Issuing dispute.

SecurityOAuth2: OAuth
Request
path Parameters
disputeId
required
string (IssuingDisputeId) = 31 characters ^idsp_[a-z0-9]{26}$

The unique identifier for the Issuing dispute.

Example: idsp_fa6psq242dcd6fdn5gifcq1491
Responses
200

Issuing dispute retrieved successfully

401

Unauthorized Request

403

Forbidden

404

Issuing dispute not found

406

Not Acceptable

415

Unsupported Media Type

429

Too Many Requests

default

Issuing dispute response retrieved successfully

get/issuing/disputes/{disputeId}
Request samples 
Response samples 
application/json
{
  • "id": "idsp_fa6psq242dcd6fdn5gifcq1491",
  • "reason": "4802",
  • "disputed_amount": {
    },
  • "status": "processing",
  • "status_reason": "chargeback_processed",
  • "transaction_id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
  • "presentment_message_id": "msg_fa6psq242dcd6fdn5gifcq1491",
  • "merchant": {
    },
  • "created_on": "2019-08-24T14:15:22Z",
  • "modified_on": "2019-08-24T14:15:22Z",
  • "action_details": {
    },
  • "chargeback": {
    },
  • "representment": {
    },
  • "pre_arbitration": {
    },
  • "arbitration": {
    },
  • "_links": {
    }
}
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.


SecurityOAuth2: OAuth 
Request 
path Parameters
disputeId
required
string (IssuingDisputeId)   = 31 characters ^idsp_[a-z0-9]{26}$
The unique identifier for the Issuing dispute.


 
 Example:  idsp_fa6psq242dcd6fdn5gifcq1491
header Parameters
Cko-Idempotency-Key
required
string  [ 1 .. 256 ] characters ^[A-Za-z0-9._-]+$
An idempotency key for safely retrying requests.


 
 Example:  7c1b9f96-4f2e-4b1a-bc2b-3d0f1a2e9f3a
Request Body schema: application/json
optional
reason
string
The updated four-digit scheme-specific reason code.
If a value is not provided, the existing reason code is retained.


 
amount
number
The updated disputed amount, in the minor unit
of the transaction currency. If not provided, the existing amount is retained.


 
Array of objects (IssuingDisputeEvidence) 
The updated or additional evidence requested by the Dispute Resolution team.
Follow the card scheme's requirements.


 
object
Provides the fraud category, and additional context if available.


This field is required if reason specifies a fraud-related dispute.


 
reason_change_justification
string  <= 13000 characters 
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
string  <= 1000 characters 
Free-form text that you can use to explain your choices, provide additional context, or ask questions about the requested changes.


 
Responses 
200
Your corrections were accepted; the dispute continues processing.


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.


post/issuing/disputes/{disputeId}/amend
Request samples 
application/json
{
  • "reason": "4853",
  • "evidence": [
    ],
  • "action_response": "Updated reason to 4853 as requested. New evidence meets scheme requirements."
}
Response samples 
application/json
{
  • "id": "idsp_fa6psq242dcd6fdn5gifcq1491",
  • "reason": "4802",
  • "disputed_amount": {
    },
  • "status": "processing",
  • "status_reason": "chargeback_processed",
  • "transaction_id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
  • "presentment_message_id": "msg_fa6psq242dcd6fdn5gifcq1491",
  • "merchant": {
    },
  • "created_on": "2019-08-24T14:15:22Z",
  • "modified_on": "2019-08-24T14:15:22Z",
  • "action_details": {
    },
  • "chargeback": {
    },
  • "representment": {
    },
  • "pre_arbitration": {
    },
  • "arbitration": {
    },
  • "_links": {
    }
}
Cancel an Issuing dispute
Beta

Cancel an Issuing dispute.
If you decide not to proceed with a dispute, you can cancel it either:


    

  • While the dispute status is processing and status_reason is chargeback_pending or chargeback_processed
For more information, see Cancel a dispute.
    • 



SecurityOAuth2: OAuth 
Request 
path Parameters
disputeId
required
string (IssuingDisputeId)   = 31 characters ^idsp_[a-z0-9]{26}$
The unique identifier for the Issuing dispute.


 
 Example:  idsp_fa6psq242dcd6fdn5gifcq1491
header Parameters
Cko-Idempotency-Key
required
string  [ 1 .. 256 ] characters ^[A-Za-z0-9._-]+$
An idempotency key for safely retrying requests.


 
 Example:  7c1b9f96-4f2e-4b1a-bc2b-3d0f1a2e9f3a
Responses 
202
Issuing dispute cancellation requested successfully


401
Unauthorized Request


404
Issuing dispute not found


409
Issuing dispute cannot be canceled


422
Request missing required information


post/issuing/disputes/{disputeId}/cancel
Request samples 
Escalate an Issuing dispute
Beta

Escalate an Issuing dispute to pre-arbitration or arbitration.


SecurityOAuth2: OAuth 
Request 
path Parameters
disputeId
required
string (IssuingDisputeId)   = 31 characters ^idsp_[a-z0-9]{26}$
The unique identifier for the Issuing dispute.


 
 Example:  idsp_fa6psq242dcd6fdn5gifcq1491
header Parameters
Cko-Idempotency-Key
required
string  [ 1 .. 256 ] characters ^[A-Za-z0-9._-]+$
An idempotency key for safely retrying requests.


 
 Example:  7c1b9f96-4f2e-4b1a-bc2b-3d0f1a2e9f3a
Request Body schema: application/json
optional
justification
required
string  <= 13000 characters 
Justification for escalating the dispute.


 
Array of objects (IssuingDisputeEvidence) 
Your evidence for escalating the dispute, in line with the card scheme's requirements.
If the request goes to arbitration, the card scheme ignores any evidence you provide at this stage using this request.


 
amount
number
The updated disputed amount, in the minor unit of the representment currency.


 
object
The change to the dispute reason and your justification for changing it.


 
object
Provides fraud-related details.


 This field is required if the dispute has a fraud-related reason code at the escalation stage, or after a requested reason code change to a fraud code.


 
Responses 
202
Issuing dispute escalation requested successfully


401
Unauthorized Request


404
Issuing dispute not found


409
Issuing dispute cannot be escalated


422
Request missing required information


post/issuing/disputes/{disputeId}/escalate
Request samples 
application/json
{
  • "justification": "The cardholder maintains that the goods were not received.",
  • "amount": 100,
  • "reason_change": {
    },
  • "additional_evidence": [
    ]
}
Submit an Issuing disputeDeprecated
Beta

Use the Create an Issuing dispute endpoint instead to create and submit a dispute in a single step.


You can also use the Amend endpoint to submit changes if the dispute status is action_required.
This endpoint may still be used to re-submit after a rejected submission or to re-attempt an escalation; existing clients will receive advance communication when the new re-open flow is available.


SecurityOAuth2: OAuth 
Request 
path Parameters
disputeId
required
string (IssuingDisputeId)   = 31 characters ^idsp_[a-z0-9]{26}$
The unique identifier for the Issuing dispute.


 
 Example:  idsp_fa6psq242dcd6fdn5gifcq1491
header Parameters
Cko-Idempotency-Key
required
string  [ 1 .. 256 ] characters ^[A-Za-z0-9._-]+$
An idempotency key for safely retrying requests.


 
 Example:  7c1b9f96-4f2e-4b1a-bc2b-3d0f1a2e9f3a
Request Body schema: application/json
optional
reason
string
The updated four-digit scheme-specific reason code. 
If not provided, Checkout.com uses the existing reason code.


 
Array of objects (IssuingDisputeEvidence) 
Your evidence for the chargeback, if updated since you created the dispute.


 
amount
number
The updated disputed amount, in the minor unit of the transaction or representment currency.
If not provided, Checkout.com uses the existing disputed amount.


 
Responses 
200
Issuing dispute submitted successfully


401
Unauthorized Request


404
Issuing dispute not found


409
Issuing dispute cannot be submitted


422
Request missing required information


post/issuing/disputes/{disputeId}/submit
Request samples 
application/json
{
  • "reason": "4807",
  • "evidence": [
    ],
  • "amount": 100
}
Response samples 
application/json
{
  • "id": "idsp_fa6psq242dcd6fdn5gifcq1491",
  • "reason": "4802",
  • "disputed_amount": {
    },
  • "status": "processing",
  • "status_reason": "chargeback_processed",
  • "transaction_id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
  • "presentment_message_id": "msg_fa6psq242dcd6fdn5gifcq1491",
  • "merchant": {
    },
  • "created_on": "2019-08-24T14:15:22Z",
  • "modified_on": "2019-08-24T14:15:22Z",
  • "action_details": {
    },
  • "chargeback": {
    },
  • "representment": {
    },
  • "pre_arbitration": {
    },
  • "arbitration": {
    },
  • "_links": {
    }
}
➔ Next to Card testing