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.Pattern: ^[A-Za-z0-9._-]+$An idempotency key for safely retrying requests.
Pattern: ^trx_[a-z0-9]{26}$The transaction's unique identifier.
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.
Your evidence for raising the chargeback, in line with the card scheme's requirements.
The chargeback amount, in the minor unit of the transaction currency.
If not provided, Checkout.com uses the full amount of the presentment.
Pattern: ^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.
Contains all fraud-related information to be sent with the chargeback.
This field is required if the dispute has a fraud-related reason code.
Short justification for raising this dispute, to be sent to the scheme.
Not Acceptable
Unsupported Media Type
Too Many Requests
curl 'https://{prefix}.api.sandbox.checkout.com/issuing/disputes' \
--request POST \
--header 'Cko-Idempotency-Key: 7c1b9f96-4f2e-4b1a-bc2b-3d0f1a2e9f3a' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"transaction_id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
"reason": "4807",
"evidence": [
{
"name": "evidence.pdf",
"content": "",
"description": "Goods were not received."
}
],
"amount": 100,
"presentment_message_id": "msg_fa6psq242dcd6fdn5gifcq1491",
"fraud_details": {
"fraud_type": "card_not_present_fraud",
"description": "Cardholder confirmed they made no online purchases on this date."
},
"justification": ""
}'
{
"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"
]
}
}
}Beta
Retrieve the details of an Issuing dispute.Pattern: ^idsp_[a-z0-9]{26}$The unique identifier for the Issuing dispute.
Forbidden
Not Acceptable
Unsupported Media Type
Too Many Requests
curl 'https://{prefix}.api.sandbox.checkout.com/issuing/disputes/idsp_fa6psq242dcd6fdn5gifcq1491' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
"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"
]
}
}
}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 viaaction_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.
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.
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.
Pattern: ^idsp_[a-z0-9]{26}$The unique identifier for the Issuing dispute.
Pattern: ^[A-Za-z0-9._-]+$An idempotency key for safely retrying requests.
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.
The updated four-digit scheme-specific reason code. If a value is not provided, the existing reason code is retained.
The updated disputed amount, in the minor unit of the transaction currency. If not provided, the existing amount is retained.
The updated or additional evidence requested by the Dispute Resolution team. Follow the card scheme's requirements.
Provides the fraud category, and additional context if available.
This field is required if reason specifies a fraud-related dispute.
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.
Free-form text that you can use to explain your choices, provide additional context, or ask questions about the requested changes.
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."
}'
{
"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"
]
}
}
}Beta
Cancel an Issuing dispute. If you decide not to proceed with a dispute, you can cancel it either:Pattern: ^idsp_[a-z0-9]{26}$The unique identifier for the Issuing dispute.
Pattern: ^[A-Za-z0-9._-]+$An idempotency key for safely retrying requests.
curl 'https://{prefix}.api.sandbox.checkout.com/issuing/disputes/idsp_fa6psq242dcd6fdn5gifcq1491/cancel' \
--request POST \
--header 'Cko-Idempotency-Key: 7c1b9f96-4f2e-4b1a-bc2b-3d0f1a2e9f3a' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'
Beta
Escalate an Issuing dispute to pre-arbitration or arbitration.Pattern: ^idsp_[a-z0-9]{26}$The unique identifier for the Issuing dispute.
Pattern: ^[A-Za-z0-9._-]+$An idempotency key for safely retrying requests.
Justification for escalating the dispute.
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.
The updated disputed amount, in the minor unit of the representment currency.
The change to the dispute reason and your justification for changing it.
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.
curl 'https://{prefix}.api.sandbox.checkout.com/issuing/disputes/idsp_fa6psq242dcd6fdn5gifcq1491/escalate' \
--request POST \
--header 'Cko-Idempotency-Key: 7c1b9f96-4f2e-4b1a-bc2b-3d0f1a2e9f3a' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"justification": "The cardholder maintains that the goods were not received.",
"amount": 100,
"reason_change": {
"reason": "4837",
"justification": "Reason changed due to evidence from the acquirer."
},
"additional_evidence": [
{
"name": "evidence.pdf",
"content": "c29tZSBiYXNlNjQgZGF0YQ==",
"description": "Goods were not received."
}
]
}'
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.
Pattern: ^idsp_[a-z0-9]{26}$The unique identifier for the Issuing dispute.
Pattern: ^[A-Za-z0-9._-]+$An idempotency key for safely retrying requests.
The updated four-digit scheme-specific reason code. If not provided, Checkout.com uses the existing reason code.
Your evidence for the chargeback, if updated since you created the dispute.
The updated disputed amount, in the minor unit of the transaction or representment currency. If not provided, Checkout.com uses the existing disputed amount.
curl 'https://{prefix}.api.sandbox.checkout.com/issuing/disputes/idsp_fa6psq242dcd6fdn5gifcq1491/submit' \
--request POST \
--header 'Cko-Idempotency-Key: 7c1b9f96-4f2e-4b1a-bc2b-3d0f1a2e9f3a' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"reason": "4807",
"evidence": [
{
"name": "evidence.pdf",
"content": "",
"description": "Goods were not received."
}
],
"amount": 100
}'
{
"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"
]
}
}
}