DOCS

New!

/

15 minute read

October 2, 2019

Case Management

Use the /cases endpoint to manage transaction disputes.

Each case object includes a type field that defines the purpose of the case. You can upload supporting documents and associate them with a specific 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

Fields Description

token

string, optional

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.

Allowable Values:

36 char max

type

string, required

The type of case.

Allowable Values:

DISPUTE

dispute_details

object, required

Specifies the disputed transaction and the reason for the dispute.

Allowable Values:

memo

string, optional

Free-form comments about the case.

Allowable Values:

512 char max

The dispute_details object

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

Fields Description

original_transaction_token

string, required

The token of the original transaction in dispute.

Allowable Values:

Existing transaction token.

dispute_amount

decimal, required

The amount of funds in dispute.

Allowable Values:

Must be less than or equal to the original transaction amount.

dispute_reason

string, required

The code describing the reason for the dispute.

Allowable Values:

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"
}

Is this helpful?

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"
}

Is this helpful?

Retrieve case

Action: GET
Endpoint: /cases/{token}

Retrieve a specific case.

URL path parameters

Fields Description

token

string, required

The token of the case to retrieve.

Allowable Values:

Existing case token.

Query parameters

Fields Description

create_access_token

boolean, optional

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.

Allowable Values:

true, false

Default value: false

create_shared_link

boolean, optional

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.

Allowable Values:

true, false

Default value: 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"
}

Is this helpful?

List cases

Action: GET
Endpoint: /cases

List existing cases. This endpoint supports sorting and pagination.

Query parameters

Fields Description

type

string, optional

Returns cases of the specified type.

Allowable Values:

DISPUTE

original_transaction_token

string, optional

Returns cases associated with the specified token.

Allowable Values:

Existing transaction token.

state

string, optional

Returns cases that are in the specified state.

Allowable Values:

OPEN, READY, CLOSED, CHARGEBACK_INITIATED, CHARGEBACK_CREATED

assignee

string, optional

Returns cases associated with the specified assignee.

Allowable Values:

user_token

string, optional

Returns cases associated with the specified user.

Allowable Values:

Existing user token.

chargeback_token

string, optional

Returns cases associated with the specified chargeback.

Allowable Values:

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"
    }
  ]
}

Is this helpful?

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"

Is this helpful?

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"

Is this helpful?

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--

Is this helpful?

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 representative for more information.

URL path parameters

Fields Description

token

string, required

The token of the case to which you are uploading and associating documents.

Allowable Values:

An existing case token.

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

Body field details

Fields Description

token

string, optional

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.

Allowable Values:

36 char max

document_category

string, required

The category of the document being uploaded.

Allowable Values:

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, required

The name of the document being uploaded.

Allowable Values:

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--

Is this helpful?

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"
}

Is this helpful?

List case contents

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

List the uploaded documents for a specific case.

URL path parameters

Fields Description

token

string, required

The token of the case associated with the documents you want to list.

Allowable Values:

An existing case token.

Send 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"
    }
  ]
}

Is this helpful?

Create case transition

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

Create a case transition.

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.

URL path parameters

Fields Description

token

string, required

The token of the case associated with the transition you want to create.

Allowable Values: An existing case token.

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

transition_token

string, required

The token of the transition to retrieve.

Allowable Values: An existing case transition token.

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

The action field (response only)

Action State Description

REINSTATE_USER

CLOSED

Reinstate User, Case status changed to CLOSED, this should trigger POST to /usertransitions with status as ACTIVE and one of the following reason_codes.

REINSTATE_BUSINESS

CLOSED

Reinstate Business, Case status changed to CLOSED, this should trigger POST to /businesstransitions with status as ACTIVE and one of the following reason_codes.

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

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

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 request body

{
    "token": "my_casetransition_id",
    "action": "REINSTATE_USER",
    "reason_code": "18",
    "created_by": "rgadewar"
    "memo": "Reinstating User"
}

Is this helpful?

Sample response body

{
      "token": "my_casetransition_id",
      "case_token": "my_case_id",
      "action": "REINSTATE_USER",
      "reason_code": "18",
      "created_by": "rgadewar",
      "memo": "Reinstating User",
      "assignee": "rgadewar",
      "reason_description": "Information Verified",
      "state": "CLOSED",
      "created_time": "2018-03-19T13:22:07Z",
      "last_modified_time": "2018-03-20T09:22:07Z"
    }

Is this helpful?

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.

URL path parameters

Fields Description

token

string, required

The token of the case associated with the transitions you want to retrieve.

Allowable Values:

An existing case token.

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

transition_token

string, required

The token of the transition to retrieve.

Allowable Values:

An existing case transition token.

Send 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.

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

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

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"
}

Is this helpful?

List case transitions

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

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

URL path parameters

Fields Description

token

string, required

The token of the case associated with the transitions you want to list.

Allowable Values:

An existing case token.

Send 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"
    }
  ]
}

Is this helpful?

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.