Checkout.com API logo

Issuing disputes

Create an Issuing dispute

Beta

Create a dispute for an Issuing transaction. For full guidance, see Manage Issuing disputes. The transaction must already be cleared and not refunded. For the card scheme to process the chargeback, you must submit the dispute using this endpoint.

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.

justification
string <= 100 characters

Your justification for the chargeback.

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",
  • "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",
  • "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",
  • "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:


    

  • Before you submit it
    • 

  • 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.


 
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": [
    ]
}
➔ Next to Card testing