POST/
Create a new dispute case by specifying the type and including the type-specific details object.
Body field details
| Fields | Description |
|---|---|
| token string Optional | The unique identifier of the dispute case. If you do not include a token, the system generates a token automatically. Because this token is necessary for use in other API calls, it is recommended that, rather than let the system generate the token, you use a simple string that is easy to remember. This value cannot be updated. Allowable Values: 36 char max |
| type string Required | The type of case. Allowable Values: DISPUTE |
| memo string Optional | Free-form comments about the dispute. Allowable Values: 512 char max |
| dispute_details object Required | The reason for the dispute. Allowable Values: See The dispute_details object table. |
The dispute_details object
Include this object in your request if the case type isDISPUTE.
| Fields | Description |
|---|---|
| original_transaction_token string Required | The token of the original transaction under dispute. Allowable Values: 36 char max |
| dispute_amount number Required | The amount of funds under dispute. Allowable Values: Must be less than or equal to the original transaction amount. |
| dispute_amount_change_reason string Conditionally required | The reason the dispute amount has been changed from the transaction amount. Required if dispute_amount is not equal to transaction amount.Allowable Values: MERCHANT_ISSUED_PARTIAL_REFUND, PARTIAL_DISPUTE, NOT_AS_DESCRIBED_PARTIAL, PARTIAL_SERVICE, PRORATED_REFUND, NOT_AUTHORIZED_FOR_FULL_AMOUNT |
| currency_code string Optional | The currency in which the original transaction was made. Currently, only 480, which is USD, is supported. Allowable Values: 30 char max |
| dispute_reason string Required | The code describing the reason for the dispute. Allowable Values: See Dispute case reasons. |
| cardholder_contact_date datetime Conditionally required | The date that the cardholder made initial contact regarding the dispute. Required for Regulation E reason codes if the program has been enrolled for Regulation E provisional credit; otherwise, optional. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
Dispute case reasons
The following are the possible Mastercard dispute messages along with the equivalent reason codes.| Mastercard Dual Message | Reason Code |
|---|---|
| Authorization-related disputes | |
| Required authorization not obtained | NO_AUTHORIZATION |
| Expired authorization protection period | NO_AUTHORIZATION |
| Multiple authorization requests | NO_AUTHORIZATION |
| Late presentment | NO_AUTHORIZATION |
Cardholder disputes | |
| Goods or services were either not as described or defective | CARDHOLDER_DISPUTE |
| Goods or services not provided | CARDHOLDER_DISPUTE |
| Credit not processed | CREDIT_NOT_PROCESSED |
| Counterfeit goods | CARDHOLDER_DISPUTE |
| Recurring transaction | CANCELLED_RECURRING_TRANSACTION |
| No-show hotel charge | CARDHOLDER_DISPUTE |
| Credit posted as a purchase | CARDHOLDER_DISPUTE |
Fraud-related disputes | |
| No cardholder authorization (card-absent or manual/key-entered card-present) | NOT_AUTHORIZED_CARD_ABSENT |
| Chip liability shift (non-fallback transaction) | CHIP_LIABILITY_SHIFT |
| Chip/PIN liability shift (card must be PIN-preferring to use this reason code) | CHIP_PIN_LIABILITY_SHIFT_LOST_STOLEN |
Point of interaction error disputes | |
| Duplicate charge | POINT_OF_INTERACTION_ERRORS |
| Paid by other means | POINT_OF_INTERACTION_ERRORS |
| Transaction amount differs | POINT_OF_INTERACTION_ERRORS |
| ATM disputes | POINT_OF_INTERACTION_ERRORS |
| Currency errors | POINT_OF_INTERACTION_ERRORS |
Response body
| Fields | Description |
|---|---|
| token string Returned | The unique identifier of the dispute case. Allowable Values: 36 char max |
| type string Returned | The type of case. Allowable Values: DISPUTE |
| memo string Returned | Free-form comments about the dispute. Allowable Values: 512 char max |
| program_short_code string Returned | Indicates what program the case belongs to. Allowable Values: 10 char max |
| user_token string Returned | Token that identifiers the user that made the original transaction. Allowable Values: 36 char max |
| business_token string Returned | the token of the business involved in the dispute case. Allowable Values: 36 char max |
| state string Returned | Indicates the current case state. Allowable Values: OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED |
| assignee string Returned | Indicates who is working on the case. This is updated by the case transition endpoint with reason_code 22 and ASSIGN action. Allowable Values: 255 char max |
| zendesk_ticket_id string Optional | ID for the Zendesk ticket. Allowable Values: 255 char max |
| type_change_time datetime Optional | When the type was changed. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
| dispute_details object Returned | The details of the dispute case. Allowable Values: See The dispute_details_response object table. |
| created_time datetime Returned | The time when the dispute case was created. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
| updated_time datetime Returned | The time when the dispute case was last updated. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
Sample request body
JSON
{
"token": "string",
"type": "DISPUTE",
"memo": "Memo text",
"dispute_details": {
"original_transaction_token": "string",
"dispute_amount": 0,
"dispute_amount_change_reason": "MERCHANT_ISSUED_PARTIAL_REFUND",
"currency_code": "USD",
"dispute_reason": "CARDHOLDER_DISPUTE",
"cardholder_contact_date": "2023-07-18T22:24:46.251Z"
}
}
Sample response body
JSON
{
"token": "string",
"type": "DISPUTE",
"memo": "string",
"program_short_code": "string",
"user_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"business_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"state": "OPEN",
"assignee": "string",
"zendesk_ticket_id": "string",
"type_change_time": "string",
"dispute_details": {
"original_transaction_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"original_transaction_type": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"dispute_amount": 0,
"dispute_amount_change_reason": "MERCHANT_ISSUED_PARTIAL_REFUND",
"currency_code": "string",
"dispute_reason": "CARDHOLDER_DISPUTE",
"dispute_state": "INITIATED",
"chargeback_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"network": "MASTERCARD",
"acquirer_fee": 0,
"associated_transaction_selection_required": true,
"card_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"network_failure_response": "string",
"cardholder_contact_date": "2023-07-18T22:24:46.251Z",
"provisional_credit_granted": true,
"regulation_type": "string"
},
"created_time": "2023-07-20T15:36:41.909Z",
"updated_time": "2023-07-20T15:36:41.909Z"
}