Declines

Use this view endpoint to retrieve data about declined transactions at a specified 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.

Path parameters

Name Type Required? Description Allowable Values
time_agg string Yes Time period over which to aggregate the data. For more information, see Data aggregation levels. 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.

{
"total": 2782,
"is_more": false,
"count": 2782,
"info": {},
"start_date": "2018-11-01T00:00:14+0000",
"end_date": "2018-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": "2018-11-02T13:23:37.000Z",
"declining_entity": "Partner",
"decline_type": "Declined by Gateway",
"transaction_amount": 160.44
},
{
"transaction_timestamp": "2018-11-02T13:23:32.000Z",
"declining_entity": "Marqeta",
"decline_type": "Not sufficient funds",
"transaction_amount": 9.84
},
...
{
"transaction_timestamp": "2018-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.

Path parameters

Name Type Required? Description Allowable Values
time_agg string Yes Time period over which to aggregate the data. For more information, see Data aggregation levels. detail | day | week | month
export_type string Yes File format in which to export the data. csv | xlsx

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":"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.

Path parameters

Name Type Required? Description Allowable Values
time_agg string Yes Time period over which to aggregate the data. For more information, see Data aggregation levels. 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).

[
{
"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 card holder to which a card holder, acting card holder, 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 identifer 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 card holder. 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 card holder 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 card holder.",
"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 card holder to which a card holder, acting card holder, 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 card holder or parent card holder.",
"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 card holder, acting card holder, 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": "Curreny",
"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
}
]