Case Management

Use the /cases endpoint to manage transaction disputes. A case stores metadata about the state of the case. The Marqeta platform manages the state of each case and transitions (or changes) the state of the case based on specific actions. You can also upload supporting documents and associate them with a specific case.

Each case object includes a type field that defines the purpose of the case. The DISPUTE type initiates a review of a transaction that is in dispute. Qualifying disputes result in the creation of a chargeback.

Create case

Action: POST
Endpoint: /cases

Create a new case by specifying the type and including the type-specific details object.

Body field details

Name Type Required? Description Allowable Values
token string No The unique identifier of the case.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.
36 char max
type string Yes The type of case. DISPUTE
dispute_details object Yes Specifies the disputed transaction and the reason for the dispute.
memo string No Free-form comments about the case. 512 char max

The dispute_details object

Include this object in your request if the case type is DISPUTE.

Name Type Required? Description Allowable Values
original_transaction_token string Yes The token of the original transaction in dispute. Existing transaction token.
dispute_amount decimal Yes The amount of funds in dispute. Must be less than or equal to the original transaction amount.
dispute_reason string Yes The code describing the reason for the dispute. See "The dispute_details.dispute_reason field".

The dispute_details.dispute_reason field

The following table describes the possible values for the dispute_details.dispute_reason field.

Dispute Reason Description
SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_RECEIVED The goods or services were not provided.
CANCELLED_RECURRING_TRANSACTION A recurring transaction was cancelled.
NOT_AS_DESCRIBED_OR_DEFECTIVE_MERCHANDISE The merchandise was not as described or defective.
FRAUD_MULTIPLE_TRANSACTIONS An installment charge was made incorrectly.
FRAUD_TRANSACTION An additional transaction at a merchant where the card holder made a previous purchase is fraudulent.
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.
LATE_PRESENTMENT The card network cannot verify that the transaction amount was deposited within 30 days.
TRANSACTION_NOT_RECOGNIZED The transaction was not recognized.
INCORRECT_CURRENCY_OR_TRANSACTION_CODE The amount of the transaction in a converted currency is incorrect.
INCORRECT_TRANSACTION_AMOUNT_OR_ACCOUNT_NUMBER The transaction amount is incorrect.
NOT_AUTHORIZED_CARD_PRESENT An unauthorized user initiated the transaction and the card was present.
NOT_AUTHORIZED_CARD_ABSENT An unauthorized user initiated the transaction and the card was not present.
CREDIT_NOT_PROCESSED A credit was not processed.
NON_RECEIPT_OF_CASH_OR_LOAD_TRANSACTION_VALUE_AT_ATM The cardholder did not receive the full cash withdrawal or received only partial amount.

The state field (response only)

The state of the case.

New cases begin in the OPEN state and can change to other states based on actions. Actions are defined in case transition events, which are managed by the Marqeta platform. Depending on the action, the state of a case changes to represent its updated status. For example, the Marqeta platform can transition a case in the OPEN state to the READY state using a transition event with the REVIEW action.

Note: Actions are only associated with the case transition event, not the case itself. For more information on actions that can be performed on a case, see "The actions field (response only)" on this page.

State Description
OPEN The case was created.
CLOSED The case was closed.
READY The case is ready for review.
CHARGEBACK_INITIATED A chargeback was initiated based on the case.
CHARGEBACK_CREATED A chargeback was created based on this case.

Sample request body

{
"token": "my_case_id",
"type": "DISPUTE", 
"dispute_details":{         
"original_transaction_token": "111",
"dispute_amount": 100.00,           
"dispute_reason": "FRAUD",
},
"memo": "Multiple browser submission"           
}

Sample response body

{
"token": "my_case_id",
"type": "DISPUTE", 
"dispute_details":{         
"original_transaction_token": "111",
"dispute_amount": 100.00,           
"currency_code": "USD",
"dispute_reason": "FRAUD",
},
"memo": "Multiple browser submission",
"state": "OPEN",
"folder_id": "123456",
"user_token": "my_user_123",
"created_time": "2018-03-19T13:22:07Z",
"last_modified_time": "2018-03-19T13:22:07Z"      
}


Retrieve case

Action: GET
Endpoint: /cases/{token}

Retrieve a specific case.

Path parameters

Name Type Required? Description Allowable Values
token string Yes The token of the case to retrieve. Existing case token.

Query parameters

Name Type Required? Description Allowable Values
create_access_token boolean No Set to true to include a new folder access token in the response; you can use the access token to manage documents associated with the case. The token expires after one hour. true | false

Default: false
create_shared_link boolean No Set to true to include a new shared link in the response; you can use the shared link to view documents associated with the case. The link expires after one hour. true | false

Default: false

Sample response body

{
"token": "my_case_id", 
"type": "DISPUTE",
"dispute_details": {         
"original_transaction_token": "111",
"dispute_amount": 100.00,           
"currency_code": "USD",
"dispute_reason": "FRAUD",
"chargeback_token": "my_chargeback_id"
},
"memo": "Multiple browser submission",
"state": "READY",
"assignee": "janes",
"folder_id": "123456",
"folder_access_token": "abcdeffedcba12345678900987654321",
"folder_shared_link": "h9ygyjqgd11wpfnf3cp6exk5ywjo065l",
"user_token": "my_user_123",
"created_time": "2018-03-19T13:22:07Z",
"last_modified_time": "2018-03-20T09:22:07Z"
}  


List cases

Action: GET
Endpoint: /cases

List existing cases. This endpoint supports sorting and pagination.

Query parameters

Name Type Required? Description Allowable Values
type string No Returns cases of the specified type. DISPUTE
original_transaction_token string No Returns cases associated with the specified token. Existing transaction token.
state string No Returns cases that are in the specified state. OPEN | READY | CLOSED | CHARGEBACK_INITIATED | CHARGEBACK_CREATED
assignee string No Returns cases associated with the specified assignee.
user_token string No Returns cases associated with the specified user. Existing user token.
chargeback_token string No Returns cases associated with the specified chargeback. Existing chargeback token.

Sample response body

{
 "count": 1,
 "start_index": 0,
 "end_index": 0,
 "is_more": false,
 "data": [
{
"token": "my_case_id",
     "type": "DISPUTE", 
     "dispute_details": {         
      "original_transaction_token": "111",
       "dispute_amount": 100.00,         
"currency_code": "USD",  
       "dispute_reason": "FRAUD",
       "chargeback_token": "my_chargeback_id"
     },
     "memo": "Multiple browser submission",
     "state": "READY",
     "assignee": "janes",
     "folder_id": "123456",
     "user_token": "my_user_123",
     "created_time": "2018-03-19T13:22:07Z",
     "last_modified_time": "2018-03-20T09:22:07Z"
}
]  
}  


Upload case content

Action: POST
Endpoint: /cases/{token}/contents

Upload a document and associate it with a case using the case token as a path parameter. The supporting documents you upload are used to help review the case and reach a final decision.

Uploading documents requires a multi-part API request.

The first part of the API request must contain the metadata and have a Content-Type header set to application/json.

Content-Type: application/json; Content-Disposition: form-data; name="body"

The second part must contain a path to the media file and have a Content-Type header of any MIME file type.

Content-Type: image/jpeg; Content-Disposition: form-data; name="file"

Define each part with a boundary string preceded by two hyphens. Follow the final boundary string with two additional hyphens.

--marqeta_file_separator
...
--marqeta_file_separator--

Acceptable document types include:

  • PDF
  • DOC/DOCX
  • TXT
  • JPG/JPEG
  • GIF
  • PNG
  • TIF/TIFF

Note: To upload documents, you must be whitelisted on the Marqeta platform. Contact your Marqeta Customer Success representative for more information.

Path parameters

Name Type Required? Description Allowable Values
token string Yes The token of the case to which you are uploading and associating documents. An existing case token.

Submit a GET request to /cases to retrieve case tokens.

Body field details

Name Type Required? Description Allowable Values
token string No The unique identifier of the document.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.
36 char max
document_category string Yes The category of the document being uploaded. RECEIPT | CUSTOMER_SIGNATURE | CUSTOMER_DL | CUSTOMER_SSN | CUSTOMER_PASSPORT | UTILITY_BILL | CUSTOMER_COMMUNICATION | DISPUTE_FORM | BANK_STATEMENT | TAX_DOCUMENTS | INCORPORATION_CERTIFICATE | LEASE_AGREEMENT | OTHERS
document_name string Yes The name of the document being uploaded. 255 char max

Sample request message

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"

{
"token": "my_upload_id",           
"document_category": "RECEIPT",
"document_name": "receipt.jpg"
}

--marqeta_file_separator

Content-Type: image/jpeg; Content-Disposition: form-data; name="file"
file=@/Users/janes/Downloads/online-receipt-location.jpg

--marqeta_file_separator--

Sample response body

{
"token": "my_content_id",
"case_token": "111",
"document_category": "RECEIPT",
"document_name": "receipt.jpg",
"created_time": "2018-03-19T13:22:07Z",
"last_modified_time": "2018-03-19T13:22:07Z"
}


List case contents

Action: GET
Endpoint: /cases/{token}/contents

List the uploaded documents for a specific case.

Path parameters

Name Type Required? Description Allowable Values
token string Yes The token of the case associated with the documents you want to list. An existing case token.

Submit a GET request to /cases to retrieve case tokens.

Sample response body

{
"count": 2,
"start_index": 0,
"end_index": 1,
"is_more": false,
"data": [

"token": "my_content_id",
"case_token": "111",
"document_category": "RECEIPT",
"document_name": "receipt.jpg",
"created_time": "2018-03-19T13:22:07Z",
"last_modified_time": "2018-03-19T13:22:07Z"    
},

"token": "my_content_id1",
"case_token": "111",
"document_category": "CUSTOMER_SIGNATURE",
"document_name": "signature.jpg",
"created_time": "2018-03-19T13:22:07Z",
"last_modified_time": "2018-03-19T13:22:07Z"       
}
]
}


Retrieve case transition

Action: GET
Endpoint: /cases/{token}/transitions/{transition_token}

Retrieve a specific case transition for a specific case.

A case transition is an event that changes the state of a case and triggers other related events. The new state of the case and which related events are triggered is determined by the action defined in the case transition. For example, the Marqeta platform can transition a case in the READY state to the CHARGEBACK_INITIATED state using the CHARGEBACK_CREDIT or CHARGEBACK_NO_CREDIT actions. In this case, both actions also trigger the creation of a chargeback.

Path parameters

Name Type Required? Description Allowable Values
token string Yes The token of the case associated with the transitions you want to retrieve. An existing case token.

Submit a GET request to /cases to retrieve case tokens.
transition_token string Yes The token of the transition to retrieve. An existing case transition token.

Submit a GET request to /cases/{token}/transitions to retrieve case transition tokens.

The action field (response only)

Action Initial State New State Description
CREATE n/a OPEN The case was created.
RE_OPEN READY OPEN The case was reopened.
REVIEW OPEN READY The case was ready for review.
ASSIGN READY READY The case was assigned to the specified user.
NON_CHARGEBACK_CREDIT READY CLOSED A non-chargeback credit was issued against the case.
CHARGEBACK_CREDIT READY CHARGEBACK_INITIATED A chargeback was created on the Marqeta platform and the account was credited.
CHARGEBACK_NO_CREDIT READY CHARGEBACK_INITIATED A chargeback was created on the Marqeta platform and the account was not credited.
CHARGEBACK_CREATED CHARGEBACK_INITIATED CHARGEBACK_CREATED A chargeback was created at the card network.
KYC_OVERRIDE READY CLOSED The KYC review was overridden and the case was closed.
REINSTATE_USER READY CLOSED The user was reinstated.
REINSTATE_BUSINESS READY CLOSED The business was reinstated.
CLOSE OPEN, READY, CHARGEBACK_INITIATED CLOSED The case was closed.
DOCUMENTS_DELETED OPEN, READY, CHARGEBACK_INITIATED, CLOSED OPEN, CHARGEBACK_INITIATED, CLOSED The documents associated with the case were deleted.

The reason_code field (response only)

Reason Code Description Related Actions
00 The case was created. CREATE
05 The case is under review. REVIEW
14 The Marqeta platform updated the case. CLOSE, NON_CHARGEBACK_CREDIT
15 An update was initiated by the issuer. REINSTATE_USER, REINSTATE_BUSINESS
18 The account was restored to ACTIVE because the account information was verified. REINSTATE_USER, REINSTATE_BUSINESS
19 The account was restored to ACTIVE because the account activity was verified. REINSTATE_USER, REINSTATE_BUSINESS
22 The case was assigned to a user. ASSIGN
23 The case was re-opened. RE_OPEN
24 The case was re-opened to gather more information. RE_OPEN
25 The documents were verified and the case was closed. CLOSE, KYC_OVERRIDE
26 The customer closed the case. CLOSE
27 A credit was issued to the customer, but no chargeback was created. NON_CHARGEBACK_CREDIT
28 A chargeback was created and the card holder was credited. CHARGEBACK_CREDIT
29 A chargeback was created and the card holder was not credited. CHARGEBACK_NO_CREDIT
30 The case was closed automatically due to inactivity. CLOSE
31 Invalid documents were uploaded. DOCUMENTS_DELETED
32 Unreadable documents were uploaded. DOCUMENTS_DELETED
33 Corrupted documents were uploaded. DOCUMENTS_DELETED
34 The chargeback failed. CHARGEBACK_CREDIT, CHARGEBACK_NO_CREDIT
35 The chargeback failed at the card network. CHARGEBACK_CREDIT, CHARGEBACK_NO_CREDIT
36 The KYC override failed. KYC_OVERRIDE
37 The user reinstatement failed. REINSTATE_USER, REINSTATE_BUSINESS
38 The business reinstatement failed. REINSTATE_USER, REINSTATE_BUSINESS

Sample response body

{
"token": "my_casetransition_id1",
"case_token": "my_case_id",
"action": "CHARGEBACK_CREDIT",
"reason_code": "27",
"created_by": "janes",
"memo": "Initiating chargeback",
"assignee": "janes",
"reason_description": "Smaller Amount",
"state": "CHARGEBACK_INITIATED",
"created_time": "2018-03-19T13:22:07Z",
"last_modified_time": "2018-03-20T09:22:07Z"
}


List case transitions

Action: GET
Endpoint: /cases/{token}/transitions

List existing case transitions for the specified case. This endpoint supports sorting and pagination.

Path parameters

Name Type Required? Description Allowable Values
token string Yes The token of the case associated with the transitions you want to list. An existing case token.

Submit a GET request to /cases to retrieve case tokens.

Sample response body

{

"count": 2,

"start_index": 0,

"end_index": 1,

"is_more": false,

"data": [



 "token": "my_casetransition_id",

"case_token": "my_case_id",

"action": "ASSIGN",

 "reason_code": "05",

"created_by": "janes",

"memo": "Assigned to user",        

"assignee": "janes",

 "reason_description": "Under Review",

 "state": "READY",

"created_time": "2018-03-19T13:22:07Z",

 "last_modified_time": "2018-03-20T09:22:07Z"      

},

{ 

"token": "my_casetransition_id1",

"case_token": "my_case_id",

"action": "CHARGEBACK_CREDIT",

"reason_code": "27",

"created_by": "janes",

 "memo": "Initiating chargeback", 

"assignee": "janes",

"reason_description": "Smaller Amount",

 "state": "CHARGEBACK_INITIATED",

"created_time": "2018-03-19T13:22:07Z",

"last_modified_time": "2018-03-20T09:22:07Z"
}

 ]

}