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 | Unique identifier of the dispute case. If you do not include a token, the system generates one 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 | Type of dispute case. Allowable Values: DISPUTE |
| memo string Optional | Free-form comments about the dispute. Allowable Values: 512 char max |
| network_comment string Optional | Comment provided by the cardholder to be sent to the PULSE card network. Allowable Values: 500 char max, with the following allowed and disallowed characters: Allowed Characters: % & * ( ) _ - + ’ : , . ` , ? /Disallowed Characters: ! @ # $ ^ = [ ] { } ” ; < > \ | |
| salesforce_ticket_id string Optional | Identifier of the associated Salesforce ticket. Allowable Values: 255 char max |
| dispute_details object Required | Object describing the disputed transaction, including 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 | Unique identifier of the original transaction under dispute. Allowable Values: 36 char max |
| original_transaction_type string Required | Transaction type of the original transaction under dispute. Allowable Values: 255 char max |
| dispute_amount number Required | Amount of funds under dispute. Allowable Values: Must be less than or equal to the original transaction amount |
| dispute_reason string Required | Code describing the reason for the dispute. Allowable Values: See The dispute_details.dispute_reason field table. |
| cardholder_contact_date datetime Required | Date that the cardholder made initial contact regarding the dispute. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
| cancelled_recurring_payment_date string Optional | Date that the recurring payment was cancelled. Optional field for CANCELLED_RECURRING_TRANSACTION disputes.Allowable Values: Format: yyyy-MM-dd |
| recurring_payment_plan_expiry_date string Required | Date that the recurring payment plan expired. Optional field for CANCELLED_RECURRING_TRANSACTION disputes.Allowable Values: Format: yyyy-MM-dd |
| cash_over_indicator string Optional | Indicates the disputed portion of the transaction. - M indicates that the merchandise portion of the transaction is in dispute. - C indicates that the cash portion of the transaction is in dispute. - B indicates that both the merchandise and cash portions of the transaction are in dispute. Conditionally required field for CREDIT_NOT_PROCESSED disputes that do not include the date_of_return field.Optional field for INCORRECT_TRANSACTION_AMOUNT, LATE_PRESENTMENT, NO_AUTHORIZATION, NOT_AS_DESCRIBED_OR_DEFECTIVE_MERCHANDISE, and SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_RECEIVED disputesAllowable Values: M, C, B |
| comments string Optional | Freeform text comments provided by the cardholder. Optional field for INCORRECT_TRANSACTION_AMOUNT and INCORRECT_TRANSACTION_CODE disputes.Allowable Values: 500 char max |
| credit_confirmation_number string Optional | Reference number for the credit that was provided to the cardholder. Optional field for INCORRECT_TRANSACTION_CODE disputes.Allowable Values: 25 char max |
| date_of_return string Optional | Date on which the merchandise was returned to the merchant. Conditionally required field for CREDIT_NOT_PROCESSED disputes that do not include the cash_over_indicator field.Optional field for INCORRECT_TRANSACTION_CODE and SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_RECEIVED disputes.Allowable Values: Format: yyyy-MM-dd |
| return_method string Optional | Code that indicates the method by which the merchandise was returned to the merchant. - F2F indicates that the merchandise was returned in person. - FEDEX indicates that the merchandise was returned by FedEx. - DHL indicates that the merchandise was returned by DHL. - POSTAL_SERVICE indicates that the merchandise was returned by the Postal Service. - UPS indicates that the merchandise was returned by UPS. - OTHER indicates that the merchandise was returned by other means. Optional field for INCORRECT_TRANSACTION_CODE disputes.Allowable Values: F2F, FEDEX, DHL, POSTAL_SERVICE, UPS, OTHER |
| motive_code string Optional | Code that indicates additional return reason details. - QUALITY_OF_GOODS_OR_SERVICES indicates that the cardholder disputes the quality of the goods received or services rendered. - TERMS_OF_SALE_OR_COUNTERFEIT_MERCHANDISE indicates that the cardholder disputes the terms of sale, or that the merchandise is counterfeit. Required field for NOT_AS_DESCRIBED_OR_DEFECTIVE_MERCHANDISE disputes.Allowable Values: QUALITY_OF_GOODS_OR_SERVICES, TERMS_OF_SALE_OR_COUNTERFEIT_MERCHANDISE |
| merchandise_counterfeit_confirmation_date string Optional | Date that the merchandise was determined to be counterfeit. Optional field for NOT_AS_DESCRIBED_OR_DEFECTIVE_MERCHANDISE disputes.Allowable Values: Format: yyyy-MM-dd |
| promised_delivery_date string Optional | Date that the merchandise was due to be delivered, or the service was due to be performed. Optional field for NOT_AS_DESCRIBED_OR_DEFECTIVE_MERCHANDISE disputes.Allowable Values: Format: yyyy-MM-dd |
| agreed_delivery_or_service_date string Conditionally required | Date of delivery or service agreed upon by both merchant and cardholder. Used for non-receipt of goods or services disputes. This field is required if the dispute is submitted within 15 days of the settlement date. This field is optional if the dispute is submitted 16 or more days after the original settlement date. Allowable Values: Format: yyyy-MM-dd |
| date_of_cancellation string Optional | Date on which the merchandise or service order was cancelled. Optional field for CREDIT_NOT_PROCESSED disputes.Allowable Values: Format: yyyy-MM-dd |
The dispute_details.dispute_reason field
The following table describes the possible values for thedispute_details.dispute_reason field.
| Dispute Reason | Description |
|---|---|
CANCELLED_RECURRING_TRANSACTION | A recurring transaction was cancelled. |
CREDIT_NOT_PROCESSED | A credit was not processed. |
DUPLICATE_PROCESSING | A single transaction was processed more than once using the same payment credential on the same transaction date, and for the same transaction amount. |
DUPLICATE_PROCESSING_OR_PAID_BY_OTHER_MEANS | A single transaction was paid by other means. Use this dispute reason only for “paid by other means” disputes. For duplicate processing disputes, use DUPLICATE_PROCESSING |
EMV_LIABILITY_SHIFT_COUNTERFEIT_FRAUD | The transaction was completed with a counterfeit card in a card-present environment and qualifies for the EMV liability shift. |
EMV_LIABILITY_SHIFT_NON_COUNTERFEIT_FRAUD | The transaction was completed in a card-present environment with a card that was reported lost or stolen and qualifies for the EMV liability shift. |
INCORRECT_ACCOUNT_NUMBER | The account number is incorrect. |
INCORRECT_TRANSACTION_AMOUNT | The transaction amount is incorrect. |
INCORRECT_TRANSACTION_CODE | The transaction code is incorrect. |
LATE_PRESENTMENT | The card network cannot verify that the transaction amount was deposited within 30 days. |
NO_AUTHORIZATION | - Authorization was required, but not obtained. - The primary account number (PAN) does not exist. - A Card Not Present (CNP) transaction was initially declined but subsequently approved through stand-in processing. |
NON_RECEIPT_OF_CASH_OR_LOAD_TRANSACTION_VALUE_AT_ATM | The cardholder did not receive the full cash withdrawal or received only partial amount. |
NOT_AS_DESCRIBED_OR_DEFECTIVE_MERCHANDISE | The merchandise was not as described or defective. |
NOT_AUTHORIZED_CARD_ABSENT | An unauthorized user initiated the transaction and the card was not present. |
NOT_AUTHORIZED_CARD_PRESENT | The cardholder denies authorization of or participation in a key-entered transaction conducted in a card-present environment. |
SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_RECEIVED | The goods or services were not provided. |
The pulseProcessingDisputeTypeDetails object
| Fields | Description |
|---|---|
| late_presentment_details object Conditionally required | An object providing late presentment details. Allowable Values: See The late_presentment_details object table. |
| incorrect_transaction_code_details object Conditionally required | An object providing incorrect transaction code details. Allowable Values: See The incorrect_transaction_code_details object table. |
| incorrect_currency_details object Conditionally required | An object providing incorrect currency details. Allowable Values: See The incorrect_currency_details object table. |
| incorrect_account_number_details object Conditionally required | An object providing incorrect account number details. Allowable Values: See The incorrect_account_number_details object table. |
| incorrect_transaction_amount_details object Conditionally required | An object providing incorrect transaction amount details. Allowable Values: See The incorrect_transaction_amount_details object table. |
| duplicate_processing_or_paid_by_other_means_details object Conditionally required | An object providing details about duplicate processing or paid by other means. Allowable Values: See The duplicate_processing_or_paid_by_other_means_details object table. |
The late_presentment_details object
| Fields | Description |
|---|---|
| account_status string Conditionally required | The account status. Whether this field is optional or required depends on previous answers provided by the cardholder. Allowable Values: ACCOUNT_CLOSED, CREDIT_PROBLEM, FRAUD, NONSUFFICIENT_FUNDS |
The incorrect_transaction_code_details object
| Fields | Description |
|---|---|
| how_is_transaction_code_incorrect string Conditionally required | The token of the original transaction under dispute. Whether this field is optional or required depends on previous answers provided by the cardholder. Allowable Values: CREDIT_INSTEAD_OF_REVERSAL_OR_ADJUSTMENT, CREDIT_POSTED_AS_DEBIT, DEBIT_POSTED_AS_CREDIT |
| explain_why_the_credit_refund_was_processed_in_error string Conditionally required | An explanation for why the credit refund was incorrectly processed. Whether this field is optional or required depends on previous answers provided by the cardholder. Allowable Values: |
The incorrect_currency_details object
| Fields | Description |
|---|---|
| incorrect_currency_reason string Conditionally required | The reason for the incorrect currency. Whether this field is optional or required depends on previous answers provided by the cardholder. Allowable Values: CURRENCY_DIFFERENCE, DCC_DISPUTE |
| what_was_the_correct_currency integer Conditionally required | An explanation for why the credit refund was incorrectly processed. Whether this field is optional or required depends on previous answers provided by the cardholder. Allowable Values: ISO 4217 currency number |
| certification_that_the_cardholder_did_not_agree_to_dynamic_currency_conversion_and_did_not_make_an_active_choice string Conditionally required | Indicates that the cardholder did not agree to or make an active choice for dynamic currency conversion. Whether this field is optional or required depends on previous answers provided by the cardholder. Allowable Values: true, false |
The incorrect_account_number_details object
| Fields | Description |
|---|---|
| is_the_account_number_on_the_issuers_master_file boolean Conditionally required | Indicates whether the cardholder’s account number is also in the issuer’s file. Whether this field is optional or required depends on previous answers provided by the cardholder. Allowable Values: true, false |
| does_the_account_number_on_the_receipt_match_the_cardholders_account_number_or_token boolean Conditionally required | Indicates whether the account numbers match. Whether this field is optional or required depends on previous answers provided by the cardholder. Allowable Values: true, false |
The incorrect_transaction_amount_details object
| Fields | Description |
|---|---|
| what_is_the_amount_on_the_cardholders_receipt number Conditionally required | The amount on the cardholder’s receipt. Allowable Values: 32 bytes |
| what_is_the_currency_on_the_cardholders_receipt string Conditionally required | The currency on the cardholder’s receipt. Allowable Values: A valid currency code. |
| is_the_dispute_due_to_the_difference_between_quoted_price_and_actual_charges_made_by_the_merchant boolean Conditionally required | Indicates whether the dispute appeared due to the difference between quoted price and actual charges made by the merchant. Allowable Values: true, false |
Response body
| Fields | Description |
|---|---|
| token string Returned | Unique identifier of the dispute case. Allowable Values: 36 char max |
| type string Returned | Dispute case type. Allowable Values: DISPUTE |
| memo string Returned | Free-form comments about the dispute. Allowable Values: 512 char max |
| program_short_code string Returned | Indicates which program the case belongs to. Allowable Values: 10 char max |
| user_token string Returned | Unique identifier of the cardholder who made the original transaction. Allowable Values: 36 char max |
| business_token string Returned | Unique identifier 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. Allowable Values: 255 char max |
| salesforce_ticket_id string Optional | Identifier of the Salesforce ticket. Allowable Values: 255 char max |
| type_change_time datetime Optional | Date and time when the dispute case type was changed. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
| dispute_details object Returned | Details of the dispute case. Allowable Values: See The dispute_details_response object table. |
| created_time datetime Returned | Date and time when the dispute case was created. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
| updated_time datetime Returned | Date and time when the dispute case was last updated. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
Sample request body
JSON
{
"dispute_details": {
"dispute_reason": "NOT_AUTHORIZED_CARD_ABSENT",
"dispute_amount": 90.00,
"original_transaction_token": "b0c7a19e-e172-4c55-9af3-aad89c339b78",
"cardholder_contact_date": "2025-02-03T00:00:00Z"
},
"type": "DISPUTE"
}
Sample response body
JSON
{
"created_time": "2025-03-02T19:28:56Z",
"last_modified_time": "2025-03-02T19:28:56Z",
"token": "deqa-55349",
"type": "DISPUTE",
"user_token": "a5dc8fd4-c428-469c-ab6a-c2b2852771bc",
"state": "OPEN",
"dispute_details": {
"original_transaction_token": "b0c7a19e-e172-4c55-9af3-aad89c339b78",
"original_transaction_type": "authorization.clearing",
"dispute_amount": 90.00,
"currency_code": "GBP",
"dispute_reason": "NOT_AUTHORIZED_CARD_ABSENT",
"network": "PULSE",
"card_token": "8f49f6e5-ced2-4324-b930-829b3305f155",
"provisional_credit_granted": false,
"acquirer_fee": 0.0000,
"associated_transaction_selection_required": false
}
}