/cases endpoint to manage transaction disputes on the PULSE network.
For general information on disputes, chargebacks, and best practices, see About Disputes.
Create dispute case
Action:POSTEndpoint:
/cases
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
}
}
Retrieve dispute case
Action:GETEndpoint:
/cases/{token}
Retrieve a specific dispute case.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the dispute case to retrieve. Allowable Values: 36 char max |
Response body
| Fields | Description |
|---|---|
| token string Returned | The 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 what program the case belongs to. Allowable Values: 10 char max |
| user_token string Returned | Unique identifier of the cardholder that 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 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. |
| 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 |
JSON
{
"count": 1,
"start_index": 1,
"end_index": 1,
"is_more": false,
"data": [
{
"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
}
}
]
}
List dispute cases
Action:GETEndpoint:
/cases
List existing dispute cases. This endpoint supports sorting and pagination.
Query parameters
| Fields | Description |
|---|---|
| 3ds boolean Optional | Returns dispute cases that involve 3D Secure. Allowable Values: true, false |
| assignee string Optional | Returns dispute cases associated with the specified assignee. Allowable Values: 255 char max |
| associated_transaction_required boolean Optional | Returns dispute cases that have any associated transactions. Allowable Values: true, false |
| chargeback_token string Optional | Returns dispute cases associated with the specified chargeback. Allowable Values: 36 char max |
| dispute_state array of strings Optional | Returns a comma-separated list of dispute states that will be used to filter the resulting case. Allowable Values: INITIATED, REPRESENTMENT, PRE_ARBITRATION, ARBITRATION, CASE_WON, CASE_LOST, NETWORK_REJECTED, CLOSED, WRITTEN_OFF_ISSUER, WRITTEN_OFF_PROGRAM |
| network_case_number string Optional | Returns dispute cases associated with the specified network case number. Allowable Values: Valid network case number |
| next_actor string Optional | Returns the dispute cases associated with the specified next actor, such as ISSUER, ACQUIRER, COURT, or DISPUTE_COMPLETED.Allowable Values: Existing next actor |
| original_transaction_token string Optional | Returns dispute cases associated with the specified token. Allowable Values: 36 char max |
| reason string Optional | Returns disputes that are using the provided dispute reason. Allowable Values: See Dispute case reasons |
| state string Optional | Returns a comma-separated list of case states that will be used to filter the resulting case. Allowable Values: OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED |
| type string Optional | Returns cases of the specified type. Allowable Values: DISPUTE |
| user_token string Optional | Returns dispute cases associated with the specified user. Allowable Values: 36 char max |
Response body
| Fields | Description |
|---|---|
| token string Returned | The 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 what 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 |
| 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 |
The dispute_details_response object
| Fields | Description |
|---|---|
| original_transaction_token string Returned | Unique identifier of the original transaction under dispute. Allowable Values: 36 char max |
| original_transaction_id integer Returned | Unique identifier of the original transaction under dispute. Allowable Values: 36 char max |
| original_transaction_type string Returned | Transaction type of the original transaction under dispute. Allowable Values: 255 char max |
| dispute_amount number Returned | Amount of funds under dispute. Allowable Values: Must be less than or equal to the original transaction amount |
| dispute_amount_change_reason string Returned | The reason the dispute amount has been changed from the 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 Returned | Currency in which the original transaction was made. Allowable Values: 30 char max |
| dispute_reason string Returned | Code describing the reason for the dispute. Allowable Values: See The dispute_details.dispute_reason field table |
| dispute_state string Returned | The current dispute state. Once the case’s state has been moved to CHARGEBACK_INITIATED, this field will be updated as it progresses in the backend lifecycle.Allowable Values: INITIATED, REPRESENTMENT, PRE_ARBITRATION, ARBITRATION, CASE_WON, CASE_LOST, NETWORK_REJECTED, CLOSED, WRITTEN_OFF_ISSUER, WRITTEN_OFF_PROGRAM |
| chargeback_token string Returned | Indicates what is the associated chargeback in the legacy system. This is useful to map the current chargeback webhooks back a dispute case. This field is populated once the case state has moved to CHARGEBACK_INITIATED. For Regulation E dispute cases, this value is returned after dispute case creation.Allowable Values: 36 char max |
| network string Returned | Card network on which the transaction took place. Allowable Values: PULSE |
| network_case_number string Returned | Card network identifier of the dispute case. Allowable Values: A valid network case number |
| acquirer_fee number Returned | Acquirer fee for the transaction. Allowable Values: Valid number |
| associated_transaction_selection_ required boolean Returned | Indicates whether there are any transactions related to the original transaction. Allowable Values: true, false |
| card_token string Returned | Unique identifier of the payment card used in the original transaction. Allowable Values: 36 char max |
| pulseProcessingDisputeTypeDetails object Returned | Object providing details about processing error disputes. Allowable Values: See The pulseProcessingDisputeTypeDetails object table |
| consumer_dispute_type_dispute_details object Returned | Indicates the latest error that has occurred while the case is processed. Allowable Values: See The consumer_dispute_type_dispute_details object table |
| network_case_status_details object Returned | Available once the case state has been successfully transitioned to CHARGEBACK_INITIATED.Allowable Values: See The network_case_status_details object table |
| additional_dispute_details object Optional | An object providing any additional information for a case. Allowable Values: See The additional_dispute_details object table |
| fraud_dispute_type_details object Returned | Provides any additional information for cases with a fraud dispute reason. Contains the general_fraud_type_dispute_details object, which contains the chip_on_card boolean value, which is set to true if the card used for the original transaction had a chip.Allowable Values: true, false |
| network_failure_response string Returned | Indicates the latest error that has occurred while the case is processed. Allowable Values: 255 char max |
| fraud_category_type_dispute_details object Returned | Additional information regarding a previously submitted fraud report in the network. Allowable Values: See The fraud_category_type_dispute_details object table |
| cardholder_contact_date date Returned | Date that the cardholder made initial contact regarding the dispute. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
| provisional_credit_granted boolean Returned | Indicates whether the provisional credit was granted. Set to true whenever a credit has been granted through the cases endpoint.Allowable Values: true, false |
| regulation_type string Returned | Regulation type of the dispute case. For Regulation E cases, this value is REG_E.Allowable Values: 255 char max |
The network_case_status_details object
| Fields | Description |
|---|---|
| network string Returned | Card network on which the original transaction originated and is being processed. Allowable Values: PULSE |
| network_case_number string Returned | Card network identifier for the case. Allowable Values: Valid network identifier |
| case_status string Returned | Card network-specific value that represents the status of the case in the network. Allowable Values: Valid status value |
| current_case_amount number Returned | Current amount that has been disputed in the network. Allowable Values: Valid number |
| next_actor string Returned | Indicates the actor who is currently expected to act upon the case. Allowable Values: ISSUER, ACQUIRER, DISPUTE_COMPLETED, UNKNOWN |
| days_to_act integer Returned | Number of days left to act for the next_actor before the dispute case defaults.Allowable Values: Valid integer |
| last_action_date date Returned | Date when the case was last updated in the card network. Allowable Values: Format: yyyy-MM-dd |
| case_opened_date date Returned | Date when the case was opened in the card network. Allowable Values: Format: yyyy-MM-dd |
| last_refresh_date date Returned | Date when the case was last refreshed from the card network to the Marqeta platform. Allowable Values: Format: yyyy-MM-dd |
| allowable_actions string Returned | Actions allowed for the dispute case in the current dispute state. Allowable Values: SUBMIT, ACCEPT_AND_CLOSE, RESPOND_WITH_PREARB, RESPOND_WITH_PREARB_RESPONSE, RESPOND_WITH_ARB, WAIT, REPRESENTMENT_RECEIVED, PREARB_RECEIVED, PREARB_ACCEPTED, PREARB_DECLINED, PREARB_RESPONSE_DECLINED, CLOSE_WITH_CASE_WON |
Sample response body
JSON
{
"count": 1,
"start_index": 0,
"end_index": 0,
"is_more": true,
"data": [
{
"token": "string",
"type": "DISPUTE",
"memo": "Multiple browser submission",
"program_short_code": "string",
"user_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"business_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"state": "OPEN",
"assignee": "string",
"dispute_details": {
"original_transaction_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"original_transaction_type": "transaction_type",
"dispute_amount": 120.49,
"dispute_amount_change_reason": "MERCHANT_ISSUED_PARTIAL_REFUND",
"currency_code": "480",
"dispute_reason": "SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_RECEIVED",
"dispute_state": "INITIATED",
"chargeback_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"network": "PULSE",
"network_case_number": "string",
"acquirer_fee": 0,
"associated_transaction_selection_required": "true",
"card_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"network_failure_response": "string",
"pulseProcessingDisputeTypeDetails": {
"late_presentment_details": {
"account_status": "ACCOUNT_CLOSED"
},
"incorrect_transaction_code_details": {
"how_is_transaction_code_incorrect": "CREDIT_INSTEAD_OF_REVERSAL_OR_ADJUSTMENT",
"explain_why_the_credit_refund_was_processed_in_error": "string"
},
"incorrect_account_number_details": {
"is_the_account_number_on_the_issuers_master_file": true,
"does_the_account_number_on_the_receipt_match_the_cardholders_account_number_or_token": true
},
"incorrect_transaction_amount_details": {
"what_is_the_amount_on_the_cardholders_receipt": 0,
"what_is_the_currency_on_the_cardholders_receipt": "string"
}
},
"consumer_dispute_type_dispute_details": {
"service_not_provided_merchandise_not_received_details": {
"detailed_description_of_what_was_purchased_and_explanation_of_the_dispute": "string",
"expected_receipt_date": "2025-01-31",
"expected_receipt_time": "2025-01-31",
"did_cardholder_cancel_prior_to_the_expected_date": true,
"cancellation_date": "2025-01-31",
"cancellation_reason": "string",
"did_cardholder_attempt_to_resolve_dispute_with_merchant": true,
"is_attempt_to_resolve_prohibited_by_local_law_or_regulations": true,
"provide_details_of_local_law_or_regulations": "string",
"merchandise_or_services": "MERCHANDISE SERVICES",
"was_merchandise_delivered_to_wrong_location": true,
"address_of_agreed_location": "string",
"did_cardholder_return_merchandise": true,
"date_cardholder_returned_merchandise": "2025-01-31",
"date_merchant_received_returned_merchandise": "2025-01-31",
"did_cardholder_attempt_to_return_merchandise": true,
"date_of_attempted_return": "2025-01-31",
"explain_how_merchandise_was_returned": "string",
"third_party_gift_card_indicator": true,
"pulse_commercial_card_virtual_account_indicator": true,
"did_virtual_account_holder_suffer_financial_loss": true,
"did_merchant_cancel_services": true,
"date_merchant_cancelled_services": "2025-01-31",
"explanation_dispute_prior_expected_delivery_date": "string"
},
"cancelled_recurring_transaction_details": {
"cancellation_date": "2025-01-31",
"cancellation_reason": "string",
"date_issuer_informed_merchant_of_account_closure": "2025-01-31"
},
"not_as_described_or_defective_merchandise_details": {
"not_as_described_or_defective": "NOT_AS_DESCRIBED DEFECTIVE",
"merchandise_or_services": "MERCHANDISE SERVICES",
"date_the_cardholder_first_notified_the_issuer_of_the_dispute": "2025-01-31",
"did_the_cardholder_attempt_to_resolve_the_dispute_with_the_merchant": true,
"is_attempt_to_resolve_prohibited_by_local_law_or_regulations": true,
"provide_details_of_local_law_or_regulations": "string",
"did_the_cardholder_return_the_merchandise": true,
"date_cardholder_returned_the_merchandise": "2025-01-31",
"date_merchant_received_the_returned_merchandise": "2025-01-31",
"return_method": "F2F",
"tracking_number": "string",
"date_of_attempted_return": "2025-01-31",
"provide_a_detailed_description_of_how_the_cardholder_attempted_to_return_and_the_disposition_of_the_merchandise": "string",
"did_the_cardholder_attempt_to_return_the_merchandise": true,
"explain_how_the_merchandise_was_returned": "string",
"cardholder_merchant_previous_negotiation_evidence": true,
"explain_prev_negotiation": "string",
"when_negotiations_begin": "2025-01-31",
"date_merchandise_or_service_was_received": "2025-01-31",
"does_the_dispute_involve_merchandise_or_services_provided_that_do_not_match_the_merchants_verbal_description": true,
"did_the_merchandise_or_services_differ_from_what_was_described_on_the_receipt": true,
"provide_details_of_what_was_ordered_and_not_as_described": "string",
"did_the_cardholder_cancel_the_services": true,
"cancellation_date": "2025-01-31",
"cancellation_reason": "string",
"what_was_ordered_and_how_it_was_damaged_or_defective": "string",
"date_merchandise_was_received": "2025-01-31"
},
"credit_not_processed_details": {
"was_a_credit_voucher_voided_transaction_receipt_or_refund_acknowledgement_given": true,
"is_the_credit_voucher_transaction_receipt_or_refund_acknowledgement_dated": true,
"credit_voucher_transaction_receipt_or_refund_acknowledgement_date": "2025-01-31",
"date_cardholder_returned_cancelled_merchandise": "string"
},
"cancelled_merchandise_or_services_details": {
"merchandise_or_services": "MERCHANDISE SERVICE",
"describe_what_was_purchased": "string",
"date_cardholder_received_or_expected_to_receive_merchandise": "2025-01-31",
"did_the_cardholder_attempt_to_resolve_the_dispute_with_the_merchant": true,
"is_attempt_to_resolve_prohibited_by_local_law_or_regulations": true,
"provide_details_of_local_law_or_regulations": "string",
"did_the_cardholder_return_the_merchandise": true,
"date_of_return": "2025-01-31",
"date_merchant_received_returned_merchandise": "2025-01-31",
"return_method": "F2F",
"tracking_number": "string",
"explain_how_the_merchandise_was_returned": "string",
"did_the_cardholder_attempt_to_return_the_merchandise": true,
"date_of_attempted_return": "2025-01-31",
"detailed_description_of_how_the_cardholder_attempted_to_return_and_the_disposition_of_the_merchandise": "2025-01-31",
"did_cardholder_cancel": true,
"cancellation_date": "2025-01-31",
"cancellation_reason": "string",
"was_cancellation_policy_provided": true,
"type_of_service": "TIMESHARE",
"date_of_service_or_expected_service": "2025-01-31",
"cancelled_guaranteed_reservation_certification_selection": "string"
}
},
"fraud_dispute_type_details": {
"general_fraud_type_dispute_details": {
"chip_on_card": true
}
},
"network_case_status_details": {
"network": "PULSE",
"network_case_number": "string",
"case_status": "string",
"current_case_amount": 0,
"next_actor": "ISSUER",
"days_to_act": 0,
"last_action_date": "2025-01-31T18:57:42.890Z",
"case_opened_date": "2025-01-31",
"last_refresh_date": "2025-01-31T18:57:42.890Z",
"allowable_actions": [
"SUBMIT"
]
},
"fraud_category_type_dispute_details": {
"fraud_report_details": {
"fraud_type": "LOST",
"fraud_type_code": "string",
"fraud_report_id": 0,
"fraud_type_category": "string"
}
}
},
"created_time": "2025-01-31T18:57:42.890Z",
"updated_time": "2025-01-31T18:57:42.890Z"
}
]
}
Create dispute case transition
Action:POSTEndpoint:
/cases/{token}/transitions
Transition a dispute case to another state or initiate a chargeback against the dispute case.
A dispute case transition is an event that changes the state of a dispute case and triggers other related events. The new state of the dispute case and which related events are triggered is determined by the action defined in the dispute case transition.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the dispute case associated with the transition you want to create. Send a GET request to /cases to retrieve dispute case tokens.Allowable Values: 36 char max |
Body field details
| Fields | Description |
|---|---|
| token string Optional | Unique identifier of the dispute case transition. If you do not include a token, the system generates one automatically. Allowable Values: 36 char max |
| action string Required | Action taken on the dispute case. Allowable Values: See Dispute case transitions |
| reason_code string Required | Identifies the standardized reason for the transition. Allowable Values: See The transition reason_code field table |
| created_by string Required | Identifier or name of the user who created the transition. Allowable Values: 255 char max |
| assignee string Optional | Identifier or name of the user assigned to the dispute case. Allowable Values: 255 char max |
| memo string Optional | Additional notes about the transition. Allowable Values: 16,777,215 char max |
| transition_details object Required | An object containing the transition details. Allowable Values: See The transition_details object |
The transition_details object
| Fields | Description |
|---|---|
| chargeback_details object Required | Object containing the chargeback details. Allowable Values: See The chargeback_details object. |
The chargeback_details object
| Fields | Description |
|---|---|
| attached_contents string Required | List of content tokens that should be submitted to the network when initiating a chargeback. The content tokens should be associated to the case. For more information about the uploading case documents, see Create dispute case content. Allowable Values: List of valid UUID tokens |
Dispute case transitions
Dispute case transitions represent the workflow during the creation, information gathering, and submission processes a dispute case. The dispute case transition actions and resulting states are described below.| Action | Reason Code | Resulting State | Description |
|---|---|---|---|
CREATE | N/A | OPEN, OPEN_WITH_ACTION_REQUIRED | Creates a new dispute case. A default action when a POST request is sent to the /cases endpoint. The OPEN_WITH_ACTION_REQUIRED state results if additional information is needed from the user.For programs that are enabled for Regulation E, this action and reason code returns an error for a Regulation E dispute and sets provisionalCreditGranted to true. |
RE_OPEN | N/A | OPEN | Reopens a dispute case to get additional information or documents. Dispute case state changes to OPEN. |
CHARGEBACK_CREDIT | 28 | CHARGEBACK_INITIATED | Sends a POST request to the \cases endpoint with credit_user set to true. Set reason_description as the value of dispute_reason and channel as ISSUER_AUTOMATED when creating the chargeback.Dispute case state changes to CHARGEBACK_INITIATED if no additional information is required. The OPEN_WITH_ACTION_REQUIRED state results if additional information is needed from the user before the chargeback can be submitted to the network.Only for programs that are not enabled for Regulation E. |
CHARGEBACK_NO_CREDIT | 29 | CHARGEBACK_INITIATED | Sends a POST request to the \cases endpoint with credit_user set to false. Set reason_description as the value of dispute_reason and channel as ISSUER_AUTOMATED when creating the chargeback.Dispute case state changes to CHARGEBACK_INITIATED if no additional information is required. The OPEN_WITH_ACTION_REQUIRED state results if additional information is needed from the user before the chargeback can be submitted to the network.Only for programs that are not enabled for Regulation E. For programs that are enabled for Regulation E, this action and reason code return an error for a Regulation E dispute. |
CHARGEBACK_SUBMIT | 51 | CHARGEBACK_INITIATED | Submitting dispute to the network. This applies only to programs that are enabled for Regulation E and for a Regulation E dispute. If provisional credit has not been granted, this returns an error. For programs that are not enabled for Regulation E, this returns an error. |
REVIEW | N/A | READY | Dispute case is ready to review. Dispute case state changes to READY. |
ASSIGN | N/A | No change | Assigns a dispute case to a user. An assignee value is required. Does not change dispute case state. |
CLOSE | 41 | CLOSED | Closes the dispute case. The case was won. Dispute case state changes to CLOSED. For all types of dispute cases, this action cannot be triggered until dispute_state is in a CASE_WON state. |
CLOSE | 42 | CLOSED/PENDING_CLOSED | Closes the dispute case. The case was lost. For non-Regulation E cases, this results in the CLOSED state. For Regulation E cases, this results in the PENDING_CLOSED state. |
CLOSE | 45 | CLOSED | Closes the dispute case. Dispute case state changes to CLOSED. This reason code indicates that the case will be closed and written off using funds from the program account. |
WITHDRAW_AND_CLOSE | 40 | CLOSED | No further action is needed, closing the case by withdrawing. This action can only be taken from the OPEN or OPEN_WITH_ACTION_REQUIRED state and when provisional credit has not been granted. |
WRITE_OFF | N/A | No change | Written off either by user or program. |
GRANT_CREDIT | N/A | No change | Granting provisional credit. |
REVERT_CREDIT | N/A | No change | Reverting provisional credit. |
CHANGE_CASE_TYPE | N/A | No change | Change case from DISPUTE type to the LEGACY_DISPUTE type. |
The transition reason_code field
The transition reason code identifies the standardized reason for the transition.| Reason Code | Description | Related Actions |
|---|---|---|
| 00 | The dispute case was created. | CREATE |
| 01 | The dispute case was created, but needs additional verification actions. | CREATE |
| 05 | The dispute case is under review. | REVIEW |
| 14 | The Marqeta platform updated the dispute case. | CLOSE, NON_CHARGEBACK_CREDIT |
| 22 | The dispute case was assigned to a user. | ASSIGN |
| 23 | The dispute case was reopened. | RE_OPEN |
| 24 | The dispute case was reopened to gather more information. | RE_OPEN |
| 25 | The documents were verified and the dispute case is being closed. | CLOSE |
| 26 | The customer closed the dispute case. | CLOSE |
| 27 | The dispute is for a smaller amount and no chargeback is needed. | NON_CHARGEBACK_CREDIT |
| 28 | A chargeback was created and the cardholder was credited. Only for programs that are not enabled for Regulation E. | CHARGEBACK_CREDIT |
| 29 | A chargeback was created and the cardholder was not credited. Only for programs that are not enabled for Regulation E. | CHARGEBACK_NO_CREDIT |
| 30 | The dispute case was closed automatically due to inactivity. | CLOSE, WITHDRAW_AND_CLOSE |
| 34 | The chargeback failed. Only for programs that are not enabled for Regulation E. | CHARGEBACK_CREDIT, CHARGEBACK_NO_CREDIT |
| 35 | The chargeback failed at the card network. Only for programs that are not enabled for Regulation E. | CHARGEBACK_CREDIT, CHARGEBACK_NO_CREDIT, CLOSE |
| 36 | KYC override failed. | KYC_OVERRIDE |
| 39 | Associated transaction selection is required to ready this dispute case. | N/A |
| 40 | No further action is needed. Closing the dispute case by withdrawing. Only used when the provisional credit has not been granted in the OPEN and OPEN_WITH_ACTION_REQUIRED states. For Regulation E and non-Regulation E cases, this results in the CLOSED state and the chargeback is WITHDRAWN. | WITHDRAW_AND_CLOSE |
| 41 | The dispute case was won, accepted with favorable results, for to all types of dispute cases. This action cannot trigger until the dispute_state is CASE_WON. | CLOSE |
| 42 | The dispute case was lost, accepted with unfavorable results. For non-Regulation E dispute cases, this results in the CLOSED state. For Regulation E dispute cases, this results in PENDING_CLOSED. | CLOSE |
| 43 | The dispute case was rejected by the network. | CLOSE |
| 44 | The dispute case was written off by the issuer. | WRITE_OFF, CLOSE |
| 45 | The dispute case was closed and written off by the program using funds from the program account. | WRITE_OFF, CLOSE |
| 46 | Provisional credit has been granted. | GRANT_CREDIT |
| 47 | Provisional credit has been reverted. | REVERT_CREDIT |
| 48 | A failure occurred when attempting to transition to the READY state. | No change |
| 49 | The dispute case was reported to the network as FRAUD. | WITHDRAW_AND_CLOSE |
| 50 | The dispute case was changed from DISPUTE type to LEGACY_DISPUTE type. | CHANGE_CASE_TYPE |
| 51 | Submitting dispute to the network. This applies only to programs that are enabled for Regulation E and for a Regulation E dispute. If provisional credit has not been granted, this returns an error. For programs that are not enabled for Regulation E, this returns an error. | CHARGEBACK_SUBMIT |
| 52 | Provisional credit is required for a Regulation E dispute case. | N/A |
| 53 | Awaiting milestone. | N/A |
Dispute transition response
| Fields | Description |
|---|---|
| case_token string Returned | Unique identifier of the dispute case. Allowable Values: 36 char max |
| token string Returned | Unique identifier of the dispute case transition. Allowable Values: 36 char max |
| action string Returned | Action taken on the dispute case. Allowable Values: See Dispute case transitions |
| reason_code string Returned | Identifies the standardized reason for the transition. Allowable Values: See The transition reason_code field table |
| reason_description string Returned | Descriptive reason for the transition. Allowable Values: 36 char max |
| created_by string Returned | Identifier or name of the user who created the transition. Allowable Values: 36 char max |
| from_state string Returned | State of the dispute case before the case transition was created. Allowable Values: OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED |
| state string Returned | Resulting state of the dispute case after the transition was created. Allowable Values: OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED |
| assignee string Returned | Identifier or name of the user assigned to the dispute case. Allowable Values: 255 char max |
| memo string Returned | Additional notes about the transition. Allowable Values: 512 char max |
| failure_reason string Returned | If an error occurred while attempting to transition the dispute case, this field provides a brief description of the failure. Allowable Values: 512 char max |
| transition_details object Returned | Object containing the transition details. Allowable Values: See The transition_details object. |
Sample request body (CHARGEBACK_CREDIT)
This sample is only for programs that are not enabled for Regulation E.JSON
{
"token": "dispute_case_token",
"action": "CHARGEBACK_CREDIT",
"reason_code": "28",
"created_by": "user_name",
"assignee": "assignee_name",
"memo": "Text about this dispute",
"transition_details": {
"chargeback_details": {
"attached_contents": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
]
}
}
}
Sample response body (CHARGEBACK_CREDIT)
This sample is only for programs that are not enabled for Regulation E.JSON
{
"case_token": "my_case_id",
"token": "my_casetransition_id",
"action": "CHARGEBACK_CREDIT",
"reason_code": "28",
"reason_description": "Smaller Amount",
"created_by": "user_name",
"from_state": "OPEN",
"state": "CHARGEBACK_INITIATED",
"assignee": "assignee_name",
"memo": "Text about this dispute",
"failure_reason": "string",
"transition_details": {
"chargeback_details": {
"attached_contents": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
]
}
}
}
Sample request body (CHARGEBACK_NO_CREDIT)
JSON
{
"token": "dispute_case_token",
"action": "CHARGEBACK_NO_CREDIT",
"reason_code": "29",
"created_by": "user_name",
"assignee": "assignee_name",
"memo": "Initiating chargeback",
"transition_details": {
"chargeback_details": {
"attached_contents": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
]
}
}
}
Sample response body (CHARGEBACK_NO_CREDIT)
JSON
{
"case_token": "my_case_id",
"token": "my_casetransition_id",
"action": "CHARGEBACK_N0_CREDIT",
"reason_code": "29",
"reason_description": "Smaller Amount",
"created_by": "user_name",
"from_state": "OPEN",
"state": "CHARGEBACK_INITIATED",
"assignee": "assignee_name",
"memo": "Initiating chargeback",
"failure_reason": "string",
"transition_details": {
"chargeback_details": {
"attached_contents": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
]
}
}
}
Response action/reason code changes
There are some cases where the reason code is changed by the system for either of two reasons:- An error occurred while processing a transition.
- The dispute case transition moved the case to a state different from the desired state.
| Action | Reason Code | Resulting State | Description |
|---|---|---|---|
CHARGEBACK_SUBMIT | 52 | OPEN_WITH_ACTION_REQUIRED | Triggered during an attempt to transition a dispute case with action CHARGEBACK_SUBMIT and reason code 51. Occurs when attempting to transition a Regulation E dispute case that has not granted provisional credit. |
CLOSE | 53 | PENDING_CLOSED | Triggered during an attempt to transition a dispute case with action CLOSED and reason code 42. Occurs for Regulation E cases to indicate that the customer must first notify the cardholder before reverting the credit, as required by Regulation E, and must wait a specified number of days before reverting credit. |
Sample response body (ACTION/REASON CODE CHANGES)
JSON
{
"token": "string",
"case_token": "string",
"reason_code": "51",
"reason_description": "Submit case to the card network",
"created_by": "string",
"from_state": "READY",
"state": "CHARGEBACK_INITIATED",
"action": "CHARGEBACK_SUBMIT",
"memo": "string",
"transition_details": {
"chargeback_details": {
"attached_contents": ["uuid"]
}
}
}
Transition failure response
An error occurs when attempting to transition a dispute case usingCHARGEBACK_SUBMIT when the dispute has no provisional credit granted.
Error response
| Error Code | Error Message | Description |
|---|---|---|
| 400400 | Attempted to close case as case won when the dispute state is not set to CASE_WON | Triggered when an attempt to close a case as CASE_WON without having it be won in the backend lifecycle. |
| 400400 | Cannot write off cases that haven’t granted provisional credit | Triggered during an attempt to transition a case with action CLOSE and reason code 45. Occurs for Regulation E cases if provisional credit has not been granted. Solution: Close the case using WITHDRAW_AND_CLOSE. |
| 400401 | Case is no longer applicable as case lost under RegE | Triggered during an attempt to transition a dispute case with action CLOSE and reason code 42. Occurs for Regulation E cases that are past the Regulation E 45-day time limit.Solution: Close the case with reason code 45. |
| 400400 | Invalid Action for Current State | Triggered during CHARGEBACK_SUBMIT if the program is not Regulation E enabled. Triggered during CHARGEBACK_CREDIT or CHARGEBACK_NO_CREDIT when attempting to use this action to transition a REG_E case. |
| 400400 | Unable to withdraw and close because provisional credit has been granted | Triggered during an attempt to transition a case with WITHDRAW_AND_CLOSE when the provisional credit has been granted. |
| 400400 | Waiting for provisional credit to be reversed before the case can be closed | Triggered during an attempt to transition a case with action CLOSE and reason code 42. Occurs if the case is in PENDING_CLOSED state and the reversal of provision credit has not occurred.Solution: Wait for the provisional credit to be reversed. |
Sample response body (TRANSITION FAILURE RESPONSE)
JSON
{
"token": "string",
"case_token": "string",
"reason_code": "52",
"reason_description": "Provisional credit required",
"created_by": "string",
"from_state": "READY",
"state": "OPEN_WITH_ACTION_REQUIRED",
"action": "CHARGEBACK_SUBMIT",
"memo": "string",
"transition_details": {
"chargeback_details": {
"attached_contents": ["uuid"]
}
}
}
Retrieve dispute case transition
Action:GETEndpoint:
/cases/{token}/transitions/{transition_token}
Retrieve a specific dispute case transition for a specific dispute case.
A dispute case transition is an event that changes the state of a dispute case and triggers other related events. The new state of the dispute case and which related events are triggered is determined by the action defined in the dispute case transition.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the dispute case associated with the transitions you want to retrieve. Send a GET request to /cases to retrieve dispute case tokens.Allowable Values: 36 char max |
| transition_token string Required | Unique identifier of the transition to retrieve. Send a GET request to /cases//transitions to retrieve dispute case transition tokens.Allowable Values: 36 char max |
Retrieve dispute case transition response
See Dispute transition response.Sample response body
JSON
{
"case_token": "string",
"token": "string",
"action": "CREATE",
"reason_code": "44",
"reason_description": "string",
"created_by": "string",
"from_state": "OPEN",
"state": "OPEN",
"assignee": "string",
"memo": "string",
"failure_reason": "string",
"transition_details": {
"chargeback_details": {
"attached_contents": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
]
}
}
}
List dispute case transitions
Action:GETEndpoint:
/cases/{token}/transitions
List existing dispute case transitions for the specified dispute case. This endpoint supports sorting and pagination.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the dispute case associated with the transitions you want to list. Send a GET request to /cases to retrieve dispute case tokens.Allowable Values: 36 char max |
Query parameters
| Fields | Description |
|---|---|
| state string Optional | Filter dispute case transitions that contain the specified resulting state. Allowable Values: OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED |
List dispute case transition response
See Dispute transition response.Sample response body
JSON
{
"count": 2,
"start_index": 0,
"end_index": 1,
"is_more": false,
"data": [
{
"case_token": "my_case_id",
"token": "my_casetransition_id1",
"action": "CHARGEBACK_CREDIT",
"reason_code": "28",
"reason_description": "Smaller Amount",
"created_by": "string",
"from_state": "OPEN",
"state": "OPEN",
"assignee": "string",
"memo": "Initiating chargeback",
"failure_reason": "string",
"transition_details": {
"chargeback_details": {
"attached_contents": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
]
}
}
},
{
"case_token": "my_case_id",
"token": "my_casetransition_id2",
"action": "ASSIGN",
"reason_code": "05",
"reason_description": "Under Review",
"created_by": "user_name",
"from_state": "READY",
"state": "OPEN",
"assignee": "string",
"memo": "Assigned to user",
"failure_reason": "string",
"transition_details": {
"chargeback_details": {
"attached_contents": [
"4fa85f64-5719-4561-b3fa-2c963f66abc9"
]
}
}
}
]
}
Create network dispute transition
Action:POSTEndpoint:
/cases/{token}/disputetransitions
Create a network dispute transition.
A network dispute transition is an event that changes the network state of a dispute and triggers other related events. The new state of the dispute within the network dispute lifecycle and which related events are triggered is determined by the action defined in the network dispute transition.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the dispute associated with the transition you want to create. Send a GET request to /cases to retrieve case tokens.Allowable Values: 36 char max |
Request body
| Fields | Description |
|---|---|
| action string Required | Action to take: - RESPOND_WITH_PREARB: Action to move a dispute to prearbitration with PULSE.- RESPOND_WITH_ARB: Action to move a prearbitration disputes to arbitration.- RESPOND_WITH_PREARB_RESPONSE: Respond to the prearbitration response.- ACCEPT_AND_CLOSE: Action to accept the dispute decision and close the dispute.- CLOSE_WITH_CASE_WON: Close with case won dispute transition.- CLOSE_WITH_NETWORK_REJECTED: Close with network rejected.- REPRESENTMENT_RECEIVED: Indicates that representment was received.Allowable Values: RESPOND_WITH_PREARB, RESPOND_WITH_ARB, RESPOND_WITH_PREARB_RESPONSE, ACCEPT_AND_CLOSE, CLOSE_WITH_CASE_WON, CLOSE_WITH_NETWORK_REJECTED, REPRESENTMENT_RECEIVED |
| created_by string Optional | Indicates the user who is creating the transition. Allowable Values: 255 char max |
| memo string Optional | A memo regarding the transaction. Allowable Values: 16777215 char max |
| network_details object Conditionally required | Card network details. Allowable Values: See The network_details object table |
The network_details object
Depending on the transition, contains theprearbitration_details object or the arbitration_details object.
| Fields | Description |
|---|---|
| prearbitration_details object Optional | Object defining the prearbitration details. Allowable Values: See The prearbitration_details object table |
| prearbitration_response_details object Optional | Object defining the prearbitration response details. Allowable Values: See The prearbitration_response_details object table |
| arbitration_details object Optional | Object defining the arbitration details. Allowable Values: See The arbitration_details object table |
| representment_details object Optional | Object defining the network state details. Allowable Values: See The network_state_details object table |
| case_close_details string Optional | The new dispute state. Allowable Values: See The case_close_details object table |
The prearbitration_details object
The details for prearbitration.| Fields | Description |
|---|---|
| amount number Required | Amount in dispute. Allowable Values: 32 bytes |
| attached_contents string Optional | Content token for documents to be submitted to the network at the current dispute state. Allowable Values: 256 char max |
| why_are_you_initiating_prearbitration string Required | The reason you are initiating prearbitration. Allowable Values: 255 char max |
| are_you_providing_new_information boolean Required | Indicates whether this state change includes new information useful for the dispute. Allowable Values: true, false |
| summary_of_new_information string Conditionally required. | A summary of the new information provided. Allowable Values: 255 char max |
The prearbitration_response_details object
The details for prearbitration response.| Fields | Description |
|---|---|
| attached_contents string Optional | Content token for documents to be submitted to the network at the current dispute state. Allowable Values: 255 char max |
| prearbitration_response_decision string Required | The prearbitration response decision. Allowable Values: ACCEPT_PARTIAL, DECLINE |
| amount string Required | The partial acceptance amount. Allowable Values: 32 bytes |
The arbitration_details object
The details for arbitration.| Fields | Description |
|---|---|
| attached_contents string Optional | Content token for documents to be submitted to the network at the current dispute state. Allowable Values: 255 char max |
The representment_details object
The details for representment transition.| Fields | Description |
|---|---|
| amount number Required | Amount in dispute. Allowable Values: Min: 0.1 |
| attached_contents string Optional | Content token for documents to be submitted to the network at the current dispute state. Allowable Values: 255 char max |
The case_close_details object
The details for case close transition details.| Fields | Description |
|---|---|
| write_off boolean Optional | Indicates whether the write-off due to the case lost happened. Allowable Values: true, false |
The network_details_response object
Depending on the transition, contains theprearbitration_details object or the arbitration_details object.
| Fields | Description |
|---|---|
| prearbitration_details object Optional | Object defining the prearbitration details. Allowable Values: See The prearbitration_details object table |
| prearbitration_response_details object Optional | Object defining the prearbitration response details. Allowable Values: See The prearbitration_response_details object table |
| arbitration_details object Optional | Object defining the arbitration details. Allowable Values: See The arbitration_details object table |
| representment_details object Optional | Object defining the network state details. Allowable Values: See The network_state_details object table |
| network_state_details string Optional | A JSON object, containing the details, received from the network. Allowable Values: Valid JSON object |
| dispute_state string Optional | After the case’s state has been moved to CHARGEBACK_INITIATED, this field will be updated as it progresses in the backend lifecycle.Allowable Values: INITIATED, REPRESENTMENT, PRE_ARBITRATION, ARBITRATION, CASE_WON, CLOSED, NETWORK_REJECTED, CASE_LOST, WRITTEN_OFF_ISSUER, WRITTEN_OFF_PROGRAM |
| case_close_details string Optional | New dispute case state. Allowable Values: See The case_close_details object table |
Sample request with prearbitration
JSON
{
"action": "RESPOND_WITH_PREARB",
"created_by": "user_name",
"memo": "pre-arb transition for testing",
"network_details": {
"prearbitration_details": {
"amount": 112.0,
"attached_contents": [
"content_token"
]
},
"prearbitration_response_details": {
"attached_contents": [
"string"
],
"prearb_response_decision": "ACCEPT_PARTIAL",
"amount": "string"
},
"arbitration_details": {
"attached_contents": [
"string"
]
},
"representment_details": {
"amount": 0.10,
"attached_contents": [
"string"
]
},
"case_close_details": {
"write_off": true,
"write_off_actor": "PROGRAM"
}
}
}
Sample response with prearbitration
JSON
{
"token": "my_dispute_transition_token",
"created_time": "2024-07-20T22:10:57.423Z",
"last_modified_time": "2024-07-20T22:10:57.423Z",
"case_token": "my_case_token",
"action": "RESPOND_WITH_PREARB",
"created_by": "user_name",
"memo": "pre-arb transition for testing",
"from_network_status": "string",
"to_network_status": "string",
"network_dispute_id": "network_dispute_id",
"system_error_message": "string",
"network_error_message": "string",
"network_details": {
"prearbitration_details": {
"amount": 112.5,
"attached_contents": [
"content_token"
]
},
"prearbitration_response_details": {
"attached_contents": [
"content_token"
],
"prearb_response_decision": "ACCEPT_PARTIAL",
"amount": "string"
},
"arbitration_details": {
"attached_contents": [
"content_token"
]
},
"representment_details": {
"amount": 112.5,
"attached_contents": [
"content_token"
]
},
"network_state_details": "string",
"dispute_state": "INITIATED",
"case_close_details": {
"write_off": true,
"write_off_actor": "PROGRAM"
}
}
}
Sample request with arbitration
JSON
{
"action": "RESPOND_WITH_ARB",
"created_by": "user_name",
"memo": "arbitration response transition response for testing",
"network_details": {
"prearbitration_details": {
"amount": 112.0,
"attached_contents": [
"content_token"
]
},
"prearbitration_response_details": {
"attached_contents": [
"string"
],
"prearb_response_decision": "ACCEPT_PARTIAL",
"amount": "string"
},
"arbitration_details": {
"attached_contents": [
"string"
]
},
"representment_details": {
"amount": 0.1,
"attached_contents": [
"string"
]
},
"case_close_details": {
"write_off": true,
"write_off_actor": "PROGRAM"
}
}
}
Sample response with arbitration
JSON
{
"token": "my_dispute_transition_token",
"created_time": "2024-07-20T22:10:57.423Z",
"last_modified_time": "2024-07-20T22:10:57.423Z",
"case_token": "my_case_token",
"action": "RESPOND_WITH_ARB",
"created_by": "user_name",
"memo": "Arbitration response transition response for testing",
"from_network_status": "string",
"to_network_status": "string",
"network_dispute_id": "network_dispute_id",
"system_error_message": "string",
"network_error_message": "string",
"network_details": {
"prearbitration_details": {
"amount": 112.5,
"attached_contents": [
"content_token"
]
},
"prearbitration_response_details": {
"attached_contents": [
"content_token"
],
"prearb_response_decision": "ACCEPT_PARTIAL",
"amount": "string"
},
"arbitration_details": {
"attached_contents": [
"content_token"
]
},
"representment_details": {
"amount": 112.5,
"attached_contents": [
"content_token"
]
},
"network_state_details": "string",
"dispute_state": "INITIATED",
"case_close_details": {
"write_off": true,
"write_off_actor": "PROGRAM"
}
}
}
Sample accept and close dispute request
JSON
{
"action": "ACCEPT_AND_CLOSE",
"created_by": "user_name",
"memo": "accept and close",
"network_details": {
"prearbitration_details": {
"amount": 112.0,
"attached_contents": [
"content_token"
]
},
"prearbitration_response_details": {
"attached_contents": [
"string"
],
"prearb_response_decision": "ACCEPT_PARTIAL",
"amount": "string"
},
"arbitration_details": {
"attached_contents": [
"string"
]
},
"representment_details": {
"amount": 0.1,
"attached_contents": [
"string"
]
},
"case_close_details": {
"write_off": true,
"write_off_actor": "PROGRAM"
}
}
}
Sample accept and close dispute response
JSON
{
"token": "my_dispute_transition_token",
"created_time": "2024-07-20T22:10:57.423Z",
"last_modified_time": "2024-07-20T22:10:57.423Z",
"case_token": "my_case_token",
"action": "ACCEPT_AND_CLOSE",
"created_by": "user_name",
"memo": "accept and close",
"from_network_status": "string",
"to_network_status": "string",
"network_dispute_id": "network_dispute_id",
"system_error_message": "string",
"network_error_message": "string",
"network_details": {
"prearbitration_details": {
"amount": 112.5,
"attached_contents": [
"content_token"
]
},
"prearbitration_response_details": {
"attached_contents": [
"content_token"
],
"prearb_response_decision": "ACCEPT_PARTIAL",
"amount": "string"
},
"arbitration_details": {
"attached_contents": [
"content_token"
]
},
"representment_details": {
"amount": 112.5,
"attached_contents": [
"content_token"
]
},
"network_state_details": "string",
"dispute_state": "INITIATED",
"case_close_details": {
"write_off": true,
"write_off_actor": "PROGRAM"
}
}
}
Sample close with case won dispute request
JSON
{
"action": "CLOSE_WITH_CASE_WON",
"created_by": "user_name",
"memo": "close with case won",
"network_details": {
"prearbitration_details": {
"amount": 112.0,
"attached_contents": [
"content_token"
],
"why_are_you_initiating_prearbitration": "string",
"are_you_providing_new_information": true,
"summary_of_new_information": "string"
},
"prearbitration_response_details": {
"attached_contents": [
"string"
],
"prearb_response_decision": "ACCEPT_PARTIAL",
"amount": "string"
},
"arbitration_details": {
"attached_contents": [
"string"
]
},
"representment_details": {
"amount": 0.10,
"attached_contents": [
"string"
]
},
"case_close_details": {
"write_off": true,
"write_off_actor": "PROGRAM"
}
}
}
Sample close with case won dispute response
JSON
{
"token": "my_dispute_transition_token",
"created_time": "2024-07-20T22:10:57.423Z",
"last_modified_time": "2024-07-20T22:10:57.423Z",
"case_token": "my_case_token",
"action": "CLOSE_WITH_CASE_WON",
"created_by": "user_name",
"memo": "close with case won",
"from_network_status": "string",
"to_network_status": "string",
"network_dispute_id": "network_dispute_id",
"system_error_message": "string",
"network_error_message": "string",
"network_details": {
"prearbitration_details": {
"amount": 112.5,
"attached_contents": [
"content_token"
]
},
"prearbitration_response_details": {
"attached_contents": [
"content_token"
],
"prearb_response_decision": "ACCEPT_PARTIAL",
"amount": "string"
},
"arbitration_details": {
"attached_contents": [
"content_token"
]
},
"representment_details": {
"amount": 112.5,
"attached_contents": [
"content_token"
]
},
"network_state_details": "string",
"dispute_state": "INITIATED",
"case_close_details": {
"write_off": true,
"write_off_actor": "PROGRAM"
}
}
}
Create ACCEPT_AND_CLOSE transition
This transition moves the network dispute state toCASE_LOST sets the case transition to CLOSE with reason code 42 (Case Lost).
For Regulation E dispute cases, if the case is past 45 days, the callee must specify both write_off and write_off_actor. When this occurs, the dispute state is set to WRITE_OFF_PROGRAM and sets the case transition to CLOSE with reason code 45 (Write off Program).
Query parameters
| Fields | Description |
|---|---|
| action string Required | Action taken. Allowable Values: ACCEPT_AND_CLOSE |
| created_by string Required | Identifier or name of the user who created the transition. Allowable Values: 255 char max |
| memo string Required | Memo regarding the transaction. Allowable Values: 16777215 char max |
| close_case_details.write_off boolean Conditionally required | Required if the 45-day Regulation E time limit has expired. Allowable Values: true, false |
| close_case_details.write_off_actor string Conditionally required | Triggers a CLOSE case transition with reason code 45. Required if the 45-day Regulation E time limit has expired.Allowable Values: PROGRAM |
Response fields
See the Network dispute transition response table.Error codes
| Error Code | Error Message | Description |
|---|---|---|
| 400301 | Case is RegE and can only be accepted and closed with write off after it expires | Triggered when attempting to do an ACCEPT_AND_CLOSE action without write-off information for a case that has exceeded the 45-day milestone. |
Sample ACCEPT_AND_CLOSE transition request
JSON
{
"action": "ACCEPT_AND_CLOSE",
"created_by": "string",
"memo": "string",
"network_details": {
"case_close_details": {
"write_off": true,
"write_off_actor": "PROGRAM"
}
}
}
Sample ACCEPT_AND_CLOSE transition response
JSON
{
"token": "string",
"case_token": "string",
"action": "ACCEPT_AND_CLOSE",
"created_by": "string",
"memo": "string",
"from_network_status": "string",
"to_network_status": "string",
"network_dispute_id": "string",
"system_error_message": "string",
"network_error_message": "string",
"created_time": "timestamp",
"last_modified_time": "timestamp",
"network_details": {
"case_close_details": {
"write_off": true,
"write_off_actor": "PROGRAM"
}
}
}
Create CLOSE_WITH_CASE_WON transition
For Regulation E and non-Regulation E network dispute cases, the dispute state is set toCASE_WON and a CLOSE case transition with reason code 41 (Case Won) is created.
Sample CLOSE_WITH_CASE_WON transition request
JSON
{
"action": "CLOSE_WITH_CASE_WON",
"created_by": "string",
"memo": "string"
}
Sample CLOSE_WITH_CASE_WON transition response
JSON
{
"token": "string",
"case_token": "string",
"action": "ACCEPT_AND_CLOSE",
"created_by": "string",
"memo": "string",
"from_network_status": "string",
"to_network_status": "string",
"network_dispute_id": "string",
"system_error_message": "string",
"network_error_message": "string",
"created_time": "timestamp",
"last_modified_time": "timestamp",
"network_details": {
"case_close_details": {
"write_off": true,
"write_off_actor": "PROGRAM"
}
}
}
Retrieve network dispute transition
Action:GETEndpoint:
/cases/{token}/disputetransitions/{transition_token}
Retrieve a specific network dispute transition for a specific dispute.
A network dispute transition is an event that changes the state of a dispute and triggers other related events. The new state of the dispute and which related events are triggered is determined by the action defined in the transition.
URL path parameters
| Fields | Description |
|---|---|
| transition_token string Required | Unique identifier of the transition to retrieve. Allowable Values: 36 char max Send a GET request to /cases//transitions to retrieve dispute transition tokens. |
Response fields
See the Network dispute transition response table.Sample response body
JSON
{
"token": "my_network_transition_id1",
"created_time": "2024-07-21T19:32:01.326Z",
"last_modified_time": "2024-07-21T19:32:01.326Z",
"case_token": "my_case_token",
"action": "CHARGEBACK_CREDIT",
"created_by": "user_name",
"memo": "Initiating chargeback",
"from_network_status": "string",
"to_network_status": "string",
"network_dispute_id": "string",
"system_error_message": "string",
"network_error_message": "string",
"network_details": {
"prearbitration_details": {
"amount": 120.0,
"attached_contents": [
"string"
]
},
"prearbitration_response_details": {
"attached_contents": [
"string"
],
"prearb_response_decision": "ACCEPT_PARTIAL",
"amount": "string"
},
"arbitration_details": {
"attached_contents": [
"string"
]
},
"representment_details": {
"amount": 120.0,
"attached_contents": [
"string"
]
},
"network_state_details": "string",
"dispute_state": "CHARGEBACK_INITIATED",
"case_close_details": {
"write_off": true,
"write_off_actor": "PROGRAM"
}
}
}
List network dispute transitions
Action:GETEndpoint:
/cases/{token}/disputetransitions
List existing network dispute transitions for the specified dispute, including details of the merchant/acquirer responses during the backend resolution process. This endpoint supports sorting and pagination.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the dispute associated with the transitions you want to list. Send a GET request to /cases to retrieve dispute tokens.Allowable Values: 36 char max |
List network dispute transitions response fields
See the Network dispute transition response table.Sample response body
JSON
{
"count": 0,
"start_index": 0,
"end_index": 0,
"is_more": true,
"data": [
{
"token": "string",
"created_time": "2024-07-21T17:37:37.792Z",
"last_modified_time": "2024-07-21T17:37:37.792Z",
"case_token": "string",
"action": "SUBMIT",
"created_by": "string",
"memo": "string",
"from_network_status": "string",
"to_network_status": "string",
"network_dispute_id": "string",
"system_error_message": "string",
"network_error_message": "string",
"network_details": {
"prearbitration_details": {
"amount": 0,
"attached_contents": [
"string"
]
},
"prearbitration_response_details": {
"attached_contents": [
"string"
],
"prearb_response_decision": "ACCEPT_PARTIAL",
"amount": "string"
},
"arbitration_details": {
"attached_contents": [
"string"
]
},
"representment_details": {
"amount": 0.1,
"attached_contents": [
"string"
]
},
"network_state_details": "string",
"dispute_state": "INITIATED",
"case_close_details": {
"write_off": true,
"write_off_actor": "PROGRAM"
}
}
}
]
}
Create dispute case content
Action:POSTEndpoint:
/cases/{token}/contents
Upload and store documents related to a dispute, such as supporting evidence or KYC verification documents.
The supported document formats are PDF, TIFF, and JPEG. Each uploaded file is restricted to 2 MB.
URL path parameter
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the dispute case. Send a GET request to /cases to retrieve dispute case tokens.Allowable Values: 36 char max |
Request body
| Fields | Description |
|---|---|
| document_category string Required | Category of the document. The category is also forwarded to PULSE. Allowable Values: AFFIDAVIT_FRAUD, AUTHORIZATION_RECORD, BANK_STATEMENT, CANCELLED_CHECK, CARDHOLDER_LETTER, CREDIT_VOUCHER, FULFILLMENT, ISSUER_CERTIFICATION, MERCHANT_LETTER, NETWORK_DOCUMENT, NETWORK_EXHIBIT, OTHERS, RECEIPT, SALES_DRAFT, SECOND_OPTION, UPDATED_CARDHOLDER_LETTER, UPDATED_MERCHANT_LETTER |
| document_name string Required | Name of the document. Allowable Values: Must include the file extension, as appropriate for a supported file format: .pdf, .tiff, or .jpeg. |
| document_data binary Required | Base64-encoded file. Allowable Values: 2 MB max size |
Create content response body
| Fields | Description |
|---|---|
| token string Returned | Unique identifier of the document. Allowable Values: 36 char max |
| case_token string Returned | Unique identifier of the dispute case you want to upload documents against. Allowable Values: 36 char max |
| document_name string Returned | Name of the document. Allowable Values: 255 char max |
| document_category string Returned | Type of document. Allowable Values: AFFIDAVIT_FRAUD, AUTHORIZATION_RECORD, BANK_STATEMENT, CANCELLED_CHECK, CARDHOLDER_LETTER, CREDIT_VOUCHER, FULFILLMENT, ISSUER_CERTIFICATION, MERCHANT_LETTER, NETWORK_DOCUMENT, NETWORK_EXHIBIT, OTHERS, RECEIPT, SALES_DRAFT, SECOND_OPTION, UPDATED_CARDHOLDER_LETTER, UPDATED_MERCHANT_LETTER |
| document_content_type string Returned | Content type of the document. Allowable Values: application/pdf, image/tiff, image/jpeg |
| network_processing_type string Returned | Indicates the current status of the document at the network: - SUBMITTED – Indicates it has been submitted to the network using the Dispute Case Transition or Network Dispute Transition endpoint.- RECEIVED – Indicates that the document has been downloaded from the network, which occurs when the acquirer uploaded a document to support their claim.Allowable Values: SUBMITTED, RECEIVED |
| network_processing_phase string Returned | Indicates the status of the document in the dispute lifecycle. Allowable Values: INITIATED, REPRESENTMENT, PRE_ARBITRATION |
| network_processing_time datetime Returned | Date and time when the document has either been submitted by the user or received from the network. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
| created_time datetime Returned | Date and time when the dispute was created. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
| updated_time datetime Returned | Date and time when the dispute was last modified. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
| download_link string Returned | Link to download the file if it is included in the request. This only applies to the GET case content by token endpoint.Allowable Values: Valid URI |
Sample request body
JSON
Content-Type: multipart/form-data; boundary=marqeta_file_separator
Cache-Control: no-cache
--marqeta_file_separator
Content-Type: application/json; Content-Disposition: form-data; name="body"
{
"document_category": "RECEIPT",
"document_name": "receipt.pdf",
"document_data": "string"
}
--marqeta_file_separator
Content-Type: image/jpeg; Content-Disposition: form-data; name="file"
file=@/Users/username/Downloads/online-receipt-location.jpg
--marqeta_file_separator--
Sample response body
JSON
{
"token": "my_content_token",
"case_token": "my_case_token",
"document_name": "string",
"document_category": "RECEIPT",
"document_content_type": "application/pdf",
"network_processing_type": "SUBMITTED",
"network_processing_phase": "INITIATED",
"network_processing_time": "2025-02-01T20:22:34.913Z",
"created_time": "2025-02-01T20:22:34.913Z",
"updated_time": "2025-02-01T20:22:34.913Z",
"download_link": "download_link"
}
List contents uploaded against a dispute case
Action:GETEndpoint:
/cases/{token}/contents
Get a list of uploaded contents for the specified dispute case.
URL path parameter
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the dispute case for which to return the contents list. Send a GET request to /cases to retrieve dispute case tokens.Allowable Values: 36 char max |
List contents response
For response details, see Create content response body.Sample response body
JSON
{
"count": 2,
"start_index": 0,
"end_index": 1,
"is_more": false,
"data": [
{
"token": "my_content_token",
"case_token": "my_case_token",
"document_name": "receipt.pdf",
"document_category": "RECEIPT",
"document_content_type": "image/jpeg",
"network_processing_type": "RECEIVED",
"network_processing_phase": "INITIATED",
"network_processing_time": "2025-01-19T13:22:07Z",
"created_time": "2025-01-19T13:22:07Z",
"updated_time": "2025-02-19T12:22:07Z",
"download_link": "uri"
},
{
"token": "my_content_token",
"case_token": "my_case_token",
"document_name": "receipt.pdf",
"document_category": "RECEIPT",
"document_content_type": "image/jpeg",
"network_processing_type": "RECEIVED",
"network_processing_phase": "INITIATED",
"network_processing_time": "2025-01-19T13:22:07Z",
"created_time": "2025-01-19T13:22:07Z",
"updated_time": "2025-02-19T14:22:07Z",
"download_link": "uri"
}
]
}
Retrieve content and status
Action:GETEndpoint:
/cases/{case_token}/contents/{token}
Get a specific document and its status, and optionally start returning a temporary link to download the file.
If you include the download_link=true query parameter, a temporary link is returned in the response that you can use to download the document. The link is active for 15 minutes; after that time, you must call this endpoint again to generate a new link.
URL path parameters
| Fields | Description |
|---|---|
| case_token string Required | Unique identifier of the dispute case for which to return the contents list. Send a GET request to /cases to retrieve dispute case tokens.Allowable Values: 36 char max |
| token string Required | Unique identifier of the document. Allowable Values: 36 char max |
| download_link string Optional | If set to true, this parameter causes a download link for the document to be included in the response.Allowable Values: true, false |
Response body
For response details, see Create content response body.Sample response body
JSON
{
"token": "my_content_token",
"case_token": "my_case_token",
"document_name": "letter.pdf",
"document_category": "CARDHOLDER_LETTER",
"document_content_type": "string",
"network_processing_type": "SUBMITTED",
"network_processing_phase": "INITIATED",
"network_processing_time": "2025-02-02T23:06:18.429Z",
"created_time": "2025-02-02T23:06:18.429Z",
"updated_time": "2025-02-02T23:06:18.429Z",
"download_link": "uri"
}
Update document
Action:PUTEndpoint:
/cases/{token}/contents/{content_token}
Change the name of a document or category. If the content has already been processed and is currently SUBMITTED or RECEIVED, an error is returned.
URL path parameter
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the dispute case for which to return the contents list. Send a GET request to /cases to retrieve dispute case tokens.Allowable Values: 36 char max |
| content_token string Required | Content token that identifies the document. Allowable Values: 36 char max |
Body field details
| Fields | Description |
|---|---|
| document_name string Required | Name of the document. Allowable Values: 255 char max |
| document_category string Required | Category of the document. Allowable Values: AFFIDAVIT_FRAUD, AUTHORIZATION_RECORD, BANK_STATEMENT, CANCELLED_CHECK, CARDHOLDER_LETTER, CREDIT_VOUCHER, FULFILLMENT, ISSUER_CERTIFICATION, MERCHANT_LETTER, NETWORK_DOCUMENT, NETWORK_EXHIBIT, OTHERS, RECEIPT, SALES_DRAFT, SECOND_OPTION, UPDATED_CARDHOLDER_LETTER, UPDATED_MERCHANT_LETTER |
Update document response body
For response details, see Create content response body.Sample request body
JSON
{
"document_name": "receipt.pdf",
"document_category": "RECEIPT"
}
Sample response body
JSON
{
"token": "my_content_token",
"case_token": "my_case_token",
"document_name": "letter.pdf",
"document_category": "CARDHOLDER_LETTER",
"document_content_type": "string",
"network_processing_type": "SUBMITTED",
"network_processing_phase": "INITIATED",
"network_processing_time": "2025-02-02T23:06:18.429Z",
"created_time": "2025-02-02T23:06:18.429Z",
"updated_time": "2025-02-02T23:06:18.429Z",
"download_link": "uri"
}
Delete a document
Action:DELETEEndpoint:
/cases/{token}/contents/{content_token}
Delete a dispute case document. If the document has already been processed with the network_processing_type set to SUBMITTED or RECEIVED, an error is returned.
URL path parameter
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the dispute case. Allowable Values: 255 char max |
| content_token string Required | Unique identifier of the content to delete. Allowable Values: 255 char max |
Delete content response
This endpoint returns a200 response code and success in the response body.
Sample response body
JSON
{
"status": "success"
}
Create dispute case action
Action:POSTEndpoint:
/cases/{token}/actions
Create a dispute case action.
Path parameter
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the dispute case. Allowable Values: 36 char max |
Body field details
| Fields | Description |
|---|---|
| action_type string Required | - GRANT_PROVISIONAL_CREDIT - Grant provisional credit and trigger the event.- REVERT_PROVISIONAL_CREDIT - Revert a previously granted provisional credit and trigger an event.Allowable Values: GRANT_PROVISIONAL_CREDIT, REVERT_PROVISIONAL_CREDIT |
| created_by string Required | Indicates the actor who created the dispute case action. Allowable Values: 255 char max |
Response body
| Fields | Description |
|---|---|
| token string Returned | Unique identifier of the dispute case. Allowable Values: 36 char max |
| action_type string Returned | Action taken. Allowable Values: 255 char max |
| created_by string Returned | Indicates the actor who created the dispute case action. Allowable Values: 255 char max |
Sample request
JSON
{
"action_type": "GRANT_PROVISIONAL_CREDIT",
"created_by": "string"
}
Sample response
JSON
{
"case_token": "<my_case_token>",
"action_type": "GRANT_PROVISIONAL_CREDIT",
"created_by": "string"
}
Create event
Action:POSTEndpoint:
/cases/{token}/events
Create a dispute case event.
If you are a Managed by Marqeta (MxM) customer or a hybrid card program and you are submitting a dispute that falls under Regulation E, you must create a case event with evidence. For instructions on creating a case event with evidence, see Disputes Evidence Collection.
Path parameter
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the dispute case. Allowable Values: 36 char max |
Body field details
| Fields | Description |
|---|---|
| name string Required | Name of the event. Allowable Values: 255 char max |
| event_date datetime Optional | Date and time when the event took place. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ssZ |
| created_by string Required | Indicates the actor creating the event. Allowable Values: 255 char max |
Response body
| Fields | Description |
|---|---|
| token string Returned | Unique identifier of the event. Allowable Values: 36 char max |
| case_token string Returned | Unique identifier of the associated case that triggered this event. Allowable Values: 36 char max |
| name string Returned | Name of the event. Allowable Values: 255 char max |
| category string Returned | Category to which the event belongs. Allowable Values: REG_E |
| created_by string Required | Indicates the actor who created the event. Allowable Values: 255 char max |
| event_date datetime Returned | Date and time when the event took place. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ssZ |
| created_time datetime Returned | Date and time when the event was created. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ssZ |
Sample request
JSON
{
"name": "string",
"created_by": "string",
"event_date": "timestamp",
}
Sample response
JSON
{
"token": "uuid",
"case_token": "string",
"name": "string",
"category": "string",
"created_by": "string",
"event_date": "timestamp",
"created_time": "timestamp"
}
List events
Action:GETEndpoint:
/cases/{token}/events
List events.
Path parameter
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the dispute case. Allowable Values: 36 char max |
Response body
| Fields | Description |
|---|---|
| token string Returned | Unique identifier of the event. Allowable Values: 36 char max |
| case_token string Returned | Unique identifier of the associated case that triggered this event. Allowable Values: 36 char max |
| name string Returned | Name of the event. Allowable Values: 255 char max |
| category string Returned | Category to which the event belongs. Allowable Values: REG_E |
| created_by string Required | Identifier or name of the user creating the event. Allowable Values: 255 char max |
| event_date datetime Returned | Date and time when the event took place. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ssZ |
| created_time datetime Returned | Date and time when the event was created. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ssZ |
Sample response
JSON
{
"count": 30,
"start_index": 0,
"end_index": 29,
"is_more": true,
"data": [
{
"case_token": "string",
"category": "string",
"sub_category": "string",
"milestone": "string",
"next_milestone_due_date": "timestamp",
"created_time": "timestamp",
"last_modified_time": "timestamp"
}
]
}
List dispute case milestones
Action:GETEndpoint:
/cases/{token}/milestones
List dispute case milestones.
Path parameter
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the dispute case. Allowable Values: 36 char max |
Body field details
| Fields | Description |
|---|---|
| name string Required | Name of the event. Allowable Values: 255 char max |
| event_date datetime Optional | Date and time when the event took place. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ssZ |
| created_by string Required | Identifier or name of the user creating the event. Allowable Values: 255 char max |
Response body
| Fields | Description |
|---|---|
| case_token string Returned | Unique identifier of the associated case that triggered this event. Allowable Values: 36 char max |
| milestone string Required | Event milestone. Allowable Values: 255 char max |
| next_milestone_due_date datetime Returned | Date that the next milestone is due. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ssZ |
| created_time datetime Returned | Date and time when the event was created. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ssZ |
| last_modified_time datetime Returned | Date and time when the event was last modified. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ssZ |
Sample response
JSON
{
"count": 30,
"start_index": 0,
"end_index": 29,
"is_more": true,
"data": [
{
"case_token": "string",
"milestone": "string",
"next_milestone_due_date": "timestamp",
"created_time": "timestamp",
"last_modified_time": "timestamp"
}
]
}