detail, each row represents a single settlement 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.
For in-depth information on this endpoint, see Settlements in Reports In-depth.
Retrieve settlement data (JSON)
Action:GETEndpoint:
/views/settlements/{time_agg}
Retrieve settlements transaction 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
| Fields | Description |
|---|---|
| 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 aGET request to the views/settlements/day?program=my_program&fields=post_date,currency_conversion_fees endpoint.
JSON
{
"total": 2,
"is_more": false,
"count": 2,
"info": {},
"start_date": "2023-02-08T00:00:00+0000",
"end_date": "2023-02-09T00:00:00+0000",
"last_run_time": "2023-02-09T18:03:19Z",
"schema": [
{
"field": "post_date",
"type": "date",
"display": "Post Date",
"units": null,
"has_total": false,
"date_format": "YYYY-MM-DD",
"is_filter_only": false
},
{
"field": "currency_conversion_fees",
"type": "numeric(14,2)",
"display": "Currency Conversion Fees",
"units": null,
"has_total": false,
"is_filter_only": false
}
],
"records": [
{
"post_date": "2023-02-09T00:00:00.000Z",
"currency_conversion_fees": 4.94
},
{
"post_date": "2023-02-08T00:00:00.000Z",
"currency_conversion_fees": 0.56
}
]
}
Retrieve settlement data (file export)
Action:GETEndpoint:
/views/settlements/{time_agg}/{export_type}
Retrieve settlements transaction 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
| Fields | Description |
|---|---|
| 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
| Fields | Description |
|---|---|
| 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 settlement schema
Action:GETEndpoint:
/views/settlements/{time_agg}/schema
Retrieve a JSON representation of the settlements 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
| Fields | Description |
|---|---|
| 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 aGET request to the /views/settlements/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": "bank",
"type": "character varying(128)",
"description": "The bank under which the program operates.",
"display": "Bank",
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "batch_number",
"type": "integer",
"description": "The clearing batch record number for a clearing record from the network.",
"display": "Batch Number",
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "transaction_token",
"type": "character varying(256)",
"description": "The token of the transaction; unique within a program.",
"display": "Transaction Token",
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "post_date",
"type": "date",
"description": "The date a transaction was posted by the network.",
"display": "Post Date",
"units": null,
"has_total": false,
"date_format": "YYYY-MM-DD HH:mm:ss",
"is_filter_only": false
},
{
"field": "initiating_transaction_token",
"type": "character varying(256)",
"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": "reference_transaction_token",
"type": "integer",
"description": "A transaction identifier which represents a transaction token to which the current transaction token relates to.",
"display": "Reference Transaction Token",
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "reversal_transaction_token",
"type": "integer",
"description": "A transaction identifier which represents a transaction that has been reversed since having originally taken place. This identifier will point to the transaction record of that reversal.",
"display": "Reversal Transaction Token",
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "chargeback_token",
"type": "integer",
"description": "unique token to identify a chargeback record within a program.",
"display": "Chargeback Token",
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "transaction_type",
"type": "character varying(128)",
"description": "A type field that categorizes the transaction event.",
"display": "Transaction Type",
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "transaction_status",
"type": "character varying(128)",
"description": "The status of the transaction.",
"display": "Transaction Status",
"enum_values": [],
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "business_name",
"type": "character varying(128)",
"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": "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": [],
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "parent_user_token",
"type": "character varying(128)",
"description": "The unique user 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": "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": "acting_first_name",
"type": "character varying(128)",
"description": "The first name of the cardholder associated with the card that transacted.",
"display": "Acting First Name",
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "acting_last_name",
"type": "character varying(128)",
"description": "The last name of the cardholder associated with the card that transacted.",
"display": "Acting Last 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(100)",
"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": "card_type",
"type": "character varying(128)",
"description": "The type of card: virtual, physical.",
"display": "Card Type",
"enum_values": [],
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "acting_card_last_four",
"type": "character varying(4)",
"description": "The last four digits of a card used in a transaction.",
"display": "Acting Card Last Four",
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "merchant",
"type": "character varying(128)",
"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_country",
"type": "character varying(128)",
"description": "The country of a merchant location where a transaction has taken place.",
"display": "Merchant Country",
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "merchant_state",
"type": "character varying(128)",
"description": "The state or province of a merchant location where a transaction has taken place.",
"display": "Merchant State",
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "merchant_city",
"type": "character varying(128)",
"description": "The city of a merchant location where a transaction has taken place.",
"display": "Merchant City",
"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": "clean_merchant",
"type": "character varying(128)",
"description": "A human-readable merchant name when available.",
"display": "Clean Merchant",
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "merchant_category_code",
"type": "integer",
"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": "standin_approved_by",
"type": "character varying(128)",
"description": "Designates the means in which a transaction was approved within a JIT transaction flow.",
"display": "Standin Approved By",
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "token_requestor",
"type": "character varying(30)",
"description": "The name of the token requestor within the card network.",
"display": "Token Requestor",
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "token_type",
"type": "character varying(30)",
"description": "The type of digital wallet token.",
"display": "Token Type",
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "token_device_location",
"type": "character varying(50)",
"description": "The geographic coordinates of the device.",
"display": "Token Device Location",
"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": "purchases",
"type": "numeric(14,2)",
"description": "The amount of purchases and any reversals related to settled transactions.",
"display": "Purchases",
"units": "USD",
"has_total": true,
"is_filter_only": false
},
{
"field": "returns",
"type": "numeric(14,2)",
"description": "The amount of returns (refunds) related to previously settled transactions.",
"display": "Returns",
"units": "USD",
"has_total": true,
"is_filter_only": false
},
{
"field": "pin_debit_assoc_fees",
"type": "numeric(14,2)",
"description": "The amount of fees charged to a cardholder for a given transaction record.",
"display": "Pin Debit Assoc Fees",
"units": "USD",
"has_total": true,
"is_filter_only": false
},
{
"field": "currency_conversion_fees",
"type": "numeric(14,2)",
"description": "The amount of currency conversion fees charged by either Mastercard, Visa, Discover, Maestro, Cirrus, VisaInterlink, VisaPlus, VisaNetDebit, or Pulse.",
"display": "Currency Conversion Fees",
"units": "USD",
"has_total": true,
"is_filter_only": false
},
{
"field": "chargebacks",
"type": "numeric(14,2)",
"description": "The amount of chargebacks that have completed, usually accompanied by a CASE_WON status.",
"display": "Chargebacks",
"units": "USD",
"has_total": true,
"is_filter_only": false
},
{
"field": "cross_border_fees",
"type": "numeric(14,2)",
"description": "The amount the merchant was charged when a transaction was conducted using a payment card from an issuing bank not located in the same country as the processing account of the merchant; an aggregate of fees relating to Mastercard, Visa, Discover, Maestro, Cirrus, VisaInterlink, VisaPlus, VisaNetDebit, or Pulse Cross Border Fees.",
"display": "Cross Border Fees",
"units": "USD",
"has_total": true,
"is_filter_only": false
},
{
"field": "switch_fees",
"type": "numeric(14,2)",
"description": "The amount of switch fees for Mastercard, Visa, Discover, Maestro, Cirrus, VisaInterlink, VisaPlus, VisaNetDebit, or Pulse.",
"display": "Switch Fees",
"units": null,
"has_total": false,
"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": "ticket_size",
"type": "character varying(128)",
"description": null,
"display": "Ticket Size",
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "account_funding_transfers",
"type": "numeric(14,2)",
"description": null,
"display": "Account Funding Transfers",
"units": "USD",
"has_total": true,
"is_filter_only": false
},
{
"field": "original_credit_transfers",
"type": "numeric(14,2)",
"description": null,
"display": "Original Credit Transfers",
"units": "USD",
"has_total": true,
"is_filter_only": false
},
{
"field": "chargebacks_acquirer_fees",
"type": "numeric(14,2)",
"description": null,
"display": "Chargebacks Acquirer Fees",
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "chargebacks_cross_border_fees",
"type": "numeric(14,2)",
"description": "Cross Border Fees charged to merchant for a completed chargeback. See \"Cross Border Fees\" for more detail.",
"display": "Chargebacks Cross Border Fees",
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "chargebacks_currency_conversion_fees",
"type": "numeric(14,2)",
"description": "Currency Conversion Fee charged by network for a chargeback. See \"Currency Conversion Fee\" for more detail.",
"display": "Chargebacks Currency Conversion Fees",
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "chargebacks_switch_fees",
"type": "numeric(14,2)",
"description": "Switch Fees charged by network for a completed chargeback. See \"Switch Fees\" for more detail.",
"display": "Chargebacks Switch Fees",
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "network_loads",
"type": "numeric(14,2)",
"description": null,
"display": "Network Loads",
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "company",
"type": "character varying(128)",
"description": "The name of the company associated with the cardholder, if applicable.",
"display": "Company",
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "core_api_transaction_token",
"type": "character varying(36)",
"description": null,
"display": "Core Api Transaction Token",
"units": null,
"has_total": false,
"is_filter_only": false
},
{
"field": "core_api_initiating_transaction_token",
"type": "character varying(36)",
"description": null,
"display": "Core Api Initiating Transaction Token",
"units": null,
"has_total": false,
"is_filter_only": false
}
]