Chargebacks

Retrieve chargeback status and detail data aggregated by transaction. Chargebacks are completed transactions that have been disputed by the issuer, usually on behalf of the card holder.

You can retrieve chargeback information using these endpoints:

  • /views/chargebacks/status returns the chargeback status in a single row per chargeback.
  • /views/chargebacks/detail returns multiple rows per chargeback with one row per chargeback state.

For example, you may want to use these endpoints to retrieve chargeback information, such as submissions date and current status for transaction tokens currently in the chargeback process, or determine the total dollar amount of chargebacks for a specified date range.

The data is derived from the chargeback-related activity on the Marqeta platform.

This endpoint supports multiple response formats, query filtering, field filtering, sorting, pagination, and currency conversion. For more information about response options, see Response Customization.

Retrieve chargebacks status (JSON)

Action: GET
Endpoint: /views/chargebacks/status

Retrieve chargeback status data as a single row per chargeback. This endpoint returns a JSON object that contains an array of records matching your filter query.

Sample response body

The following sample shows a representative response for a GET request to the /views/chargebacks/status?program=my_program&network=MASTERCARD&fields=original_transaction_token,chargeback_state endpoint.

{
"total": 150,
"is_more": false,
"count": 150,
"info": {},
"start_date": "2018-12-01T00:00:00+0000",
"end_date": "2018-12-12T00:00:00+0000",
"last_run_time": "2018-12-12T11:12:13Z",
"schema": [
{
"field": "original_transaction_token",
"type": "bigint",
"description": "Relates to chargebacks, displays the transaction token for the settlement transaction that is now being charged back.",
"display": "Original Transaction Token",
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "chargeback_state",
"type": "character varying(50)",
"description": "The current state of the chargeback.",
"display": "Chargeback State",
"units": null,
"has_total": false,
"is_filter_only": false
}
],
"records": [
{
"original_transaction_token": 5140903,
"chargeback_state": "CASE_WON"
},
{
"original_transaction_token": 6442706,
"chargeback_state": "INITIATED"
},

...

{
"original_transaction_token": 7053516,
"chargeback_state": "INITIATED"
}
]
}


Retrieve chargebacks status (file export)

Action: GET
Endpoint: /views/chargebacks/status/schema/{export_type}

Retrieve chargebacks status data aggregated by transaction. This endpoint asynchronously generates a file in the specified format and returns a job token for retrieving the file when it is completed. The file contains a list of records matching your filter query.

Path parameters

Name Type Required? Description Allowable Values
export_type string Yes File format in which to export the data. csv

Query parameters

Name Type Required? Description Allowable Values
compress string No Type of file compression for the exported file. gz | zip

Default: gz

Sample response body

{
"token":"d22d718504d51ff7a49efcc40d5fe808fd1e9d9e.csv.gz"
}


Retrieve chargebacks status schema

Action: GET
Endpoint: /views/chargebacks/status/schema

Retrieve a JSON representation of the chargebacks status view schema for data aggregated by transaction. The schema object contains an array of objects that describe the available columns and the data type of each column.

Sample response body

The following sample shows a representative response for a GET request to the /views/chargebacks/status/schema?program=my_program endpoint. The schema can vary based on the data aggregation level and the data you are authorized to access (based on the credentials you provide in your request).

[
    {
        "field": "program",
        "type": "character varying(128)",
        "description": "The name of the card program.",
        "display": "Program",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "chargeback_token",
        "type": "bigint",
        "description": "unique token to identify a chargeback record within a program.",
        "display": "Chargeback Token",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "acting_card_type",
        "type": "character varying(50)",
        "description": "The type of card: virtual, physical.",
        "display": "Acting Card Type",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "acting_card_token",
        "type": "character varying(128)",
        "description": "The token identifying a card within a card program. This can be seen in the cards view and transaction level views.",
        "display": "Acting Card Token",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "network",
        "type": "character varying(50)",
        "description": "The card network on which a transaction took place.",
        "display": "Network",
        "enum_values": [
            "DISCOVER",
            "MASTERCARD",
            "VISA"
        ],
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "role",
        "type": "character varying(20)",
        "description": "#N/A",
        "display": "Role",
        "enum_values": [
            "ISSUER"
        ],
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "chargeback_state",
        "type": "character varying(50)",
        "description": "The current state of the chargeback.",
        "display": "Chargeback State",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "chargeback_previous_state",
        "type": "character varying(50)",
        "description": "The previous state of the chageback if the chargeback has moved through more than one state.",
        "display": "Chargeback Previous State",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "chargeback_created_date",
        "type": "timestamp without time zone",
        "description": "The date the chageback was created.",
        "display": "Chargeback Created Date",
        "units": null,
        "has_total": false,
        "date_format": "YYYY-MM-DD HH:mm:ss",
        "is_filter_only": false
    },
    {
        "field": "chargeback_submission_date",
        "type": "timestamp without time zone",
        "description": "The date the chargeback was submitted to the network.",
        "display": "Chargeback Submission Date",
        "units": null,
        "has_total": false,
        "date_format": "YYYY-MM-DD HH:mm:ss",
        "is_filter_only": false
    },
    {
        "field": "original_transaction_token",
        "type": "bigint",
        "description": "Relates to chargebacks, displays the transaction token for the settlement transaction that is now being charged back.",
        "display": "Original Transaction Token",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "chargeback_reason_code",
        "type": "character varying(40)",
        "description": "The code that indicates the reason for the current state of the chargeback.",
        "display": "Chargeback Reason Code",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "chargeback_reason",
        "type": "character varying(1024)",
        "description": "The reason for the current chargeback state.",
        "display": "Chargeback Reason",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "network_reason_code",
        "type": "character varying(20)",
        "description": "A label attached to a chargeback that has been submitted to a card network, describing the type or reasoning behind the chargeback being submitted.",
        "display": "Network Reason Code",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "network_case_id",
        "type": "character varying(60)",
        "description": "An identifier assigned to a chargeback that has been submitted to a card network, unique within a program.",
        "display": "Network Case Id",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "has_documentation",
        "type": "character(1)",
        "description": "Indicates whether the chargeback has documentation.",
        "display": "Has Documentation",
        "enum_values": [
            "Y"
        ],
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "provisional_credit_given",
        "type": "character(1)",
        "description": "Signifies whether a provisional credit has been granted to a card holder in relation to a chargeback submission. A \"Y\" will be present if a provisional credit has been given and a \"N\" if a provisional credit has not been given.",
        "display": "Provisional Credit Given",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "notes",
        "type": "character varying(1024)",
        "description": "#N/A",
        "display": "Notes",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "transaction_processing_type",
        "type": "character varying(128)",
        "description": "The method used to capture the card PAN (chip, magstripe, contactless, chip fallback, token). Chip fallback is used when a chip-capable terminal fails and requires the use of the magstripe.",
        "display": "Transaction Processing Type",
        "enum_values": [
            "NON TOKEN",
            "TOKEN"
        ],
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "merchant_category_code",
        "type": "character varying(10)",
        "description": "The merchant category code (MCC) associated with a transaction.",
        "display": "Merchant Category Code",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "merchant_category_code_group",
        "type": "character varying(2000)",
        "description": "The merchant category code (MCC) group associated with a transaction.",
        "display": "Merchant Category Code Group",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "merchant_category_code_description",
        "type": "character varying(1000)",
        "description": "The description of the merchant category code (MCC) associated with a transaction.",
        "display": "Merchant Category Code Description",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "currency",
        "type": "character varying(10)",
        "description": "The abbreviated currency code.",
        "display": "Currency",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "chargeback_amount",
        "type": "numeric(14,2)",
        "description": "#N/A",
        "display": "Chargeback Amount",
        "units": null,
        "has_total": true,
        "is_filter_only": false
    }
]


Retrieve chargeback details (JSON)

Action: GET
Endpoint: /views/chargebacks/detail

Retrieve chargeback details in multiple rows per chargeback with one row per chargeback state. This endpoint returns a JSON object that contains an array of records matching your filter query.

Sample response body

The following sample shows a representative response for a GET request to the /views/chargebacks/detail?program=my_program&network=MASTERCARD&fields=original_transaction_token,chargeback_state endpoint.

{
    "total": 223,
    "is_more": false,
    "count": 223,
    "info": {
        "bad_parameters": [
            "network"
        ]
    },
    "start_date": "2018-12-01T00:00:00+0000",
    "end_date": "2018-12-13T00:00:00+0000",
    "last_run_time": "2018-12-13T11:12:14Z",
    "schema": [
        {
            "field": "original_transaction_token",
            "type": "bigint",
            "description": "Relates to chargebacks, displays the transaction token for the settlement transaction that is now being charged back.",
            "display": "Original Transaction Token",
            "units": null,
            "has_total": false,
            "is_filter_only": false
        },
        {
            "field": "chargeback_state",
            "type": "character varying(30)",
            "description": "The current state of the chargeback.",
            "display": "Chargeback State",
            "units": null,
            "has_total": false,
            "is_filter_only": false
        }
    ],
    "records": [
        {
            "original_transaction_token": 4931927,
            "chargeback_state": null
        },
        {
            "original_transaction_token": 4529581,
            "chargeback_state": null
        },

...

        {
            "original_transaction_token": 7321574,
            "chargeback_state": "INITIATED"
        }
    ]
}


Retrieve chargeback details (file export)

Action: GET
Endpoint: /views/chargebacks/detail/{export_type}

Retrieve chargeback details aggregated by transaction. This endpoint asynchronously generates a file in the specified format and returns a job token for retrieving the file when it is completed. The file contains a list of records matching your filter query.

Path parameters

Name Type Required? Description Allowable Values
export_type string Yes File format in which to export the data. csv

Query parameters

Name Type Required? Description Allowable Values
compress string No Type of file compression for the exported file. gz | zip

Default: gz

Sample response body

{
"token":"d22d718504d51ff7a49efcc40d5fe808fd1e9d9e.csv.gz"
}


Retrieve chargeback details schema

Action: GET
Endpoint: /views/chargebacks/detail/schema

Retrieve a JSON representation of the chargeback details view schema for data aggregated by transaction. The schema object contains an array of objects that describe the available columns and the data type of each column.

Sample response body

The following sample shows a representative response for a GET request to the /views/chargebacks/detail/schema?program=my_program endpoint. The schema can vary based on the data aggregation level and the data you are authorized to access (based on the credentials you provide in your request).

[
    {
        "field": "program",
        "type": "character varying(256)",
        "description": "The name of the card program.",
        "display": "Program",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "chargeback_token",
        "type": "bigint",
        "description": "unique token to identify a chargeback record within a program.",
        "display": "Chargeback Token",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "original_transaction_token",
        "type": "bigint",
        "description": "Relates to chargebacks, displays the transaction token for the settlement transaction that is now being charged back.",
        "display": "Original Transaction Token",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "transaction_token",
        "type": "character varying(128)",
        "description": "The token of the transaction; unique within a program.",
        "display": "Transaction Token",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "transaction_date",
        "type": "timestamp without time zone",
        "description": "The number of transactions related to a particular grouping of transactions and date.",
        "display": "Transaction Date",
        "units": null,
        "has_total": false,
        "date_format": "YYYY-MM-DD HH:mm:ss",
        "is_filter_only": false
    },
    {
        "field": "internal_transaction_code",
        "type": "character varying(60)",
        "description": "A transaction code representing a type of payment or transaction.",
        "display": "Internal Transaction Code",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "transaction_type",
        "type": "character varying(256)",
        "description": "A type field that categorizes the transaction event.",
        "display": "Transaction Type",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "chargeback",
        "type": "character varying(50)",
        "description": "The identifier for the chargeback record.",
        "display": "Chargeback",
        "units": null,
        "has_total": true,
        "is_filter_only": false
    },
    {
        "field": "acting_card_token",
        "type": "character varying(108)",
        "description": "The token identifying a card within a card program. This can be seen in the cards view and transaction level views.",
        "display": "Acting Card Token",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "acting_card_type",
        "type": "character varying(201)",
        "description": "The type of card: virtual, physical.",
        "display": "Acting Card Type",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "transaction_processing_type",
        "type": "character varying(9)",
        "description": "The method used to capture the card PAN (chip, magstripe, contactless, chip fallback, token). Chip fallback is used when a chip-capable terminal fails and requires the use of the magstripe.",
        "display": "Transaction Processing Type",
        "enum_values": [
            "NON TOKEN",
            "TOKEN"
        ],
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "chargeback_state",
        "type": "character varying(30)",
        "description": "The current state of the chargeback.",
        "display": "Chargeback State",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "chargeback_previous_state",
        "type": "character varying(30)",
        "description": "The previous state of the chageback if the chargeback has moved through more than one state.",
        "display": "Chargeback Previous State",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "chargeback_created_date",
        "type": "timestamp without time zone",
        "description": "The date the chageback was created.",
        "display": "Chargeback Created Date",
        "units": null,
        "has_total": false,
        "date_format": "YYYY-MM-DD HH:mm:ss",
        "is_filter_only": false
    },
    {
        "field": "chargeback_submission_date",
        "type": "timestamp without time zone",
        "description": "The date the chargeback was submitted to the network.",
        "display": "Chargeback Submission Date",
        "units": null,
        "has_total": false,
        "date_format": "YYYY-MM-DD HH:mm:ss",
        "is_filter_only": false
    },
    {
        "field": "chargeback_reason_code",
        "type": "character varying(40)",
        "description": "The code that indicates the reason for the current state of the chargeback.",
        "display": "Chargeback Reason Code",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "chargeback_reason",
        "type": "character varying(1024)",
        "description": "The reason for the current chargeback state.",
        "display": "Chargeback Reason",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "network_reason_code",
        "type": "character varying(30)",
        "description": "A label attached to a chargeback that has been submitted to a card network, describing the type or reasoning behind the chargeback being submitted.",
        "display": "Network Reason Code",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "network_case_id",
        "type": "character varying(60)",
        "description": "An identifier assigned to a chargeback that has been submitted to a card network, unique within a program.",
        "display": "Network Case Id",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "has_documentation",
        "type": "character varying(1)",
        "description": "Indicates whether the chargeback has documentation.",
        "display": "Has Documentation",
        "enum_values": [
            "Y"
        ],
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "provisional_credit_given",
        "type": "character varying(1)",
        "description": "Signifies whether a provisional credit has been granted to a card holder in relation to a chargeback submission. A \"Y\" will be present if a provisional credit has been given and a \"N\" if a provisional credit has not been given.",
        "display": "Provisional Credit Given",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "chargeback_transition_token",
        "type": "bigint",
        "description": "Used in the chargebacks detail view, this id represents each state a chargeback has progresses through.",
        "display": "Chargeback Transition Token",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "etl_batch_id",
        "type": "bigint",
        "description": null,
        "display": "Etl Batch Id",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "entry_createdate",
        "type": "timestamp without time zone",
        "description": "The date and time when a record has been read into the database following a replication cycle.",
        "display": "Entry Createdate",
        "units": null,
        "has_total": false,
        "date_format": "YYYY-MM-DD HH:mm:ss",
        "is_filter_only": false
    },
    {
        "field": "last_modified_time",
        "type": "timestamp without time zone",
        "description": "The date when the record was most recently updated.",
        "display": "Last Modified Time",
        "units": null,
        "has_total": false,
        "date_format": "YYYY-MM-DD HH:mm:ss",
        "is_filter_only": false
    },
    {
        "field": "purchases",
        "type": "numeric(38,2)",
        "description": "The amount of purchases and any reversals related to settled transactions.",
        "display": "Purchases",
        "units": null,
        "has_total": true,
        "is_filter_only": false
    },
    {
        "field": "chargebacks",
        "type": "numeric(38,2)",
        "description": "The amount of chargebacks that have completed, usually accompanied by a CASE_WON status.",
        "display": "Chargebacks",
        "units": null,
        "has_total": true,
        "is_filter_only": false
    },
    {
        "field": "cardholder",
        "type": "numeric(38,2)",
        "description": "Used in the chargebacks detail view to represent the financial impact to the account of a cardholder as it relates to a particular chargeback event",
        "display": "Cardholder",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "pending_interchange",
        "type": "numeric(38,2)",
        "description": "The amount of interchange associated with a chargeback that has been set aside into a holding account pending the completion status of a chargeback.",
        "display": "Pending Interchange",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "pending_chargebacks",
        "type": "numeric(38,2)",
        "description": "The amount of pending chargebacks–funds are put in a holding account until the chargeback is completed.",
        "display": "Pending Chargebacks",
        "units": null,
        "has_total": true,
        "is_filter_only": false
    },
    {
        "field": "pending_cardholder",
        "type": "numeric(38,2)",
        "description": "Amount of funds run through a Cardholder Account through the 4840 (or equivalent depending on country of transaction) layer. The movement of chargebacks funds or related to chargebacks in a state as to where it does not impact the ledger but rather the funds are set in a \"holding\" account until the chargeback is completed.",
        "display": "Pending Cardholder",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    },
    {
        "field": "core_api_transaction_type",
        "type": "character varying(256)",
        "description": null,
        "display": "Core Api Transaction Type",
        "units": null,
        "has_total": false,
        "is_filter_only": false
    }
]