Transactions

count

The number of transactions to retrieve.

1-10

start_index

The sort order index of the first resource in the returned array.

Any integer

fields

Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.

Comma-delimited list of fields, or blank

sort_by

Field on which to sort. Use any field in the resource model, or one of the system fields lastModifiedTime or createdTime. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.

-created_time, created_time, -user_transaction_time, user_transaction_time

start_date

The starting date (or date-time) of a date range from which to return transactions. To return transactions for a single day, enter the same date in both the start_date and end_date fields.

Format: yyyy-MM-dd or yyyy-MM-ddThh:mm:ss.SS

end_date

The ending date (or date-time) of a date range from which to return transactions. To return transactions for a single day, enter the same date in both the end_date and start_date fields.

Format: yyyy-MM-dd or yyyy-MM-ddThh:mm:ss.SS

type

Comma-delimited list of transaction types to include.

user_token

The unique identifier of the user account holder.

Existing user token

business_token

The unique identifier of the business account holder.

Existing business token

acting_user_token

The unique identifier of the acting user.

Existing user token

card_token

The unique identifier of the card.

Existing card token

state

Comma-delimited list of transaction states to display.

PENDING, CLEARED, COMPLETION, DECLINED, ERROR, ALL

version

Specifies the API version for the request.

v1, v2, v3

verbose

If true, the query returns additional information for diagnostic purposes.

true, false

count

The number of resources to retrieve.

This field is returned if there are resources in your returned array.

1-10

data

An array of transaction objects.

Objects are returned as appropriate to your query.

Valid array of one or more transaction objects

data[].acquirer

Contains information about the merchant’s financial institution.

Existing acquirer object

data[].acquirer.institution_country

Country code of the merchant’s financial institution.

Valid alpha-3 ISO 3166 country code

data[].acquirer.institution_id_code

Identifier code of the merchant’s financial institution.

255 char max

data[].acquirer.network_international_id

The international network identifier.

255 char max

data[].acquirer.retrieval_reference_number

Retrieval reference number of the merchant’s financial institution.

255 char max

data[].acquirer.system_trace_audit_number

System trace audit number of the merchant’s financial institution.

255 char max

data[].acquirer_fee_amount

Indicates the amount of the acquirer fee. Account holders are sometimes charged an acquirer fee for card use at ATMs, fuel dispensers, and so on.

decimal

Format:
0.00

data[].acquirer_reference_id

Acquirer-assigned unique identifier of the transaction. Useful for settlement and reconciliation.

255 char max

data[].acting_user_token

Unique identifier of the user who conducted the transaction. This might be a child user configured to share its parent’s account balance.

36 char max

data[].address_verification

Contains address verification data consisting of address data entered by the cardholder, address data held by the Marqeta platform, and an assertion by the Marqeta platform as to whether the two sets of data match.

on_file, request, response

data[].address_verification.on_file

Contains address verification information.

postal_code, street_address, zip

data[].address_verification.on_file.postal_code

Postal code of the address.

10 char max

data[].address_verification.on_file.street_address

Street name and number of the address.

40 char max

data[].address_verification.on_file.zip

United States ZIP code of the address.

10 char max

data[].address_verification.request

Contains address verification information.

postal_code, street_address, zip

data[].address_verification.request.postal_code

Postal code of the address.

10 char max

data[].address_verification.request.street_address

Street name and number of the address.

40 char max

data[].address_verification.request.zip

United States ZIP code of the address.

10 char max

data[].address_verification.response

Response codes and memos for address verification, card security verification, and transactions.

additional_information, code, memo

data[].address_verification.response.additional_information

Information about the velocity control applied to the transaction.

NOTE: This field is returned only in transaction response objects. It is not returned in address verification or card security verification response objects.

The additional_information field returns a string in the following format: <Velocity control name>, cumulative transaction amount is <X>, where X is the cumulative transaction amount value calculated by Marqeta. For example: 500 max spend per day, cumulative transaction amount is 750.

data[].address_verification.response.code

Four-digit response code for address verification, card security code verification, or transactions.

For address verification responses, the code is an assertion by the Marqeta platform as to whether its address verification data matches that provided by the cardholder:

For card security verification, the code indicates whether the verification check passed and can have these possible values:

For a transaction, the code describes the outcome of the attempted transaction. For the full list of transaction codes, see Transaction response codes.

Four-digit code

data[].address_verification.response.memo

Additional text that describes the response.

255 char max

data[].amount

Amount of the transaction.

decimal

Format:
0.00

data[].amount_to_be_released

Amount of original authorization to be released. This field appears in final clearing transactions where the clearing amount is lower than the authorization amount.

decimal

Format:
0.00

data[].approval_code

Unique identifier assigned to an authorization, printed on the receipt at point of sale.

255 char max

data[].auto_reload

Contains information about an auto reload. See Auto Reloads for more information.

Returned if an auto reload was executed.

active, association, currency_code, funding_source_address_token, funding_source_token, order_scope, token

data[].auto_reload.active

Specifies whether the auto reload is active.

Only one auto reload per level, per object, can be active.

true, false

Default value:
true

data[].auto_reload.association

Specifies the scope of the auto reload.

Input no more than one field. If no value is supplied, the auto reload applies at the program level.

business_token, card_product_token, user_token

data[].auto_reload.association.business_token

Unique identifier of the business for which the auto reload is configured.

Send a GET request to /businesses to retrieve business tokens.

1–36 chars

data[].auto_reload.association.card_product_token

Unique identifier of the card product for which the auto reload is configured.

Send a GET request to /cardproducts to retrieve card product tokens.

1–36 chars

data[].auto_reload.association.user_token

Unique identifier of the user for which the auto reload is configured.

Send a GET request to /users to retrieve user tokens.

1–36 chars

data[].auto_reload.currency_code

Three-digit ISO 4217 currency code.

Any currency code allowed by your program

data[].auto_reload.funding_source_address_token

Unique identifier of the funding source address to use for this auto reload.

If your funding source is an ACH account, then a funding_source_address_token is not required. If your funding source is a payment card, you must have at least one funding source address in order to create a GPA order.

Send a GET request to /fundingsources/addresses/user/{user_token} to retrieve address tokens for a user.

Send a GET request to /fundingsources/addresses/business/{business_token} to retrieve address tokens for a business.

1–36 chars

data[].auto_reload.funding_source_token

Unique identifier of the funding source to use for this auto reload.

Send a GET request to /fundingsources/user/{user_token} to retrieve funding source tokens for a user.

Send a GET request to /fundingsources/business/{business_token} to retrieve funding source tokens for a business.

1–36 chars

data[].auto_reload.order_scope

Defines the balance threshold and reload amounts.

gpa

data[].auto_reload.order_scope.gpa

Defines the type of order.

reload_amount, trigger_amount

data[].auto_reload.order_scope.gpa.reload_amount

Available balance on the card after the reload has completed.

This value must be greater than or equal to the value of trigger_amount. Note that this is not the same as the amount added to the card, which will vary from reload to reload.

0.01 min

data[].auto_reload.order_scope.gpa.trigger_amount

Threshold that determines when the reload happens.

The reload is triggered when the card balance falls below this amount.

0.01 min

data[].auto_reload.token

Unique identifier of the auto reload.

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.

1–36 chars

data[].batch_number

The batch number of the transaction.

255 char max

data[].business

Contains customer-provided information about the business that funded the transaction.

Existing business metadata

data[].business.metadata

Associates customer-provided metadata with the business.

Up to 20 name-value pair fields in "field_name_1": "field_value_1" format.

data[].business_token

Unique identifier of the business that owns the account that funded the transaction.

36 char max

data[].card

Contains information about the card used in the transaction.

activation_actions, barcode, bulk_issuance_token, card_product_token, chip_cvv_number, contactless_exemption_counter, created_time, cvv_number, expidite, expiration, expiration_time, fulfillment, fulfillment_status, instrument_type, last_four, last_modified_time, metadata, pan, pin_is_set, reissue_pan_from_card_token, new_pan_from_card_token, state, state_reason, token, translate_pin_from_card_token, user_token

data[].card.activation_actions

Defines actions to execute when the card is activated. The fields in this object are mutually exclusive.

swap_digital_wallet_tokens_from_card_token, terminate_reissued_source_card

data[].card.activation_actions.swap_digital_wallet_tokens_from_card_token

Moves all digital wallet tokens from the specified card to the new card.

Not relevant when reissue_pan_from_card_token is set.

Send a GET request to /cards/user/{token} to retrieve card tokens for a particular user.

1–36 chars

Existing card token

data[].card.activation_actions.terminate_reissued_source_card

If you are reissuing a card, the source card is terminated by default. To prevent the source card from being terminated, set this field to false.

Only relevant when reissue_pan_from_card_token is set.

true, false

Default value:
true

data[].card.barcode

Barcode printed on the card, expressed as numerals.

10-20 chars

data[].card.bulk_issuance_token

Unique identifier of the bulk card order.

1-36 chars

data[].card.card_product_token

Unique identifier of the card product.

1-36 chars

data[].card.chip_cvv_number

Three-digit card verification value (ICVV) stored on the chip of the card.

3 chars

data[].card.contactless_exemption_counter

Running count of the contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the number of contactless transactions that can be performed without issuing an SCA challenge at the card product level.

For more information about strong customer authentication, see Card Products.

Any integer

data[].card.contactless_exemption_total_amount

Running total of the money spent in contactless transactions successfully completed since the last strong customer authentication (SCA) challenge was issued. You can limit the total amount that can be spent in contactless transactions without issuing an SCA challenge at the card product level.

For more information about strong customer authentication, see Card Products.

Any integer

data[].card.created_time

Date and time when the resource was created, in UTC.

datetime

Format:
yyyy-MM-ddThh:mm:ssZ

data[].card.cvv_number

Three-digit card verification value (CVV2 or CVC2) printed on the card.

3 chars

data[].card.expedite

A value of true indicates that you requested expedited processing of the card from your card fulfillment provider.

true, false

data[].card.expiration

Expiration date in MMyy format.

Format: MMyy

data[].card.expiration_time

Expiration date and time, in UTC.

datetime

Format:
yyyy-MM-ddThh:mm:ssZ

data[].card.fulfillment

Determines physical characteristics of a card and shipment information.

card_fulfillment_reason, card_personalization, shipping

data[].card.fulfillment.card_fulfillment_reason

Descriptive reason for the card fulfillment.

NEW, LOST_STOLEN, EXPIRED

data[].card.fulfillment.card_personalization

Specifies personalized attributes to be added to the card.

carrier, images, perso_type, text

data[].card.fulfillment.card_personalization.carrier

Specifies attributes of the card carrier.

logo_file, logo_thumbnail_file, message_file, message_line, template_id

data[].card.fulfillment.card_personalization.carrier.logo_file

Specifies an image to display on the card carrier.

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

data[].card.fulfillment.card_personalization.carrier.logo_thumbnail_file

Specifies a thumbnail-sized rendering of the image specified in the logo_file field.

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

data[].card.fulfillment.card_personalization.carrier.message_file

Specifies a text file containing a custom message to print on the card carrier.

Contains the name of the text file and must match the name of the file you send to your fulfillment provider.

data[].card.fulfillment.card_personalization.carrier.message_line

Specifies a custom message that appears on the card carrier.

60 char max

data[].card.fulfillment.card_personalization.carrier.template_id

Specifies the card carrier template to use.

Card carrier template ID

data[].card.fulfillment.card_personalization.images

Specifies personalized images that appear on the card.

card, carrier, carrier_return_window, signature

data[].card.fulfillment.card_personalization.images.card

Specifies personalized images that appear on the card.

name, thermal_color

data[].card.fulfillment.card_personalization.images.card.name

Specifies a PNG image to display on the card.

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

data[].card.fulfillment.card_personalization.images.card.thermal_color

Specifies the color of the image displayed on the card.

Contains the name of the color and must match one of the provider’s predefined colors.

data[].card.fulfillment.card_personalization.images.carrier

Specifies personalized images that appear on the card carrier.

message_1, name

data[].card.fulfillment.card_personalization.images.carrier.message_1

Specifies a custom message that appears on the card carrier.

60 char max

data[].card.fulfillment.card_personalization.images.carrier.name

Specifies a PNG image to display on the card carrier.

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

data[].card.fulfillment.card_personalization.images.carrier_return_window

Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders.

name

data[].card.fulfillment.card_personalization.images.carrier_return_window.name

Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders.

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

data[].card.fulfillment.card_personalization.images.signature

Specifies a PNG image of the cardholder’s signature.

name

data[].card.fulfillment.card_personalization.images.signature.name

Specifies a PNG image of the cardholder’s signature.

Contains the name of the image file and must match the name of the file you send to your fulfillment provider.

data[].card.fulfillment.card_personalization.perso_type

Specifies the type of card personalization.

EMBOSS, LASER, FLAT

data[].card.fulfillment.card_personalization.text

Specifies personalized text that appears on the card.

name_line_1, name_line_2, name_line_3

data[].card.fulfillment.card_personalization.text.name_line_1

Specifies the first line of personalized text that appears on the card.

name_line_1.value

21 char max; if name_line_1_numeric_postfix is true, 14 char max.

Strings longer than the character limit are truncated.

data[].card.fulfillment.card_personalization.text.name_line_1.value

Line of personalized text printed on the card.

21 char max

data[].card.fulfillment.card_personalization.text.name_line_2

Specifies the second line of personalized text that appears on the card.

name_line_2.value

data[].card.fulfillment.card_personalization.text.name_line_2.value

Line of personalized text printed on the card.

21 char max

data[].card.fulfillment.card_personalization.text.name_line_3

Specifies the third line of personalized text that appears on the card.

name_line_3.value

data[].card.fulfillment.card_personalization.text.name_line_3.value

Line of personalized text printed on the card.

21 char max

data[].card.fulfillment.shipping

Specifies shipping details for the order.

This object is returned if it exists in the resource.

care_of_line, method, recipient_address, return_address

data[].card.fulfillment.shipping.care_of_line

Specifies the value of the care of (C/O) line on the mailing carrier.

This field is returned if it exists in the resource.

255 char max

data[].card.fulfillment.shipping.method

Specifies the shipping service.

This field is returned if it exists in the resource.

LOCAL_MAIL, LOCAL_MAIL_PACKAGE, GROUND, TWO_DAY, OVERNIGHT, INTERNATIONAL, INTERNATIONAL_PRIORITY, LOCAL_PRIORITY, FEDEX_EXPEDITED, FEDEX_REGULAR, UPS_EXPEDITED, UPS_REGULAR, USPS_EXPEDITED, USPS_REGULAR

data[].card.fulfillment.shipping.recipient_address

Address to which the order will be shipped.

This field is returned if it exists in the resource.

Existing recipient_address object

data[].card.fulfillment.shipping.recipient_address.address1

Number and street of the address.

This field is returned if it exists in the resource.

255 char max

Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters.

data[].card.fulfillment.shipping.recipient_address.address2

Additional address information.

This field is returned if it exists in the resource.

255 char max

Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters.

data[].card.fulfillment.shipping.recipient_address.city

City of the address.

This field is returned if it exists in the resource.

40 char max

data[].card.fulfillment.shipping.recipient_address.country

Country of the address.

This field is returned if it exists in the resource.

40 char max

English short name. For example, for the Kingdom of Spain, use the English short name "Spain". The ISO maintains the full list of country codes.

data[].card.fulfillment.shipping.recipient_address.first_name

First name of the addressee.

This field is returned if it exists in the resource.

40 char max

data[].card.fulfillment.shipping.recipient_address.last_name

Last name of the addressee.

This field is returned if it exists in the resource.

40 char max

data[].card.fulfillment.shipping.recipient_address.middle_name

Middle name of the addressee.

This field is returned if it exists in the resource.

40 char max

data[].card.fulfillment.shipping.recipient_address.phone

Telephone number of the addressee.

This field is returned if it exists in the resource.

20 char max

data[].card.fulfillment.shipping.recipient_address.postal_code

Postal code of the address.

This field is returned if it exists in the resource.

10 char max

data[].card.fulfillment.shipping.recipient_address.state

State or province of the address.

This field is returned if it exists in the resource.

32 char max

data[].card.fulfillment.shipping.recipient_address.zip

United States ZIP code of the address.

This field is returned if it exists in the resource.

10 char max

data[].card.fulfillment.shipping.return_address

Address to which the order will be returned if shipping fails.

This object is returned if it exists in the resource.

Existing return_address object

data[].card.fulfillment.shipping.return_address.address1

Number and street of the address.

This field is returned if it exists in the resource.

255 char max

Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters.

data[].card.fulfillment.shipping.return_address.address2

Additional address information.

This field is returned if it exists in the resource.

255 char max

Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters.

data[].card.fulfillment.shipping.return_address.city

City of the address.

This field is returned if it exists in the resource.

40 char max

data[].card.fulfillment.shipping.return_address.country

Country of the address.

This field is returned if it exists in the resource.

40 char max

English short name. For example, for the Kingdom of Spain, use the English short name "Spain". The ISO maintains the full list of country codes.

data[].card.fulfillment.shipping.return_address.first_name

First name of the addressee.

This field is returned if it exists in the resource.

40 char max

data[].card.fulfillment.shipping.return_address.last_name

Last name of the addressee.

This field is returned if it exists in the resource.

40 char max

data[].card.fulfillment.shipping.return_address.middle_name

Middle name of the addressee.

This field is returned if it exists in the resource.

40 char max

data[].card.fulfillment.shipping.return_address.phone

Telephone number of the addressee.

This field is returned if it exists in the resource.

20 char max

data[].card.fulfillment.shipping.return_address.postal_code

Postal code of the address.

This field is returned if it exists in the resource.

10 char max

data[].card.fulfillment.shipping.return_address.state

State or province of the address.

This field is returned if it exists in the resource.

32 char max

data[].card.fulfillment.shipping.return_address.zip

United States ZIP code of the address.

This field is returned if it exists in the resource.

10 char max

data[].card.fulfillment_status

Card fulfillment status:

ISSUED, ORDERED, REORDERED, REJECTED, SHIPPED, DELIVERED, DIGITALLY_PRESENTED

data[].card.instrument_type

Instrument type of the card:

PHYSICAL_MSR, PHYSICAL_ICC, PHYSICAL_CONTACTLESS, PHYSICAL_COMBO, VIRTUAL_PAN

data[].card.last_four

Last four digits of the card primary account number (PAN).

4 chars

data[].card.last_modified_time

Date and time when the resource was last modified, in UTC.

datetime

Format:
yyyy-MM-ddThh:mm:ssZ

data[].card.metadata

Associates customer-provided metadata with the card.

Contains the names and values of up to 20 fields in the format "my_name_1": "my_value_1"

data[].card.pan

Primary account number (PAN) of the card.

16 char max

data[].card.pin_is_set

Specifies if the personal identification number (PIN) has been set for the card.

4 chars

data[].card.reissue_pan_from_card_token

Reissues the specified card (known as the "source" card).

Existing card token

data[].card.new_pan_from_card_token

Reissues the specified card (known as the "source" card) with a new primary account number (PAN).

Existing card token

data[].card.state

Indicates the state of the card.

ACTIVE, SUSPENDED, TERMINATED, UNSUPPORTED, UNACTIVATED, LIMITED

data[].card.state_reason

Descriptive reason for why the card is in its current state. For example, "Card activated by cardholder".

255 char max

data[].card.token

Unique identifier of the card.

Existing card token

data[].card.translate_pin_from_card_token

Copies the personal identification number (PIN) from the specified source card to the newly created card.

Existing card token

data[].card.user_token

Unique identifier of the cardholder.

Existing user token

data[].card_acceptor

Contains information about the merchant.

Existing card_acceptor object

data[].card_acceptor.address

Card acceptor’s address. May be returned if the request uses Transaction Model v1 of the Marqeta Core API. Not returned for Transaction Model v2 requests.

255 char max

data[].card_acceptor.city

Card acceptor’s city.

40 char max

data[].card_acceptor.country_code

Card acceptor’s country code. May be returned if the request uses Transaction Model v2 of the Marqeta Core API. Not returned for Transaction Model v1 requests.

Valid alpha-3 ISO 3166 country code

data[].card_acceptor.mcc

Merchant category code (MCC).

Existing MCC

data[].card_acceptor.mcc_groups

An array of mcc_groups.

Valid array of one or more mcc_groups

data[].card_acceptor.mid

The merchant identifier.

255 char max

data[].card_acceptor.name

Card acceptor’s name.

50 char max

data[].card_acceptor.network_mid

The merchant identifier on the card network.

255 char max

data[].card_acceptor.poi

Contains information about the point of sale, including details on how the card was presented.

Returned if provided by the card network, and the request uses Transaction Model v1 of the Marqeta Core API. Not returned for Transaction Model v2 requests.

card_presence, cardholder_presence, partial_approval_capable, pin_present, special_condition_indicator, tid

data[].card_acceptor.poi.card_presence

Indicates whether the card was present during the transaction.

255 char max

data[].card_acceptor.poi.cardholder_presence

Indicates whether the cardholder was present during the transaction.

255 char max

data[].card_acceptor.poi.partial_approval_capable

Indicates whether the card acceptor or terminal supports partial-approval transactions.

255 char max

data[].card_acceptor.poi.pin_present

Indicates whether the cardholder entered a PIN during the transaction.

255 char max

data[].card_acceptor.poi.special_condition_indicator

Indicates a higher-risk operation, such as a quasi-cash or cryptocurrency transaction.

These transactions typically involve non-financial institutions.

CRYPTOCURRENCY_PURCHASE, DEBT_PAYMENT, QUASI_CASH, UNSPECIFIED

data[].card_acceptor.poi.tid

Card acceptor or terminal identification number.

255 char max

data[].card_acceptor.postal_code

Card acceptor’s postal code.

255 char max

data[].card_acceptor.state

Two-character state, province, or territorial abbreviation.

For a complete list of valid state and province abbreviations, see Valid state, provincial, and territorial abbreviations.

Note: Non-US merchants may return more than 2 char for this field.

2 char max

data[].card_acceptor.country_of_origin

The merchant’s country of origin.

A merchant’s country of origin can be different from the country in which the merchant is located. For example, embassies are physically located in countries that are not their country of origin: a Mexican embassy might be physically located in Singapore, but the country of origin is Mexico.

This field is included when the cardholder conducts a transaction with a government-controlled merchant using a Marqeta-issued card.

255 char max

data[].card_acceptor.transfer_service_provider_name

The name of the transfer service provider of a money transfer original credit transaction. This field is included when a transfer service provider participates in the transaction.

25 char max

data[].card_acceptor.payment_facilitator_name

The name of the payment facilitator, including the sub-merchant identifier, of an original credit transaction. This field is returned when a payment facilitator participates in the transaction.

25 char max

data[].card_holder_model

Contains information about a cardholder.

account_holder_group_token, active, address1, address2, authentication, birth_date, business_token, city, company, corporate_card_holder, country, created_time, email, first_name, gender, honorific, id_card_expiration_date, id_card_number, identifications, ip_address, last_modified_time, last_name, metadata, middle_name, nationality, notes, parent_token, passport_expiration_date, passport_number, password, phone, postal_code, ssn, state, status, token, uses_parent_account, zip

data[].card_holder_model.account_holder_group_token

Associates the specified account holder group with the cardholder.

36 char max

data[].card_holder_model.active

Specifies if the cardholder is in the ACTIVE state on the Marqeta platform.

true, false

data[].card_holder_model.address1

Cardholder’s address.

255 char max

data[].card_holder_model.address2

Additional address information for the cardholder.

255 char max

data[].card_holder_model.authentication

Contains the cardholder’s email address and password information.

email_verified, email_verified_time, last_password_update_channel, last_password_update_time

data[].card_holder_model.authentication.email_verified

Specifies whether the email address has been verified.

true, false

data[].card_holder_model.authentication.email_verified_time

Date and time when the email address was verified.

datetime

Format:
yyyy-MM-ddThh:mm:ssZ

data[].card_holder_model.authentication.last_password_update_channel

Specifies the channel through which the password was last changed.

USER_CHANGE, USER_RESET

data[].card_holder_model.authentication.last_password_update_time

Date and time when the password was last changed.

datetime

Format:
yyyy-MM-ddThh:mm:ssZ

data[].card_holder_model.birth_date

Cardholder’s date of birth.

Format: yyyy-MM-dd

data[].card_holder_model.business_token

Unique identifier of the business resource.

Existing business resource token

data[].card_holder_model.city

City where the cardholder resides.

40 char max

data[].card_holder_model.company

Company name.

255 char max

data[].card_holder_model.corporate_card_holder

Specifies if the cardholder holds a corporate card.

true, false

data[].card_holder_model.country

Country where the cardholder resides.

40 char max

data[].card_holder_model.created_time

Date and time when the resource was created, in UTC.

datetime

Format:
yyyy-MM-ddThh:mm:ssZ

data[].card_holder_model.email

Valid email address of the cardholder.

1–255 chars

data[].card_holder_model.first_name

Cardholder’s first name.

40 char max

data[].card_holder_model.gender

Gender of the cardholder.

F, M

data[].card_holder_model.honorific

Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on.

10 char max

data[].card_holder_model.id_card_expiration_date

Expiration date of the cardholder’s identification.

Format: yyyy-MM-dd

data[].card_holder_model.id_card_number

Cardholder’s identification card number.

255 char max

data[].card_holder_model.identifications

One or more objects containing identifications associated with the cardholder.

Valid array of one or more identifications objects

data[].card_holder_model.identifications[].expiration_date

Expiration date for the identification, if applicable.

Format: yyyy-MM-dd

data[].card_holder_model.identifications[].type

Type of identification.

SSN, TIN, SIN, NIN, PASSPORT_NUMBER, DRIVERS_LICENSE, BUSINESS_NUMBER, BUSINESS_TAX_ID, TAXPAYER_REFERENCE

data[].card_holder_model.identifications[].value

Number associated with the identification.

255 char max

data[].card_holder_model.ip_address

Cardholder’s IP address.

39 char max

data[].card_holder_model.last_modified_time

Date and time when the resource was last updated, in UTC.

datetime

Format:
yyyy-MM-ddThh:mm:ssZ

data[].card_holder_model.last_name

Cardholder’s last name.

40 char max

data[].card_holder_model.metadata

Associates any additional metadata you provide with the cardholder.

You can define the names and values of up to 20 fields in the format "my_name_1": "my_value_1"

data[].card_holder_model.middle_name

Cardholder’s middle name.

40 char max

data[].card_holder_model.nationality

Cardholder’s nationality.

255 char max

data[].card_holder_model.notes

Any additional information pertaining to the cardholder.

255 char max

data[].card_holder_model.parent_token

Unique identifier of the parent user or business resource.

1–36 chars

data[].card_holder_model.passport_expiration_date

Expiration date of the cardholder’s passport.

Format: yyyy-MM-dd

data[].card_holder_model.passport_number

Cardholder’s passport number.

40 char max

data[].card_holder_model.password

Password to the cardholder’s user account on the Marqeta platform.

1–255 chars

data[].card_holder_model.phone

Cardholder’s telephone number.

255 char max

data[].card_holder_model.postal_code

Postal code of the cardholder’s address.

10 char max

data[].card_holder_model.ssn

Cardholder’s Social Security Number (SSN).

Nine digits only, no delimiters.

data[].card_holder_model.state

State or province where the cardholder resides.

2 char max

data[].card_holder_model.status

Specifies the status of the cardholder on the Marqeta platform.

UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED

data[].card_holder_model.token

Unique identifier of the cardholder.

1–36 chars

data[].card_holder_model.uses_parent_account

Indicates whether the child shares balances with the parent (true), or the child’s balances are independent of the parent (false).

true, false

data[].card_holder_model.zip

United States ZIP code of the cardholder’s address.

10 char max

data[].card_security_code_verification

Contains information about a verification check performed on the card’s security code.

Existing card_security_code_verification object

data[].card_security_code_verification.response

Response codes and memos for address verification, card security verification, and transactions.

additional_information, code, memo

data[].card_security_code_verification.response.additional_information

Information about the velocity control applied to the transaction.

NOTE: This field is returned only in transaction response objects. It is not returned in address verification or card security verification response objects.

The additional_information field returns a string in the following format: <Velocity control name>, cumulative transaction amount is <X>, where X is the cumulative transaction amount value calculated by Marqeta. For example: 500 max spend per day, cumulative transaction amount is 750.

data[].card_security_code_verification.response.code

Four-digit response code for address verification, card security code verification, or transactions.

For address verification responses, the code is an assertion by the Marqeta platform as to whether its address verification data matches that provided by the cardholder:

For card security verification, the code indicates whether the verification check passed and can have these possible values:

For a transaction, the code describes the outcome of the attempted transaction. For the full list of transaction codes, see Transaction response codes.

Four-digit code

data[].card_security_code_verification.response.memo

Additional text that describes the response.

255 char max

data[].card_security_code_verification.type

Indicates the type of security code. Can have these possible values:

CVV1, CVV2, ICVV, DCVV

data[].card_token

Unique identifier of the card. Useful when a single account holder has multiple cards.

36 char max

data[].cardholder_authentication_data

Contains 3D Secure authentication data:

Existing cardholder_authentication_data object

data[].cardholder_authentication_data.acquirer_exemption

Indicates 3D Secure authentication exemptions from the acquirer. This array is returned if it is included in the transaction data from the card network.

MERCHANT_INITIATED_TRANSACTION, TRANSACTION_RISK_ANALYSIS, RECURRING_PAYMENT, LOW_VALUE_PAYMENT, SCA_PERFORMED, SECURE_CORPORATE_PAYMENT, AUTHENTICATION_OUTAGE_EXCEPTION

data[].cardholder_authentication_data.authentication_method

Specifies the 3D Secure authentication method.

null, AUDIO_CALL, BEHAVIORAL_BIOMETRICS, BIOMETRIC, BIOMETRIC_FACE, BIOMETRIC_FINGERPRINT, DECOUPLED, DELEGATED_TRUSTED_AUTHENTICATION, FRICTIONLESS, IN_APP_LOGIN, KNOWLEDGE_BASED, OOB, OOB_OTHER, OTHER, OTP, OTP_SMS, OTP_EMAIL, SECURE_PAYMENT_CONFM, VIDEO_CALL, VOICE_RECOGNITION, WEB_AUTHN, OTHER

data[].cardholder_authentication_data.authentication_status

Specifies the status of the 3D Secure authentication:

ATTEMPTED, DATA_SHARE_EXEMPTION, EXEMPTED, EXEMPTION_CLAIMED, SCA_EXEMPTION, SUCCESSFUL, SUCCESSFUL_NON_PAYMENT, THREEDS_REQUESTER_DATA_SHARE_EXEMPTION, THREEDS_REQUESTER_SCA_EXEMPTION, THREEDS_REQUESTER_TRA_EXEMPTION, UNAVAILABLE

data[].cardholder_authentication_data.electronic_commerce_indicator

Status of the 3D Secure authentication attempt, as provided by a transaction participant.

authentication_attempted, authentication_successful, no_authentication

data[].cardholder_authentication_data.issuer_exemption

Indicates a 3D Secure authentication exemption from the issuer This field is returned if it is included in the transaction data from the card network.

SCA_LOW_VALUE_PAYMENT

data[].cardholder_authentication_data.three_ds_message_version

Specifies the 3D Secure message version used for authentication.

1.0.2, 2.1.0, 2.2.0

data[].cardholder_authentication_data.verification_result

Result of cardholder authentication verification value (CAVV) or accountholder authentication value (AAV) verification performed by the card network.

failed, not_present, not_provided, not_verified, not_verified_authentication_outage, verified, verified_amount_checked, verified_amount_greater_than_20_percent, verified_amount_less_than_20_percent

data[].cardholder_authentication_data.verification_value_created_by

Transaction participant who determined the verification result.

issuer_acs, issuer_attempts_server, network, network_attempts_server

data[].cash_back_amount

Amount of cash back requested by the cardholder during the transaction. Included in the total transaction amount.

decimal

Format:
0.00

data[].chargeback

Contains the chargeback object associated with this transaction if a chargeback has been initiated.

Existing chargeback object

data[].chargeback.amount

Amount of the chargeback.

0.01 min

data[].chargeback.channel

Channel the chargeback came through.

GATEWAY, GATEWAY_AUTOMATED, ISSUER, ISSUER_AUTOMATED

data[].chargeback.created_time

Date and time when the chargeback was created. Not returned for transactions when the associated chargeback is in the INITIATED state.

datetime

Format:
yyyy-MM-ddThh:mm:ssZ

data[].chargeback.credit_user

Whether to credit the user for the chargeback amount.

true, false

data[].chargeback.last_modified_time

Date and time when the chargeback was last modified. Not returned for transactions when the associated chargeback is in the INITIATED state.

datetime

Format:
yyyy-MM-ddThh:mm:ssZ

data[].chargeback.memo

Additional comments about the chargeback.

1–1024 chars

data[].chargeback.network

Network handling the chargeback.

MARQETA, DISCOVER, MASTERCARD, PULSE, VISA

data[].chargeback.network_case_id

Network-assigned identifier of the chargeback.

50 char max

data[].chargeback.reason_code

Identifies the standardized reason for the chargeback.

See The reason_code field in the Cases (Visa) API reference.

data[].chargeback.state

State of the case.

INITIATED, REPRESENTMENT, PREARBITRATION, ARBITRATION, CASE_WON, CASE_LOST, NETWORK_REJECTED, WITHDRAWN

data[].chargeback.token

Unique identifier of the chargeback.

1–36 chars

data[].chargeback.transaction_token

Unique identifier of the transaction being charged back.

1–36 chars

data[].clearing_record_sequence_number

A sequence number that identifies a specific clearing message among multiple clearing messages for an authorization.

Sequence number returned in the clearing record

data[].created_time

Date and time when the Marqeta platform created the transaction entry, in UTC format. For example, when Marqeta processed the clearing record for a refund.

datetime

Format:
yyyy-MM-ddThh:mm:ssZ

data[].currency_code

Currency type of the transaction.

Valid three-digit ISO 4217 currency code

data[].currency_conversion

Contains information about currency conversion.

Existing currency_conversion object

data[].currency_conversion.network

Contains information from the card network about currency conversion, including the original currency of the transaction, the amount of the transaction in the original currency, and the conversion rate.

Existing network object

data[].currency_conversion.network.conversion_rate

Conversion rate between the origination currency and the settlement currency.

Returned when the transaction currency is different from the origination currency.

Current conversion rate.

NOTE: A value of 0 or 1 indicates no conversion; the currencies are the same.

data[].currency_conversion.network.dynamic_currency_conversion

Indicates whether currency conversion was performed dynamically at the point of sale.

true, false

data[].currency_conversion.network.original_amount

Amount of the transaction in the currency in which it originated.

Decimal amount.

data[].currency_conversion.network.original_currency_code

Currency type of the origination currency.

Valid three-digit ISO 4217 currency code

data[].currency_conversion.network.settlement_data

Contains information from the card network about currency conversion at the time of settlement, including the original currency of the transaction, the amount of the transaction in the original currency, and the conversion rate.

Existing settlement_data object

data[].currency_conversion.network.settlement_data.amount

The settled amount.

decimal

Format:
0.00

data[].currency_conversion.network.settlement_data.conversion_rate

Returned when the transaction currency is different from the origination currency.

Conversion rate between the origination currency and the settlement currency.

Current conversion rate.

NOTE: A value of 0 or 1 indicates no conversion; the currencies are the same.

data[].currency_conversion.network.settlement_data.currency_code

The ISO 4217 code of the currency used in the transaction.

Valid three-digit ISO 4217 currency code

data[].digital_wallet_token

Contains information about the digital wallet that funded the transaction.

Returned for all transactions funded by a digital wallet or related to digital wallet token provisioning.

For more on digital wallets, see the Digital Wallets Management API reference and Digital Wallets and Tokenization developer guide.

address_verification, card_token, created_time, device, fulfillment_status, issuer_eligibility_decision, last_modified_time, metadata, state, state_reason, token, token_service_provider, user, wallet_provider_profile

data[].digital_wallet_token.address_verification

Contains address verification information.

name, postal_code, street_address, zip

data[].digital_wallet_token.address_verification.name

Name of the cardholder.

40 char max

data[].digital_wallet_token.address_verification.postal_code

Postal code.

10 char max

data[].digital_wallet_token.address_verification.street_address

Street address provided by the cardholder.

40 char max

data[].digital_wallet_token.address_verification.zip

United States ZIP code.

10 char max

data[].digital_wallet_token.card_token

Unique identifier of the card.

Existing card token

data[].digital_wallet_token.created_time

Date and time when the digital wallet token object was created, in UTC.

datetime

Format:
yyyy-MM-ddThh:mm:ssZ

data[].digital_wallet_token.device

Contains information related to the device being provisioned.

device_id, ip_address, language_code, location, name, phone_number, token, type

data[].digital_wallet_token.device.device_id

Identity number of the device.

24 char max

data[].digital_wallet_token.device.ip_address

Device’s IP address.

IP address format, 50 char max

data[].digital_wallet_token.device.language_code

Language the device is configured to use.

50 char max

data[].digital_wallet_token.device.location

Geographic coordinates of the device.

Latitude and longitude in DDD.DD/DDD.DD format.

NOTE: Both the longitude and latitude are prefixed with either a + or - symbol, for example: +42.29/-71.07.

data[].digital_wallet_token.device.name

Name of the device.

50 char max

data[].digital_wallet_token.device.phone_number

Device’s telephone number.

50 char max

data[].digital_wallet_token.device.token

Unique identifier of the device object.

36 char max

data[].digital_wallet_token.device.type

Type of device being provisioned.

MOBILE_PHONE, WATCH, TABLET, MOBILE_PHONE_OR_TABLET, VEHICLE, APPLIANCE, LAPTOP, GAMING_DEVICE, UNKNOWN

data[].digital_wallet_token.fulfillment_status

Digital wallet token’s provisioning status.

For fulfillment status descriptions, see Create digital wallet token transition.

DECISION_RED, DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED

data[].digital_wallet_token.issuer_eligibility_decision

The Marqeta platform’s decision as to whether the digital wallet token should be provisioned.

For all other values, check the value of the fulfillment_status field to definitively ascertain the provisioning outcome.

NOTE: The value invalid.cid indicates an invalid CVV2 number.

0000, cardaccount.verified, card.suspicious, token.activation.verification.required, token.activation-request.decline, card.not.active, invalid.cid, card.expired, card.suspended, cardholder.not.active

data[].digital_wallet_token.last_modified_time

Date and time when the digital wallet token object was last modified, in UTC.

datetime

Format:
yyyy-MM-ddThh:mm:ssZ

data[].digital_wallet_token.metadata

Contains additional information about the digital wallet token.

cardproduct_preferred_notification_language, issuer_product_config_id

data[].digital_wallet_token.metadata.cardproduct_preferred_notification_language

Language specified in the config.transaction_controls.notification_language field of the card product: ces (Czech), deu (German), eng (English), fra (French), ita (Italian), pol (Polish), spa (Spanish), swe (Swedish)

The ISO maintains the full list of ISO 3166 two- and three-digit numeric country codes.

ces, deu, eng, fra, ita, pol, spa, swe

data[].digital_wallet_token.metadata.issuer_product_config_id

Unique identifier of the product configuration on the Marqeta platform.

255 char max

data[].digital_wallet_token.state

State of the digital wallet token.

For state descriptions, see Transitioning Token States.

REQUESTED, REQUEST_DECLINED, ACTIVE, SUSPENDED, TERMINATED

data[].digital_wallet_token.state_reason

Reason why the digital wallet token transitioned to its current state.

255 char max

data[].digital_wallet_token.token

Unique identifier of the digital wallet token.

Existing digital wallet token.

data[].digital_wallet_token.token_service_provider

Contains information held and provided by the token service provider (card network).

correlation_id, pan_reference_id, token_assurance_level, token_eligibility_decision, token_expiration, token_pan, token_reference_id, token_requestor_id, token_requestor_name, token_score, token_type

data[].digital_wallet_token.token_service_provider.correlation_id

Unique value representing a tokenization request (Mastercard only).

Existing correlation identifier

data[].digital_wallet_token.token_service_provider.pan_reference_id

Unique identifier of the digital wallet token primary account number (PAN) within the card network.

Existing PAN Reference ID

data[].digital_wallet_token.token_service_provider.token_assurance_level

(Mastercard only) Represents the confidence level in the digital wallet token.

0-99

data[].digital_wallet_token.token_service_provider.token_eligibility_decision

Digital wallet’s decision as to whether the digital wallet token should be provisioned.

DECISION_RED, DECISION_YELLOW, DECISION_GREEN

data[].digital_wallet_token.token_service_provider.token_expiration

Expiration date of the digital wallet token.

Format: MMyy

data[].digital_wallet_token.token_service_provider.token_pan

Primary account number (PAN) of the digital wallet token.

16 char max

data[].digital_wallet_token.token_service_provider.token_reference_id

Unique identifier of the digital wallet token within the card network.

Existing Token Reference ID

data[].digital_wallet_token.token_service_provider.token_requestor_id

Unique numerical identifier of the token requestor within the card network. These ID numbers map to token_requestor_name field values as follows:

Mastercard

Visa

11 char max

Example Values:

data[].digital_wallet_token.token_service_provider.token_requestor_name

Name of the token requestor within the card network.

NOTE: The list of example values for this field is maintained by the card networks and is subject to change.

255 char max

Example Values: