Skip to main content
Use this view endpoint to retrieve data about declined transactions at a specific aggregation level. For example, if you choose an aggregation level of detail, each row represents a single declined transaction. The data is derived from the transaction-related messages sent to and from 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 declined transactions data (JSON)

Action: GET
Endpoint: /views/declines/{time_agg} Retrieve declined transactions data, aggregated over the specified time period. This endpoint returns a JSON object that contains an array of records matching your filter query.

​
URL path parameters

FieldsDescription
time_agg

string
Required		Time period over which to aggregate the data. For more information, see Data aggregation levels .

Allowable Values:

detail, day, week, month

​
Sample response body

The following sample shows a representative response for a GET request to the /views/declines/detail?program=my_program&fields=transaction_timestamp,declining_entity,decline_type,transaction_amount endpoint.
JSON
{
     "total": 2782,
     "is_more": false,
     "count": 2782,
     "info": {},
     "start_date": "2023-11-01T00:00:14+0000",
     "end_date": "2023-11-02T13:23:37+0000",
     "last_run_time": "",
     "schema": [
          {
               "field": "transaction_timestamp",
               "type": "timestamp without time zone",
               "description": "",
               "display": "Transaction Timestamp",
               "units": null,
               "has_total": false,
               "date_format": "YYYY-MM-DD HH:mm:ss",
               "is_filter_only": false
          },
          {
               "field": "declining_entity",
               "type": "character varying(128)",
               "description": null,
               "display": "Declining Entity",
               "units": null,
               "has_total": false,
               "is_filter_only": false
          },
          {
               "field": "decline_type",
               "type": "character varying(279)",
               "description": null,
               "display": "Decline Type",
               "units": null,
               "has_total": false,
               "is_filter_only": false
          },
          {
               "field": "transaction_amount",
               "type": "numeric(14,2)",
               "description": "The amount of the transaction or sum total amount of multiple, relevant transactions.",
               "display": "Transaction Amount",
               "units": "USD",
               "has_total": true,
               "is_filter_only": false
          }
     ],
     "records": [
          {
               "transaction_timestamp": "2023-11-02T13:23:37.000Z",
               "declining_entity": "Partner",
               "decline_type": "Declined by Gateway",
               "transaction_amount": 160.44
          },
          {
               "transaction_timestamp": "2023-11-02T13:23:32.000Z",
               "declining_entity": "Marqeta",
               "decline_type": "Not sufficient funds",
               "transaction_amount": 9.84
          },
          ...
          {
               "transaction_timestamp": "2023-11-02T03:33:38.000Z",
               "declining_entity": "Network",
               "decline_type": "Network decline advice",
               "transaction_amount": 377.76
          },
          ...

     ]
}

​
Retrieve declined transactions data (file export)

Action: GET
Endpoint: /views/declines/{time_agg}/{export_type} Retrieve declined transactions data, aggregated over the specified time period. 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.

​
URL path parameters

FieldsDescription
time_agg

string
Required		Time period over which to aggregate the data. For more information, see Data aggregation levels .

Allowable Values:

detail, day, week, month
export_type

string
Required		File format in which to export the data.

Allowable Values:

csv

​
Query parameters

FieldsDescription
compress

string
optional		Type of file compression for the exported file.

Allowable Values:

gz, zip

Default value:
gz

​
Sample response body

JSON
{
    "token": "111122226c444d8888888a9999ae11111db63da4.csv.gz"
}

​
Retrieve declined transactions schema

Action: GET
Endpoint: /views/declines/{time_agg}/schema Retrieve a JSON representation of the declines view schema for data aggregated over the specified time period. The schema object contains an array of objects that describe the available columns and the data type of each column.

​
URL path parameters

FieldsDescription
time_agg

string
Required		Time period over which to aggregate the data. For more information, see Data aggregation levels .

Allowable Values:

detail, day, week, month

​
Sample response body

The following sample shows a representative response for a GET request to the /views/declines/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).
JSON
[
     {
          "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": "transaction_timestamp",
          "type": "timestamp without time zone",
          "description": "",
          "display": "Transaction Timestamp",
          "units": null,
          "has_total": false,
          "date_format": "YYYY-MM-DD HH:mm:ss",
          "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_type",
          "type": "character varying(256)",
          "description": "",
          "display": "Transaction Type",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "initiating_transaction_token",
          "type": "character varying(128)",
          "description": "The token identifying the initial transaction in a chain of transactions (usually an authorization).",
          "display": "Initiating Transaction Token",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "related_transaction_token",
          "type": "bigint",
          "description": null,
          "display": "Related Transaction Token",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "related_transaction_type",
          "type": "character varying(256)",
          "description": null,
          "display": "Related Transaction Type",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "transaction_processing_type",
          "type": "character varying(150)",
          "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": [],
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "transaction_status",
          "type": "character varying(150)",
          "description": "The status of the transaction.",
          "display": "Transaction Status",
          "enum_values": [],
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "declining_entity",
          "type": "character varying(128)",
          "description": null,
          "display": "Declining Entity",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "decline_type",
          "type": "character varying(279)",
          "description": null,
          "display": "Decline Type",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "reason_code",
          "type": "character varying(12)",
          "description": null,
          "display": "Reason Code",
          "enum_values": [],
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "displaymessage",
          "type": "character varying(279)",
          "description": "A user-friendly display message describing the outcome of a transaction.",
          "display": "Displaymessage",
           "enum_values": [],
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "account_id",
          "type": "bigint",
          "description": "The ID for the account-level cardholder to which a cardholder, acting cardholder, or business is associated.",
          "display": "Account Id",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "account_user_token",
          "type": "character varying(50)",
          "description": "The token for the associated user account.",
          "display": "Account User Token",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "account_uai",
          "type": "character varying(50)",
          "description": "The unique account identifier (UAI) for an account within a bank; unique across programs.",
          "display": "Account Uai",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "acting_user_id",
          "type": "bigint",
          "description": "The identifier generated by the Marqeta platform for an acting level cardholder as it relates to a transaction.",
          "display": "Acting User Id",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "acting_user_token",
          "type": "character varying(128)",
          "description": "The unique user token of a cardholder. This can be seen in the user view and transaction level views.",
          "display": "Acting User Token",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "acting_uai",
          "type": "character varying(50)",
          "description": "The unique account identifier (UAI) for an acting cardholder account within a bank; unique across programs.",
          "display": "Acting Uai",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "parent_id",
          "type": "bigint",
          "description": "The ID of the parent account associated with an acting cardholder.",
          "display": "Parent Id",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "parent_user_token",
          "type": "character varying(50)",
          "description": "The token identifying the parent of the user or business account.",
          "display": "Parent User Token",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "parent_uai",
          "type": "character varying(50)",
          "description": "The unique account identifier (UAI) for the parent of the user or business account.",
          "display": "Parent Uai",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "business_id",
          "type": "bigint",
          "description": "The ID generated by the Marqeta platform for the business-level cardholder to which a cardholder, acting cardholder, or business is attached.",
          "display": "Business Id",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "business_user_token",
          "type": "character varying(50)",
          "description": "The business token associated with an acting cardholder or parent cardholder.",
          "display": "Business User Token",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "business_uai",
          "type": "character varying(50)",
          "description": "The unique account identifier (UAI) for the business account within a bank; unique across programs.",
          "display": "Business Uai",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "business_name",
          "type": "character varying(255)",
          "description": "The name of the business associated with a cardholder, acting cardholder, or business account.",
          "display": "Business Name",
          "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": "acting_card_product",
          "type": "character varying(128)",
          "description": "The name of the card product related to a card; each card product has unique spend controls.",
          "display": "Acting Card Product",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "acting_card_type",
          "type": "character varying(128)",
          "description": "The form factor of the card (virtual or physical).",
          "display": "Acting Card Type",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "clean_merchant",
          "type": "character varying(765)",
          "description": "The clean name of the business at which the transaction took place.",
          "display": "Clean Merchant",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "merchant",
          "type": "character varying(765)",
          "description": "The merchant associated with the transaction; where a transaction took place.",
          "display": "Merchant",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "merchant_category_code",
          "type": "bigint",
          "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_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": "network",
          "type": "character varying(128)",
          "description": "The card network on which a transaction took place.",
          "display": "Network",
          "enum_values": [],
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "sub_network",
          "type": "character varying(128)",
          "description": "The subnetwork used by a transaction (VisaPlus, VisaNet, VisaInterlink, VisaNet Debit, Maestro, Cirrus, or Pulse).",
          "display": "Sub Network",
          "enum_values": [],
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "merchant_lat",
          "type": "numeric(10,7)",
          "description": "#N/A",
          "display": "Merchant Lat",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "merchant_lon",
          "type": "numeric(11,7)",
          "description": "#N/A",
          "display": "Merchant Lon",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "merchant_country",
          "type": "character varying(765)",
          "description": "#N/A",
          "display": "Merchant Country",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "merchant_city",
          "type": "character varying(65535)",
          "description": "#N/A",
          "display": "Merchant City",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "merchant_state",
          "type": "character varying(128)",
          "description": "#N/A",
          "display": "Merchant State",
          "units": null,
          "has_total": false,
          "is_filter_only": false
     },
    {
          "field": "currency_code",
          "type": "character varying(10)",
          "description": "The three-number code of the currency.",
          "display": "Currency Code",
          "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": "transaction_amount",
          "type": "numeric(14,2)",
          "description": "The amount of the transaction or sum total amount of multiple, relevant transactions.",
          "display": "Transaction Amount",
          "units": null,
          "has_total": true,
          "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
     }
]

Related topics

Transaction Decline CodesTransaction Details in the Marqeta DashboardRelease Notes2022 Release NotesExpense Management with Gateway JIT Funding