/
125 minute read
October 6, 2021

Transactions

Hidden

The /transactions resource represents the electronic messages that carry information used for payment processing. A transaction usually originates when a cardholder attempts to make a payment online or at a physical point of sale.

You can receive information about transactions as they occur by configuring webhooks. Learn about configuring webhooks in the Webhooks Overview guide. See the transaction events for which you can set up webhooks in the Event Types API reference page.

You can also retrieve transactions associated with specific cards, merchants, and account holders using the endpoints described here.

For an overview of transactions and the transaction object, see About Transactions.

Tip
Use the /transactions endpoint to retrieve smaller datasets (up to one page). For best performance when requesting larger datasets, use the DiVA API.

Retrieve transaction

Action: GET
Endpoint: /transactions/{token}

Retrieve a specific transaction. Include the token path parameter to identify the transaction.

Note
Transactions are not available in real time via this endpoint, and typically appear after 30 seconds. On occasion a transaction may require up to four hours to appear.
URL path parameters
Fields Description

token

string
Required

Identifies the transaction to retrieve.

Allowable Values:

Existing transaction token.

Transaction field descriptions

The following table contains a superset of possible transaction response elements. Responses always include the type and amount fields. Other objects are conditionally returned. For more information about which objects may be returned based on the type of transaction, see the Transaction Types table.

Fields Description

type

string
Returned

Transaction event type. For more information about the type field, see the "Transaction events" section on the Event Types page.

Allowable Values:

state

string
Returned

Current state of the transaction. For more information about the state field, see The transaction lifecycle on the "About Transactions" page.

Allowable Values:

PENDING, CLEARED, COMPLETION, DECLINED, ERROR

identifier

string
Conditionally returned

Sequential identifier of the transaction.

Allowable Values:

token

string
Returned

Unique identifier of the transaction, formatted as a UUID.

NOTE: For subsequent related transactions, this token value appears as the preceding_related_transaction_token.

Allowable Values:

36 char max

user_token

string
Conditionally returned

Unique identifier of the user who owns the account that funded the transaction; subsequent related transactions retain the same user_token even if the card used to complete the transaction moves to another user.

Allowable Values:

36 char max

business_token

string
Conditionally returned

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

Allowable Values:

36 char max

acting_user_token

string
Returned

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

Allowable Values:

36 char max

card_token

string
Conditionally returned

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

Allowable Values:

36 char max

is_preauthorization

boolean
Returned

Indicates if the transaction is a pre-authorization.

Allowable Values:

true, false

duration

integer
Conditionally returned

Duration of the transaction on Marqeta servers, in milliseconds.

Allowable Values:

created_time

datetime
Conditionally returned

Date and time when the Marqeta platform created the transaction entry (for example, when the platform received an incoming message for a refund).

Allowable Values:

user_transaction_time

datetime
Conditionally returned

Date and time when the user initiated the transaction (for example, when a merchant entered a refund).

Allowable Values:

settlement_date

datetime
Conditionally returned

Date and time when funds were moved for a transaction (for example, in the case of a refund, when funds were credited to the cardholder).

Allowable Values:

request_amount

decimal
Conditionally returned

Merchant-requested amount, including any fees.

Allowable Values:

amount

decimal
Returned

Amount of the transaction.

Allowable Values:

cash_back_amount

decimal
Conditionally returned

Amount of cash back requested by the card holder during the transaction, to be included in the total transaction amount.

Allowable Values:

currency_conversion

object
Conditionally returned

Contains information about currency conversion.

Allowable Values:

currency_conversion.network

object
Conditionally returned

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.

Allowable Values:

A valid currency_conversion.network object.

currency_conversion.network.original_amount

decimal
Conditionally returned

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

Allowable Values:

Decimal amount.

currency_conversion.network.conversion_rate

decimal
Conditionally returned

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

Conversion rate between the origination currency and the settlement currency.

Allowable Values:

Current conversion rate.

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

currency_conversion.network.original_currency_code

string
Conditionally returned

Currency type of the origination currency.

Allowable Values:

A valid three-digit ISO 4217 currency type.

currency_conversion.network.dynamic_currency_conversion

boolean
Conditionally returned

Indicates whether currency conversion was performed dynamically.

Allowable Values:

true, false

currency_conversion.network.settlement_data

object
Conditionally returned

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.

Allowable Values:

A valid currency_conversion.network.settlement_data object.

currency_conversion.network.settlement_data.original_amount

decimal
Conditionally returned

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

Allowable Values:

Decimal amount.

currency_conversion.network.settlement_data.conversion_rate

decimal
Conditionally returned

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

Conversion rate between the origination currency and the settlement currency.

Allowable Values:

Current conversion rate.

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

currency_conversion.network.settlement_data.original_currency_code

string
Conditionally returned

Currency type of the origination currency.

Allowable Values:

A valid three-digit ISO 4217 currency type.

currency_code

string
Conditionally returned

Currency type of the transaction.

Allowable Values:

A valid three-digit ISO 4217 currency type.

approval_code

string
Conditionally returned

Unique identifier assigned to a given authorization. Is printed on the receipt at point of sale.

Allowable Values:

response

object
Conditionally returned

Contains information about the response, including the response code and response memo.

Allowable Values:

response.code, response.memo, response.additional_information

response.code

string
Returned

Four-digit code corresponding with the outcome of the attempted transaction type.

card_security_code_verification.response.code indicates whether the verification check passed and can have these possible values:

  • 0000 – passed

  • 0001 – did not pass

Allowable Values:

Four digits

response.memo

string
Returned

Information on the outcome of the attempted transaction type.

Allowable Values:

255 char max

response.additional_information

string
Conditionally returned

Information about the relevant velocity control for the transaction, if applicable.

Allowable Values:

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.

Marqeta recommends that you name your velocity controls in a clearly descriptive way so that you can easily understand why a transaction was declined. In the example given previously, the velocity control name 500 max spend per day indicates that the cardholder is only authorized to spend 500 dollars per calendar day, and the transaction was declined because it would have brought the cumulative transaction amount to 750 dollars.

preceding_related_transaction_token

string
Conditionally returned

Returned for final transaction types.

Unique identifier of the preceding related transaction. Useful for identifying the transaction that preceded the current one.

For example, authorization, a temporary transaction type, precedes and is completed by authorization.clearing, a final transaction type. In this case, the authorization token is returned with this field. For which transaction types are temporary or final, see Transaction events in Event Types.

Allowable Values:

preceding_transaction

object
Conditionally returned

Returned for authorization.clearing transaction types following a financial advice.

Contains information about the preceding transaction.

Allowable Values:

preceding_transaction.amount

decimal
Conditionally returned

Amount of the preceding transaction.

Allowable Values:

preceding_transaction.token

string
Conditionally returned

Unique identifier of the preceding transaction.

Allowable Values:

amount_to_be_released

string
Conditionally returned

Amount to release following a financial advice.

Allowable Values:

incremental_authorization_transaction_tokens

array
Conditionally returned

List of incremental authorization transaction tokens.

Allowable Values:

Valid incremental authorization transaction tokens

card_acceptor

object
Conditionally returned

Contains information about the merchant.

Allowable Values:

Valid card_acceptor object

card_acceptor.mcc

string
Conditionally returned

Merchant category code (MCC).

Allowable Values:

Valid MCC.

5 char max

card_acceptor.partial_approval_capable

boolean
Conditionally returned

Whether the response can approve an amount less than or equal to the requested amount.

Allowable Values:

true, false

Default value:
false

card_acceptor.name

string
Conditionally returned

Card acceptor’s name.

Allowable Values:

50 char max

card_acceptor.street_address

string
Conditionally returned

Card acceptor’s address. May be returned if the request uses Transaction Model V2 of the Marqeta Core API. Not returned for V1 requests. See Versioning for details.

Allowable Values:

255 char max

card_acceptor.address

string
Conditionally returned

Card acceptor’s address. May be returned if the request uses Transaction Model V1 of the Marqeta Core API. Not returned for V2 requests. See Versioning for details.

Allowable Values:

255 char max

card_acceptor.city

string
Conditionally returned

Card acceptor’s city.

Allowable Values:

40 char max

card_acceptor.state

string
Conditionally returned

Card acceptor’s state.

Allowable Values:

2 char max

card_acceptor.zip

string
Conditionally returned

Card acceptor’s zip or postal code.

Allowable Values:

10 char max

card_acceptor.country_code

string
Conditionally returned

Card acceptor’s country. May be returned if the request uses Transaction Model V2 of the Marqeta Core API. Not returned for V1 requests. See Versioning for details.

Allowable Values:

card_acceptor.country

string
Conditionally returned

Card acceptor’s country. May be returned if the request uses Transaction Model V1 of the Marqeta Core API. Not returned for V2 requests. See Versioning for details.

Allowable Values:

card_acceptor.payment_facilitator_id

string
Conditionally returned

The payment facilitator identifier of the card acceptor. This field is returned if it is provided by the card network.

Allowable Values:

For Mastercard, an 11-digit number. For Visa, a variable-length alphanumeric identifier, 11 char max.

card_acceptor.independent_sales_organization_id

string
Conditionally returned

The independent sales organization identifier of the card acceptor. This field is returned if it is provided by the card network.

Allowable Values:

For Mastercard, an 11-digit number. For Visa, an 11-character alphanumeric identifier.

card_acceptor.sub_merchant_id

string
Conditionally returned

The sub-merchant identifier of the card acceptor. This field is returned if it is provided by the card network.

Allowable Values:

For Mastercard, a 15-character alphanumeric identifier. For Visa, a variable-length alphanumeric identifier, 15 char max.

from_account

string
Conditionally returned

Specifies the account type for ATM transactions.

Allowable Values:

DEFAULT. OTHER, SAVINGS, CHECKING, CREDIT_CARD, CREDIT_LINE, CORPORATE, CREDIT_FACILITY, UNIVERSAL, MONEY_MARKET_INVESTMENT, STORED_VALUE, REVOLVING_LOAN, MORTGAGE, INSTALLMENT_LOAN, CHILD_CARE_BENEFIT, CASH_BENEFIT, UNKNOWN, FOOD_STAMP

multi_clearing_sequence_number

string
Conditionally returned

If an authorization has multiple clearing transactions, this field displays the sequence number for the clearing transaction. For example, if this is the second clearing transaction of four, the sequence number is 02.

Allowable Values:

The sequence number returned in the clearing record.

multi_clearing_sequence_count

string
Conditionally returned

If an authorization has multiple clearing transactions, this field displays their total number. For example, if an authorization has four clearing transactions, the sequence count is 04.

Allowable Values:

The sequence count returned in the clearing record.

gpa

object
Conditionally returned

Contains information about the GPA balances and pending credits.

Allowable Values:

A valid gpa object.

gpa.currency_code

string
Returned

Currency of the funds used in the transaction.

Allowable Values:

A valid three-digit ISO 4217 currency type.

gpa.ledger_balance

decimal
Returned

When using standard funding: The funds that are available to spend immediately, including funds from any authorized transactions that have not yet cleared. When using Just-in-Time (JIT) Funding: Authorized funds that are currently on hold, but not yet cleared.

Allowable Values:

Format: 0.00

gpa.available_balance

decimal
Returned

Ledger balance minus any authorized transactions that have not yet cleared. Also known as the card holder’s purchasing power. When using JIT Funding, this balance is usually equal to $0.00.

Allowable Values:

Format: 0.00

gpa.pending_credits

decimal
Returned

ACH loads that have been accepted, but for which the funding time has not yet elapsed.

Allowable Values:

Format 0.00

gpa.impacted_amount

decimal
Conditionally returned

Balance change based on the amount of the transaction.

Allowable Values:

Format: 0.00

gpa.balances

object
Returned

Balances and related information for each currency used in the transaction.

Allowable Values:

A valid gpa.balances object.

gpa.balances.xxx

object
Returned

Balances and related information in the currency specified in the field name.

NOTE: In the field name, xxx represents the three-digit ISO 4217 currency type.

Allowable Values:

A valid gpa.balances.xxx object.

gpa.balances.usd.currency_code

string
Conditionally returned

Currency of balances and related information in this object.

Allowable Values:

A valid three-digit ISO 4217 currency type.

gpa.balances.usd.ledger_balance

decimal
Conditionally returned

When using standard funding: The funds that are available to spend immediately, including funds from any authorized transactions that have not yet cleared. When using Just-in-Time (JIT) Funding, authorized funds that are currently on hold, but not yet cleared.

Allowable Values:

Format: 0.00

gpa.balances.usd.available_balance

decimal
Conditionally returned

Ledger balance minus any authorized transactions that have not yet cleared. Also known as the card holder’s purchasing power. If you are using JIT Funding, this balance is usually equal to $0.00.

Allowable Values:

Format: 0.00

gpa.balances.usd.pending_credits

decimal
Conditionally returned

ACH loads that have been accepted, but for which the funding time has not yet elapsed.

Allowable Values:

Format: 0.00

gpa.balances.usd.impacted_amount

decimal
Conditionally returned

Amount to credit or debit from the GPA.

Allowable Values:

Format: 0.00

gpa_order

object
Conditionally returned

Contains information about a GPA order, including fees, funding sources, and addresses. See Orders for more information.

Allowable Values:

A valid gpa_order object.

gpa_order.token

string
Returned

Unique identifier of the funding transaction.

Allowable Values:

Format: UUID

gpa_order.amount

decimal
Returned

Amount of the funding transaction.

Allowable Values:

Format: 0.00

gpa_order.tags

string
Conditionally returned

Customer-defined tags describing the funding transaction.

Allowable Values:

99 char max

gpa_order.memo

string
Conditionally returned

Additional information describing the funding transaction.

Allowable Values:

225 char max

gpa_order.fees

array
Conditionally returned

List of fees associated with the funding transaction.

Allowable Values:

Existing fee_model objects.

gpa_order.created_time

datetime
Returned

Time when the funding transaction was last modified.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

gpa_order.last_modified_time

datetime
Returned

Time when the funding transaction was last modified.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

gpa_order.transaction_token

string
Returned

Unique identifier of the transaction being funded.

Allowable Values:

Format: UUID

gpa_order.state

string
Returned

Current status of the funding transaction.

Allowable Values:

gpa_order.response

object
Returned

Contains verification information about the funding transaction.

Allowable Values:

gpa_order.response.code

string
Conditionally returned

Assertion by the Marqeta platform, presented as a four-digit code, as to whether its verification data matches that provided by the cardholder.

Allowable Values:

One of the following assertion codes:

Code Address Postal Code

0000

Match

Match

0001

Match

Unmatched

0100

Unmatched

Match

0101

Unmatched

Unmatched

0200

Data Not Present

Match

0201

Data Not Present

Unmatched

0002

Match

Data Not Present

0102

Unmatched

Data Not Present

0303

Not Validated

Not Validated

gpa_order.response.memo

string
Conditionally returned

Additional information about the GPA order response.

Allowable Values:

99 char max

gpa_order.funding

object
Returned

Contains funding information for the transaction, including funding amount, type, and time.

Allowable Values:

gpa_order.funding.amount

decimal
Conditionally returned

Amount of funds loaded into the GPA.

Allowable Values:

Format: 0.00

gpa_order.funding.source

object
Returned

Contains funding source information for the transaction, including funding type and time.

Allowable Values:

gpa_order.funding.source.type

string
Returned

Funding type of the funding source.

Allowable Values:

ach, paymentcard

gpa_order.funding.source.token

string
Returned

Unique identifier of the funding source.

Allowable Values:

Format: UUID

gpa_order.funding.source.active

boolean
Returned

Whether the funding source is active.

Allowable Values:

true, false

Default value:
false

gpa_order.funding.source.is_default_account

boolean
Returned

Whether the funding source is the default account.

Allowable Values:

true, false

gpa_order.funding.source.created_time

datetime
Returned

Time when the funding source was created.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

gpa_order.funding.source.last_modified_time

datetime
Returned

Time when the funding source was last modified.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

gpa_order.funding.source_address

object
Conditionally returned

Contains information about the billing address of the funding source.

Allowable Values:

gpa_order.funding.source_address.user_token

OR

gpa_order.funding.source_address.business_token

string
Returned

Unique identifier of the account holder associated with the address.

Allowable Values:

Existing user or business token.

gpa_order.funding.source_address.token

string
Returned

Unique identifier of the address.

Allowable Values:

36 char max

Format: UUID

gpa_order.funding.source_address.first_name

string
Returned

First name of the account holder associated with the funding source.

Allowable Values:

40 char max

gpa_order.funding.source_address.last_name

string
Returned

Last name of the account holder associated with the funding source.

Allowable Values:

40 char max

gpa_order.funding.source_address.address_1

string
Returned

Street address of the funding source.

Allowable Values:

225 char max

gpa_order.funding.source_address.address_2

string
Conditionally returned

Additional address information for the funding source.

Allowable Values:

225 char max

gpa_order.funding.source_address.city

string
Returned

City of the funding source.

Allowable Values:

40 char max

gpa_order.funding.source_address.state

string
Returned

State of the funding source.

Allowable Values:

2 char max

gpa_order.funding.source_address.zip

string
Returned

Zip code of the funding source.

Allowable Values:

10 char max

gpa_order.funding.source_address.postal_code

string
Returned

Postal code of the funding source.

Allowable Values:

10 char max

gpa_order.funding.source_address.country

string
Returned

Country of the funding source.

Allowable Values:

40 char max

gpa_order.funding.source_address.phone

string
Conditionally returned

Phone number of the funding source.

Allowable Values:

255 char max

gpa_order.funding.source_address.is_default_address

boolean
Conditionally returned

Whether this address is the default address used by the funding source.

Allowable Values:

true, false

Default value:
false

gpa_order.funding.source_address.active

boolean
Conditionally returned

Whether the address is active.

Allowable Values:

true, false

Default value:
false

gpa_order.funding.source_address.created_time

datetime
Conditionally returned

Date and time when the address was created.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

gpa_order.funding.source_address.last_modified_time

datetime
Conditionally returned

Date and time when the address was last modified.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

gpa_order.funding.gateway_log

object
Conditionally returned

Contains information from the gateway in response to a funding request.

Allowable Values:

gpa_order.funding.gateway_log.order_number

string
Returned

Customer order number, same value as transaction.token.

Allowable Values:

Existing transaction.token value.

gpa_order.funding.gateway_log.transaction_id

string
Returned

Customer-defined identifier for the transaction.

Allowable Values:

gpa_order.funding.gateway_log.message

string
Returned

Message about the status of the funding request. Useful for determining whether it was approved and completed successfully, declined by the gateway, or timed out.

Allowable Values:

Approved or completed successfully, Declined by gateway, Operation timeout

gpa_order.funding.gateway_log.duration

integer
Conditionally returned

Length of time the gateway took to respond to a funding request.

Allowable Values:

Format: int64

gpa_order.funding.gateway_log.timed_out

boolean
Conditionally returned

Whether the gateway sent a response (true) or timed out (false).

Allowable Values:

Default value:
false

gpa_order.funding.gateway_log.response

object
Conditionally returned

Contains information on the gateway’s response to a funding request.

Allowable Values:

Existing response object.

gpa_order.funding.gateway_log.response.code

string
Returned

Code received from the gateway.

Allowable Values:

gpa_order.funding.gateway_log.response.data

object
Conditionally returned

Any additional data sent by the gateway.

Allowable Values:

gpa_order.funding.gateway_log.response.data.jit_funding

object
Returned

Contains the gateway’s information about the JIT Funding transaction.

Allowable Values:

gpa_order.funding.gateway_log.response.data.jit_funding.token

string
Returned

Unique identifier of the JIT Funding request and response.

Allowable Values:

Existing JIT Funding token matching the request.

36 char max

gpa_order.funding.gateway_log.response.data.jit_funding.method

string
Returned

JIT Funding response type.

Allowable Values:

Existing JIT Funding method matching the request.

36 char max

See The jit_funding object for the purpose, funding event type, and description of each method.

gpa_order.funding.gateway_log.response.data.jit_funding.user_token

OR

gpa_order.funding.gateway_log.response.data.jit_funding.business_token

string
Returned

Holder of the account to be funded.

Either a user_token or business_token field is present, not both.

Allowable Values:

Existing user or business token matching the request.

36 char max

gpa_order.funding.gateway_log.response.data.jit_funding.acting_user_token

string
Conditionally returned

User who conducted the transaction.

Can be a child user configured to share its parent’s account balance.

Allowable Values:

Existing user token matching the request.

36 char max

gpa_order.funding.gateway_log.response.data.jit_funding.amount

decimal
Returned

Requested amount of funding.

Allowable Values:

Format: 0.00

If partial_approval_capable is false, the response amount must match the request amount. If partial_approval_capable is true, the response amount must be equal to or less than the request amount and greater than zero.

NOTE: The JIT Funding request contains multiple amount fields. Ensure that you use the value from gpa_order.jit_funding.amount. Do not use the value from the top-level amount field or any other amount field because those fields might contain a value different from the gpa_order.jit_funding.amount field. In particular, amount fields will differ if the account being funded has a positive account balance before JIT Funding is requested. Associated fees can also cause amount field values to differ.

gpa_order.funding.gateway_log.response.data.jit_funding.memo

string
Conditionally returned

Additional information on the JIT Funding transaction.

Returned for authorization and authorization completion transactions.

Allowable Values:

99 char max

gpa_order.funding.gateway_log.response.data.jit_funding.original_jit_funding_token

string
Conditionally returned

Token of the first associated JIT Funding message. Useful for correlating related JIT Funding messages (that is, those associated with the same GPA order). Not included in the first of any set of related messages.

Allowable Values:

Existing original JIT Funding token matching the request.

36 char max

gpa_order.funding.gateway_log.response.data.jit_funding.incremental_authorization_jit_funding_tokens

array of strings
Conditionally returned

Array of tokens referencing the JIT Funding tokens of all previous associated incremental authorization JIT Funding requests. Useful for ascertaining the final transaction amount when the original amount was incremented.

Allowable Values:

Existing incremental authorization JIT funding tokens.

gpa_order.funding.gateway_log.response.data.jit_funding.address_verification

object
Conditionally returned

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.

Allowable Values:

Existing gpa_order.funding.gateway_log.response.data.jit_funding.address_verification object.

gpa_order.funding.gateway_log.response.data.jit_funding.address_verification.request

object
Conditionally returned

Contains address verification data provided by the cardholder.

Allowable Values:

gpa_order.funding.gateway_log.response.data.jit_funding.address_verification.request.street_address

string
Conditionally returned

Street address provided by the cardholder.

Allowable Values:

40 char max

gpa_order.funding.gateway_log.response.data.jit_funding.address_verification.request.zip

string
Conditionally returned

Postal code provided by the cardholder.

Allowable Values:

9 char max

gpa_order.funding.gateway_log.response.data.jit_funding.address_verification.issuer

object
Conditionally returned

Contains the address verification data held by the Marqeta platform and its assertion as to whether its address verification data matches that provided by the cardholder.

Allowable Values:

gpa_order.funding.gateway_log.response.data.jit_funding.address_verification.issuer.on_file

object
Conditionally returned

Contains address verification data held by the Marqeta platform.

Allowable Values:

An existing gpa_order.jit_funding.address_verification.issuer.on_file object.

gpa_order.funding.gateway_log.response.data.jit_funding.address_verification.issuer.on_file.street_address

string
Conditionally returned

Street address provided by the Marqeta platform.

This field is a concatenation of the address1 and address2 fields associated with the cardholder.

Allowable Values:

40 char max

gpa_order.funding.gateway_log.response.data.jit_funding.address_verification.issuer.on_file.zip

string
Conditionally returned

Zip code provided by the Marqeta platform.

Allowable Values:

gpa_order.funding.gateway_log.response.data.jit_funding.address_verification.issuer.on_file.postal_code

string
Conditionally returned

Postal code provided by the Marqeta platform.

Allowable Values:

gpa_order.funding.gateway_log.response.data.jit_funding.address_verification.issuer.response

object
Conditionally returned

Contains the Marqeta platform’s assertion as to whether its address verification data matches that provided by the cardholder.

Allowable Values:

Existing gpa_order.jit_funding.address_verification.issuer.response object.

gpa_order.funding.gateway_log.response.data.jit_funding.address_verification.issuer.response.code

string
Returned

Assertion by the Marqeta platform as to whether its address verification data matches that provided by the cardholder. The assertion is presented as a four-digit code.

Allowable Values:

One of the following assertion codes:

Code Address Postal Code

0000

Match

Match

0001

Match

Unmatched

0100

Unmatched

Match

0101

Unmatched

Unmatched

0200

Data Not Present

Match

0201

Data Not Present

Unmatched

0002

Match

Data Not Present

0102

Unmatched

Data Not Present

0303

Not Validated

Not Validated

gpa_order.funding.gateway_log.response.data.jit_funding.address_verification.issuer.response.memo

string
Returned

Additional information on the address verification.

Returned for authorization and authorization completion transactions.

Allowable Values:

99 char max

gpa_order.funding.gateway_log.response.data.jit_funding.address_verification.gateway

object
Conditionally returned

Contains gateway-held address verification data and the gateway’s assertion as to whether its data matches the data provided by the cardholder.

Returned when overriding the assertion provided in the JIT Funding request.

Allowable Values:

Existing gpa_order.funding.gateway_log.response.data.jit_funding.address_verification.gateway object.

gpa_order.funding.gateway_log.response.data.jit_funding.address_verification.gateway.on_file

object
Conditionally returned

Contains address verification data held by the gateway.

Allowable Values:

Existing gpa_order.funding.gateway_log.response.data.jit_funding.address_verification.gateway.on_file object.

gpa_order.funding.gateway_log.response.data.jit_funding.address_verification.gateway.on_file.street_address

string
Conditionally returned

Street address provided by the gateway.

Allowable Values:

40 char max

gpa_order.funding.gateway_log.response.data.jit_funding.address_verification.gateway.on_file.zip

string
Conditionally returned

Zip code provided by the gateway.

Allowable Values:

gpa_order.funding.gateway_log.response.data.jit_funding.address_verification.gateway.on_file.postal_code

string
Conditionally returned

Postal code provided by the gateway.

Allowable Values:

gpa_order.funding.gateway_log.response.data.jit_funding.address_verification.gateway.response

object
Conditionally returned

Contains the gateway’s assertion as to whether its address verification data matches the cardholder’s.

Allowable Values:

Existing gpa_order.funding.gateway_log.response.data.jit_funding.address_verification.gateway.response object.

gpa_order.funding.gateway_log.response.data.jit_funding.address_verification.gateway.response.code

string
Returned

Gateway’s assertion as to whether the address verification data provided by the gateway and cardholder match. The assertion is presented as a four-digit code.

Allowable Values:

One of the following assertion codes:

Code Address Postal Code

0000

Match

Match

0001

Match

Unmatched

0100

Unmatched

Match

0101

Unmatched

Unmatched

0200

Data Not Present

Match

0201

Data Not Present

Unmatched

0002

Match

Data Not Present

0102

Unmatched

Data Not Present

0303

Not Validated

Not Validated

gpa_order.funding.gateway_log.response.data.jit_funding.address_verification.gateway.response.memo

string
Returned

Additional information on about the address verification.

Returned for authorization and authorization completion transactions.

Allowable Values:

99 char max

gpa_order.funding.gateway_log.response.data.jit_funding.balances

object
Conditionally returned

Contains the GPA’s balance details.

Allowable Values:

Existing gpa_order.funding.gateway_log.response.data.jit_funding.balances object.

gpa_order.funding.gateway_log.response.data.jit_funding.balances.currency_code

string
Returned

Currency of the funds used in the transaction.

Allowable Values:

A valid three-digit ISO 4217 currency type. For example, USD.

gpa_order.funding.gateway_log.response.data.jit_funding.balances.ledger_balance

decimal
Returned

Authorized funds that are currently on hold but not yet cleared.

Allowable Values:

Format: 0.00

gpa_order.funding.gateway_log.response.data.jit_funding.balances.available_balance

decimal
Returned

Ledger balance minus any authorized transactions that have not yet cleared. Also known as the card holder’s purchasing power. When using JIT Funding, this balance is usually equal to $0.00.

Allowable Values:

Format: 0.00

gpa_order.funding.gateway_log.response.data.jit_funding.balances.pending_credits

decimal
Returned

ACH loads that have been accepted, but for which the funding time has not yet elapsed.

Allowable Values:

gpa_order.funding.gateway_log.response.data.jit_funding.balances.impacted_amount

decimal
Conditionally returned

Balance change based on the amount of the transaction.

Allowable Values:

gpa_order.funding_source_token

string
Returned

Unique identifier of the funding source.

Allowable Values:

Existing funding source token.

gpa_order.funding_source_address_token

string
Returned

Unique identifier of the funding source address.

Allowable Values:

Existing funding source address token.

gpa_order.jit_funding

object
Returned

Contains the information about the JIT Funding load event, where funds are loaded into an account.

Allowable Values:

An existing gpa_order.jit_funding object.

gpa_order.jit_funding.token

string
Returned

Unique identifier of the JIT Funding notification.

Allowable Values:

Existing JIT Funding token matching the funding.gateway_log.transaction_id field of the associated general purpose account (GPA) order. Note that the transaction_id field updates if a subsequent JIT Funding message associated with that GPA order is sent. If multiple JIT Funding messages are associated with the same GPA order, the transaction_id field matches the token of the most recent message.

36 char max

gpa_order.jit_funding.method

string
Returned

JIT Funding notification type.

Allowable Values:

pgfs.authorization, pgfs.balanceinquiry, pgfs.authorization.incremental, pgfs.authorization.capture, pgfs.authorization.reversal, pgfs.auth_plus_capture, pgfs.refund, pgfs.force_capture, pgfs.authorization.capture.chargeback, pgfs.authorization.capture.chargeback.reversal, pgfs.pindebit.chargeback, pgfs.pindebit.chargeback.reversal, pgfs.directdeposit.credit, pgfs.directdeposit.debit, pgfs.directdeposit.credit.reversal, pgfs.directdeposit.debit.reversal, pgfs.adjustment.credit, pgfs.adjustment.debit, pgfs.auth_plus_capture.standin, pgfs.authorization.standin, pgfs.network.load, pgfs.original.credit.authorization, pgfs.original.credit.auth_plus_capture, pgfs.refund.authorization, pgfs.refund.authorization.reversal

See The jit_funding object for the purpose, funding event type, and description of each method.

gpa_order.jit_funding.user_token

OR

gpa_order.jit_funding.business_token

string
Returned

Holder of the account that was funded.

Either a user_token or business_token field is present, not both.

Allowable Values:

Existing user or business token value.

36 char max

gpa_order.jit_funding.acting_user_token

string
Conditionally returned

User who conducted the transaction.

Can be a child user configured to share its parent’s account balance.

Allowable Values:

Existing user token value.

36 char max

gpa_order.jit_funding.amount

decimal
Returned

Requested amount of funding.

NOTE: This field’s value can differ from the transaction’s top-level amount field or any other amount field within the transaction. In particular, these fields will differ if the account being funded already has a positive account balance. Associated fees can also cause these fields to differ.

Allowable Values:

Format: 0.00

gpa_order.jit_funding.memo

string
Conditionally returned

Additional information that describes the JIT funding transaction.

Allowable Values:

key-value pairs

99 char max

gpa_order.jit_funding.tags

string
Conditionally returned

Customer-defined tag for the JIT funding transaction.

Allowable Values:

255 char max

gpa_order.jit_funding.original_jit_funding_token

string
Conditionally returned

Token of the first associated JIT Funding message. Useful for correlating related JIT Funding messages (that is, those associated with the same GPA order). Not included in the first of any set of related messages.

Allowable Values:

Existing JIT Funding token value.

36 char max

gpa_order.jit_funding.incremental_authorization_jit_funding_tokens

array of strings
Conditionally returned

Array of tokens referencing the JIT Funding tokens of all previous associated incremental authorization JIT Funding requests. Useful for ascertaining the final transaction amount when the original amount was incremented.

Allowable Values:

Existing incremental authorization JIT funding tokens.

gpa_order.jit_funding.address_verification

object
Conditionally returned

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.

Allowable Values:

Existing gpa_order.jit_funding.address_verification object.

gpa_order.jit_funding.address_verification.request

object
Conditionally returned

Contains address verification data provided by the cardholder.

Allowable Values:

Existing gpa_order.jit_funding.address_verification.request object.

gpa_order.jit_funding.address_verification.request.street_address

string
Conditionally returned

Street address provided by the cardholder.

Allowable Values:

40 char max

gpa_order.jit_funding.address_verification.request.zip

string
Conditionally returned

Postal code provided by the cardholder.

Allowable Values:

9 char max

gpa_order.jit_funding.address_verification.issuer

object
Conditionally returned

Contains the address verification data held by the Marqeta platform and its assertion as to whether its address verification data matches that provided by the cardholder.

Allowable Values:

gpa_order.jit_funding.address_verification.issuer.on_file

object
Conditionally returned

Contains address verification data held by the Marqeta platform.

Allowable Values:

An existing gpa_order.jit_funding.address_verification.issuer.on_file object.

gpa_order.jit_funding.address_verification.issuer.on_file.street_address

string
Conditionally returned

Street address provided by the Marqeta platform.

This field is a concatenation of the address1 and address2 fields associated with the cardholder.

Allowable Values:

40 char max

gpa_order.jit_funding.address_verification.issuer.on_file.zip

string
Conditionally returned

Zip code provided by the Marqeta platform.

Allowable Values:

gpa_order.jit_funding.address_verification.issuer.on_file.postal_code

string
Conditionally returned

Postal code provided by the Marqeta platform.

Allowable Values:

gpa_order.jit_funding.address_verification.issuer.response

object
Conditionally returned

Contains the Marqeta platform’s assertion as to whether its address verification data matches that provided by the cardholder.

Allowable Values:

Existing gpa_order.jit_funding.address_verification.issuer.response object.

gpa_order.jit_funding.address_verification.issuer.response.code

string
Returned

Assertion by the Marqeta platform as to whether its address verification data matches that provided by the cardholder. The assertion is presented as a four-digit code.

Allowable Values:

One of the following assertion codes:

Code Address Postal Code

0000

Match

Match

0001

Match

Unmatched

0100

Unmatched

Match

0101

Unmatched

Unmatched

0200

Data Not Present

Match

0201

Data Not Present

Unmatched

0002

Match

Data Not Present

0102

Unmatched

Data Not Present

0303

Not Validated

Not Validated

gpa_order.jit_funding.address_verification.issuer.response.memo

string
Returned

Additional information on the address verification.

Returned for authorization and authorization completion transactions.

Allowable Values:

99 char max

gpa_order.jit_funding.address_verification.gateway

object
Conditionally returned

Contains gateway-held address verification data and the gateway’s assertion as to whether its data matches the data provided by the cardholder.

Returned when overriding the assertion provided in the JIT Funding request.

Allowable Values:

Existing gpa_order.jit_funding.address_verification.gateway.on_file object.

gpa_order.jit_funding.address_verification.gateway.on_file

object
Conditionally returned

Contains address verification data held by the gateway.

Allowable Values:

Existing gpa_order.jit_funding.address_verification.gateway.on_file object.

gpa_order.jit_funding.address_verification.gateway.on_file.street_address

string
Conditionally returned

Street address provided by the gateway.

Allowable Values:

40 char max

gpa_order.jit_funding.address_verification.gateway.on_file.zip

string
Conditionally returned

Zip code provided by the gateway.

Allowable Values:

gpa_order.jit_funding.address_verification.gateway.on_file.postal_code

string
Conditionally returned

Postal code provided by the gateway.

Allowable Values:

gpa_order.jit_funding.address_verification.gateway.response

object
Conditionally returned

Contains the gateway’s assertion as to whether its address verification data matches the cardholder’s.

Allowable Values:

Existing gpa_order.jit_funding.address_verification.gateway.response object.

gpa_order.jit_funding.address_verification.gateway.response.code

string
Returned

Gateway’s assertion as to whether the address verification data provided by the gateway and cardholder match. The assertion is presented as a four-digit code.

Allowable Values:

One of the following assertion codes:

Code Address Postal Code

0000

Match

Match

0001

Match

Unmatched

0100

Unmatched

Match

0101

Unmatched

Unmatched

0200

Data Not Present

Match

0201

Data Not Present

Unmatched

0002

Match

Data Not Present

0102

Unmatched

Data Not Present

0303

Not Validated

Not Validated

gpa_order.jit_funding.address_verification.gateway.response.memo

string
Returned

Additional information on the address verification.

Returned for authorization and authorization completion transactions.

Allowable Values:

99 char max

gpa_order.jit_funding.balances

object
Conditionally returned

Contains the GPA’s balance details.

Allowable Values:

Existing gpa_order.jit_funding.balances object.

gpa_order.jit_funding.balances.currency_code

string
Returned

Currency of the funds used in the transaction.

Allowable Values:

A valid three-digit ISO 4217 currency type. For example, USD.

gpa_order.jit_funding.balances.ledger_balance

decimal
Returned

Authorized funds that are currently on hold but not yet cleared.

Allowable Values:

Format: 0.00

gpa_order.jit_funding.balances.available_balance

decimal
Returned

Ledger balance minus any authorized transactions that have not yet cleared. Also known as the card holder’s purchasing power. When using JIT Funding, this balance is usually equal to $0.00.

Allowable Values:

Format 0.00

gpa_order.jit_funding.balances.pending_credits

decimal
Returned

ACH loads that have been accepted, but for which the funding time has not yet elapsed.

Allowable Values:

gpa_order.jit_funding.balances.impacted_amount

decimal
Conditionally returned

Balance change based on the amount of the transaction.

Allowable Values:

gpa_order.user_token

OR

gpa_order.business_token

string
Returned

Unique identifier of the account holder of the account being funded.

Allowable Values:

Existing user or business token.

Send a GET request to /users to retrieve user tokens or to /businesses to retrieve business tokens.

gpa_order.currency_code

string
Returned

Currency of the funding transaction.

Allowable Values:

3-character ISO 4217 currency code

card

object
Conditionally returned

Contains information about a specific card.

Allowable Values:

Existing card object.

card.created_time

datetime
Returned

Date and time when the card was created.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

card.last_modified_time

datetime
Returned

Date and time when the card was last modified.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

card.token

string
Returned

Unique identifier of the card.

Allowable Values:

36 char max

card.user_token

string
Returned

Unique identifier of the authorized user of the card.

Allowable Values:

Existing user token.

36 char max

card.card_product_token

string
Returned

Unique identifier of the card product.

Allowable Values:

Existing card product token.

36 char max

card.last_four

string
Returned

Last four digits of the card PAN.

Allowable Values:

card.pan

string
Returned

PAN of the card.

Allowable Values:

Existing card PAN.

card.cvv_number

string
Conditionally returned

Three-digit card verification value (CVV2) included on the back of the card.

Allowable Values:

3 char max

card.chip_cvv_number

string
Conditionally returned

Three-digit card verification value (CVV2) included on the back of the card.

Allowable Values:

card.barcode

string
Conditionally returned

Barcode of the card.

Allowable Values:

card.pin_is_set

boolean
Returned

Whether a PIN was set.

Allowable Values:

true, false

Default value:
false

card.state

string
Returned

State of the card.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED, UNSUPPORTED, UNACTIVATED

card.state_reason

string
Returned

Reason for the state of the card.

Allowable Values:

card.fulfillment

object
Returned

Status of the card fulfillment.

Allowable Values:

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

card.fulfillment.shipping

object
Conditionally returned

Contains information about the card fulfillment’s shipping address.

Allowable Values:

Existing fulfillment.shipping object.

card.fulfillment.shipping.method

string
Conditionally returned

Method of shipment.

Allowable Values:

card.fulfillment.shipping.return_address

object
Conditionally returned

Contains information about the card fulfillment’s return address, in case it could not be shipped.

Allowable Values:

card.fulfillment.shipping.return_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

card.fulfillment.shipping.return_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

card.fulfillment.shipping.return_address.address_1

string
Conditionally returned

Street address

Allowable Values:

225 char max

card.fulfillment.shipping.return_address.address_2

string
Conditionally returned

Additional address information.

Allowable Values:

225 char max

card.fulfillment.shipping.return_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

card.fulfillment.shipping.return_address.state

string
Conditionally returned

State.

Allowable Values:

2 char max

card.fulfillment.shipping.return_address.zip

string
Conditionally returned

Zip code.

Allowable Values:

10 char max

card.fulfillment.shipping.return_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

card.fulfillment.shipping.return_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

card.fulfillment.shipping.return_address.phone

string
Conditionally returned

Phone number.

Allowable Values:

20 char max

card.fulfillment.shipping.recipient_address

object
Conditionally returned

Contains information about the address of the recipient.

Allowable Values:

card.fulfillment.shipping.recipient_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

card.fulfillment.shipping.recipient_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

card.fulfillment.shipping.recipient_address.address_1

string
Conditionally returned

Street address.

Allowable Values:

225 char max

card.fulfillment.shipping.recipient_address.address_2

string
Conditionally returned

Additional address information.

Allowable Values:

225 char max

card.fulfillment.shipping.recipient_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

card.fulfillment.shipping.recipient_address.state

string
Conditionally returned

State.

Allowable Values:

2 char max

card.fulfillment.shipping.recipient_address.zip

string
Conditionally returned

Zip code.

Allowable Values:

10 char max

card.fulfillment.shipping.recipient_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

card.fulfillment.shipping.recipient_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

card.fulfillment.shipping.recipient_address.phone

string
Conditionally returned

Phone number.

Allowable Values:

20 char max

card.fulfillment.shipping.care_of_line

object
Conditionally returned

Name of person or company receiving the card on behalf of the recipient.

Allowable Values:

card.fulfillment.card_personalization

object
Returned

Contains information about personalized attributes added to the card.

Allowable Values:

Existing card_personalization object.

card.fulfillment.text

object
Returned

Contains personalized text that appears on the card.

Allowable Values:

Existing fulfillment.card_personalization.text object.

card.fulfillment.text.name_line_1.value

string
Returned

First line of personalized text printed on the face of the card.

Allowable Values:

Valid characters differ according to your fulfillment provider:

  • For Arroweye Solutions, IDEMIA Poland, and IDEMIA Czech Republic, all characters are valid. For specific character and language guidelines, contact your fulfillment provider.

  • For all other providers, valid characters are:

    • A-Z (uppercase letters)

    • a-z (lowercase letters)

    • 0-9 (integers)

    •   (space)

    • . (period)

    • , (comma)

    • / (forward slash)

    • - (hyphen)

    • & (ampersand)

    • ' (single quote)

    • @ (stylized D for Discover cards)

21 char max. Strings longer than 21 characters are truncated.

card.fulfillment.text.name_line_2.value

string
Conditionally returned

Second line of personalized text printed on the face of the card.

Allowable Values:

Valid characters differ according to your fulfillment provider:

  • For Arroweye Solutions, IDEMIA Poland, and IDEMIA Czech Republic, all characters are valid. For specific character and language guidelines, contact your fulfillment provider.

  • For all other providers, valid characters are:

    • A-Z (uppercase letters)

    • a-z (lowercase letters)

    • 0-9 (integers)

    •   (space)

    • . (period)

    • , (comma)

    • / (forward slash)

    • - (hyphen)

    • & (ampersand)

    • ' (single quote)

    • @ (stylized D for Discover cards)

21 char max. Strings longer than 21 characters are truncated.

card.fulfillment.text.name_line_3.value

string
Conditionally returned

Third line of personalized text printed on the face of the card.

Allowable Values:

Valid characters differ according to your fulfillment provider:

  • For Arroweye Solutions, IDEMIA Poland, and IDEMIA Czech Republic, all characters are valid. For specific character and language guidelines, contact your fulfillment provider.

  • For all other providers, valid characters are:

    • A-Z (uppercase letters)

    • a-z (lowercase letters)

    • 0-9 (integers)

    •   (space)

    • . (period)

    • , (comma)

    • / (forward slash)

    • - (hyphen)

    • & (ampersand)

    • ' (single quote)

    • @ (stylized D for Discover cards)

21 char max. Strings longer than 21 characters are truncated.

card.fulfillment.carrier

object
Conditionally returned

Contains attributes of the card carrier (if your fulfillment provider is Arroweye Solutions).

Allowable Values:

Existing fulfillment.card_personalization.carrier object.

card.fulfillment.carrier.template_id

string
Conditionally returned

Card carrier template to use.

Allowable Values:

A card carrier template ID.

card.fulfillment.carrier.logo_file

string
Conditionally returned

Image to display on the card carrier.

Allowable Values:

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

card.fulfillment.carrier.logo_thumbnail_file

string
Conditionally returned

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

Allowable Values:

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

card.fulfillment.carrier.message_file

string
Conditionally returned

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

Allowable Values:

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

card.fulfillment.carrier.message_line

string
Conditionally returned

Specifies a custom message that appears on the card carrier.

Allowable Values:

60 char max

card.fulfillment.images

object
Conditionally returned

Contains personalized images that appear on the card (for individual card orders only). Also specifies attributes of the card carrier, if your fulfillment provider is Perfect Plastic Printing or IDEMIA.

NOTE: The images object does not store or pass any actual image data. It only specifies image files that you send to your fulfillment provider.

Allowable Values:

Existing fulfillment.card_personalization.images object.

card.fulfillment.images.card

object
Conditionally returned

Specifies personalized images that appear on the card.

Allowable Values:

card.fulfillment.images.card.name

string
Conditionally returned

Specifies a PNG image to display on the card.

Allowable Values:

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

Must end in .png.

card.fulfillment.images.card.thermal_color

string
Conditionally returned

Specifies the color of the image displayed on the card.

Allowable Values:

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

card.fulfillment.images.signature.name

string
Conditionally returned

Specifies a PNG image of the cardholder’s signature.

Allowable Values:

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

Must end in .png.

card.fulfillment.images.carrier_return_window.name

string
Conditionally returned

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

Allowable Values:

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

Must end in .png.

card.fulfillment.perso_type

string
Optional

Specifies the method for printing personalized text on the card.

Allowable Values:

EMBOSS, LASER, FLAT

card.fulfillment.card_fulfillment_reason

string
Conditionally returned

Specifies the reason for card fulfillment.

Allowable Values:

NEW, LOST_STOLEN, EXPIRED

card.instrument_type

string
Conditionally returned

Instrument type of the card used in the transaction.

  • PHYSICAL_MSR: A physical card with a magnetic stripe. This is the default physical card type.

  • PHYSICAL_ICC: A physical card with an integrated circuit, or "chip."

  • PHYSICAL_CONTACTLESS: A physical card that uses radio frequency identification (RFID) or near-field communication (NFC) to enable payment over a secure radio interface.

  • PHYSICAL_COMBO: A physical card with a chip that also supports contactless payments.

  • VIRTUAL_PAN: A virtual card with a PAN.

Allowable Values:

PHYSICAL_MSR, PHYSICAL_ICC, PHYSICAL_CONTACTLESS, PHYSICAL_COMBO, VIRTUAL_PAN

card.expedite

boolean
Conditionally returned

Whether to expedite the card.

Allowable Values:

true, false

Default value:
false

card.metadata

object
Returned

Custom metadata associated with the card used in the transaction.

Allowable Values:

Customer-defined strings as key/value pairs.

gpa_order_unload

object
Conditionally returned

Contains information about a GPA order unload, which unloads a GPA order by returning funds to the funding source.

Allowable Values:

gpa_order_unload.token

string
Returned

Unique identifier of the GPA order unload.

Allowable Values:

gpa_order_unload.amount

decimal
Returned

Amount of funds to return to funding source.

Allowable Values:

gpa_order_unload.created_time

datetime
Returned

Date and time when the GPA order unload was created.

Allowable Values:

gpa_order_unload.last_modified_time

datetime
Returned

Date and time when the GPA order unload was last modified.

Allowable Values:

gpa_order_unload.transaction_token

string
Returned

Unique identifier of the original funding transaction to unload.

Allowable Values:

Existing transaction token.

gpa_order_unload.state

string
Returned

Current status of the GPA order unload.

Allowable Values:

gpa_order_unload.response

object
Returned

Contains verification information for the GPA order unload.

Allowable Values:

gpa_order_unload.response.code

string
Conditionally returned

Four-digit code asserting whether its verification data matches that provided by the cardholder.

Allowable Values:

gpa_order_unload.response.memo

string
Conditionally returned

Additional comments about the outcome of the verification.

Allowable Values:

gpa_order_unload.funding

object
Returned

Contains funding information for the GPA order unload, including funding amount, type, and time.

Allowable Values:

gpa_order_unload.funding.amount

decimal
Conditionally returned

Amount of funds unloaded and returned to the funding source.

Allowable Values:

gpa_order_unload.funding.source

object
Conditionally returned

Contains funding source information for the GPA order unload, including funding type and time.

Allowable Values:

gpa_order_unload.funding.source.type

string
Conditionally returned

Funding type of the funding source.

Allowable Values:

gpa_order_unload.funding.source.token

string
Conditionally returned

Unique identifier of the funding source.

Allowable Values:

gpa_order_unload.funding.source.active

boolean
Conditionally returned

Whether the funding source is active.

Allowable Values:

true, false

gpa_order_unload.funding.source.name

string
Conditionally returned

Name of the funding source.

Allowable Values:

gpa_order_unload.funding.source.is_default_account

boolean
Conditionally returned

Whether the GPA order unload’s funding source is the default funding account.

Allowable Values:

true, false

gpa_order_unload.funding.source.created_time

datetime
Conditionally returned

Date and time when the funding source was created.

Allowable Values:

gpa_order_unload.funding.source.last_modified_time

datetime
Conditionally returned

Date and time when the funding source was last modified.

Allowable Values:

gpa_order_unload.funding_source_token

string
Returned

Unique identifier of the funding source to which to return funds.

Allowable Values:

Existing funding source token.

gpa_order_unload.jit_funding

object
Conditionally returned

Contains information about the JIT Funding unload event, where funds are removed from an account.

Allowable Values:

Existing gpa_order_unload.jit_funding event.

gpa_order_unload.jit_funding.token

string
Returned

Unique identifier of the JIT Funding notification.

Allowable Values:

Existing JIT Funding token matching the funding.gateway_log.transaction_id field of the associated general purpose account (GPA) order. Note that the transaction_id field updates if a subsequent JIT Funding message associated with that GPA order is sent. If multiple JIT Funding messages are associated with the same GPA order, the transaction_id field matches the token of the most recent message.

36 char max

gpa_order_unload.jit_funding.method

string
Returned

JIT Funding notification type.

Allowable Values:

pgfs.authorization, pgfs.balanceinquiry, pgfs.authorization.incremental, pgfs.authorization.capture, pgfs.authorization.reversal, pgfs.auth_plus_capture, pgfs.refund, pgfs.force_capture, pgfs.authorization.capture.chargeback, pgfs.authorization.capture.chargeback.reversal, pgfs.pindebit.chargeback, pgfs.pindebit.chargeback.reversal, pgfs.directdeposit.credit, pgfs.directdeposit.debit, pgfs.directdeposit.credit.reversal, pgfs.directdeposit.debit.reversal, pgfs.adjustment.credit, pgfs.adjustment.debit, pgfs.auth_plus_capture.standin, pgfs.authorization.standin, pgfs.network.load, pgfs.original.credit.authorization, pgfs.original.credit.auth_plus_capture, pgfs.refund.authorization, pgfs.refund.authorization.reversal

See The jit_funding object for the purpose, funding event type, and description of each method.

gpa_order_unload.jit_funding.user_token

OR

gpa_order_unload.jit_funding.business_token

string
Returned

Holder of the account that was funded.

Either a user_token or business_token field is present, not both.

Allowable Values:

Existing user or business token value.

36 char max

gpa_order_unload.jit_funding.acting_user_token

string
Returned

User who conducted the transaction.

Can be a child user configured to share its parent’s account balance.

Allowable Values:

Existing user token value.

36 char max

gpa_order_unload.jit_funding.amount

decimal
Returned

Requested amount of funding.

NOTE: This field’s value can differ from the transaction’s top-level amount field or any other amount field within the transaction. In particular, these fields will differ if the account being funded already has a positive account balance. Associated fees can also cause these fields to differ.

Allowable Values:

Format: 0.00

gpa_order_unload.jit_funding.memo

string
Conditionally returned

Additional information that describes the JIT funding transaction.

Allowable Values:

99 char max

gpa_order_unload.jit_funding.tags

string
Conditionally returned

Customer-defined tags for the JIT funding transaction.

Allowable Values:

255 char max

gpa_order_unload.jit_funding.original_jit_funding_token

string
Conditionally returned

Token of the first associated JIT Funding message. Useful for correlating related JIT Funding messages (that is, those associated with the same GPA order). Not included in the first of any set of related messages.

Allowable Values:

Existing JIT Funding token value.

36 char max

gpa_order_unload.jit_funding.incremental_authorization_jit_funding_tokens

array of strings
Conditionally returned

List of tokens referencing the JIT Funding tokens of all previous associated incremental authorization JIT Funding requests. Useful for ascertaining the final transaction amount when the original amount was incremented.

Allowable Values:

Existing JIT funding tokens.

gpa_order_unload.jit_funding.address_verification

object
Conditionally returned

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.

Allowable Values:

Existing gpa_order_unload.jit_funding.address_verification object.

gpa_order_unload.jit_funding.address_verification.request

object
Conditionally returned

Contains address verification data provided by the cardholder.

Allowable Values:

Existing gpa_order_unload.jit_funding.address_verification.request object.

gpa_order_unload.jit_funding.address_verification.request.street_address

string
Conditionally returned

Street address provided by the cardholder.

Allowable Values:

40 char max

gpa_order_unload.jit_funding.address_verification.request.zip

string
Conditionally returned

Postal code provided by the cardholder.

Allowable Values:

9 char max

gpa_order_unload.jit_funding.address_verification.issuer

object
Conditionally returned

Contains the address verification data held by the Marqeta platform and its assertion as to whether its address verification data matches that provided by the cardholder.

Allowable Values:

gpa_order_unload.jit_funding.address_verification.issuer.on_file

object
Conditionally returned

Contains address verification data held by the Marqeta platform.

Allowable Values:

An existing gpa_order_unload.jit_funding.address_verification.issuer.on_file object.

gpa_order_unload.jit_funding.address_verification.issuer.on_file.street_address

string
Conditionally returned

Street address provided by the Marqeta platform.

This field is a concatenation of the address1 and address2 fields associated with the cardholder.

Allowable Values:

40 char max

gpa_order_unload.jit_funding.address_verification.issuer.on_file.zip

string
Conditionally returned

Zip code provided by the Marqeta platform.

Allowable Values:

gpa_order_unload.jit_funding.address_verification.issuer.on_file.postal_code

string
Conditionally returned

Postal code provided by the Marqeta platform.

Allowable Values:

gpa_order_unload.jit_funding.address_verification.issuer.response

object
Conditionally returned

Contains the Marqeta platform’s assertion as to whether its address verification data matches that provided by the cardholder.

Allowable Values:

Existing gpa_order_unload.jit_funding.address_verification.issuer.response object.

gpa_order_unload.jit_funding.address_verification.issuer.response.code

string
Returned

Assertion by the Marqeta platform as to whether its address verification data matches that provided by the cardholder. The assertion is presented as a four-digit code.

Allowable Values:

One of the following assertion codes:

Code Address Postal Code

0000

Match

Match

0001

Match

Unmatched

0100

Unmatched

Match

0101

Unmatched

Unmatched

0200

Data Not Present

Match

0201

Data Not Present

Unmatched

0002

Match

Data Not Present

0102

Unmatched

Data Not Present

0303

Not Validated

Not Validated

gpa_order_unload.jit_funding.address_verification.issuer.response.memo

string
Returned

Additional information on the address verification.

Returned for authorization and authorization completion transactions.

Allowable Values:

99 char max

gpa_order_unload.jit_funding.address_verification.gateway

object
Conditionally returned

Contains gateway-held address verification data and the gateway’s assertion as to whether its data matches the data provided by the cardholder.

Returned when overriding the assertion provided in the JIT Funding request.

Allowable Values:

Existing gpa_order_unload.jit_funding.address_verification.gateway.on_file object.

gpa_order_unload.jit_funding.address_verification.gateway.on_file

object
Conditionally returned

Contains address verification data held by the gateway.

Allowable Values:

Existing gpa_order_unload.jit_funding.address_verification.gateway.on_file object.

gpa_order_unload.jit_funding.address_verification.gateway.on_file.street_address

string
Conditionally returned

Street address provided by the gateway.

Allowable Values:

40 char max

gpa_order_unload.jit_funding.address_verification.gateway.on_file.zip

string
Conditionally returned

Zip code provided by the gateway.

Allowable Values:

gpa_order_unload.jit_funding.address_verification.gateway.on_file.postal_code

string
Conditionally returned

Postal code provided by the gateway.

Allowable Values:

gpa_order_unload.jit_funding.address_verification.gateway.response

object
Conditionally returned

Contains the gateway’s assertion as to whether its address verification data matches the cardholder’s.

Allowable Values:

Existing gpa_order_unload.jit_funding.address_verification.gateway.response object.

gpa_order_unload.jit_funding.address_verification.gateway.response.code

string
Returned

Gateway’s assertion as to whether the address verification data provided by the gateway and cardholder match. The assertion is presented as a four-digit code.

Allowable Values:

One of the following assertion codes:

Code Address Postal Code

0000

Match

Match

0001

Match

Unmatched

0100

Unmatched

Match

0101

Unmatched

Unmatched

0200

Data Not Present

Match

0201

Data Not Present

Unmatched

0002

Match

Data Not Present

0102

Unmatched

Data Not Present

0303

Not Validated

Not Validated

gpa_order_unload.jit_funding.address_verification.gateway.response.memo

string
Returned

Additional information on the address verification.

Returned for authorization and authorization completion transactions.

Allowable Values:

99 char max

gpa_order_unload.jit_funding.balances

object
Conditionally returned

Contains the GPA’s balance details.

Allowable Values:

Existing gpa_order.jit_funding.balances object.

gpa_order_unload.jit_funding.balances.currency_code

string
Returned

Currency of the funds used in the transaction.

Allowable Values:

A valid three-digit ISO 4217 currency type. For example, USD.

gpa_order_unload.jit_funding.balances.ledger_balance

decimal
Returned

Authorized funds that are currently on hold but not yet cleared.

Allowable Values:

Format: 0.00

gpa_order_unload.jit_funding.balances.available_balance

decimal
Returned

Ledger balance minus any authorized transactions that have not yet cleared. Also known as the card holder’s purchasing power. When using JIT Funding, this balance is usually equal to $0.00.

Allowable Values:

gpa_order_unload.jit_funding.balances.pending_credits

decimal
Returned

ACH loads that have been accepted, but for which the funding time has not yet elapsed.

Allowable Values:

gpa_order_unload.jit_funding.balances.impacted_amount

decimal
Conditionally returned

Balance change based on the amount of the transaction.

Allowable Values:

program_transfer

object
Conditionally returned

Contains information about a program transfer, which moves funds from an account holder’s GPA to a program funding source.

Allowable Values:

program_transfer.fees

array
Conditionally returned

List of fees to add to the program transfer and debit from the account holder’s GPA.

Allowable Values:

Valid fees.

program_transfer.token

string
Conditionally returned

Unique identifier of the program transfer.

Allowable Values:

36 char max

program_transfer.user_token

string
Conditionally returned

Required if business_token is null.

Allowable Values:

36 char max

program_transfer.business_token

string
Conditionally returned

Required if user_token is null.

Allowable Values:

36 char max

program_transfer.amount

Returned
decimal

Amount to be transferred.

Allowable Values:

Format: 0.00

program_transfer.type_token

Returned
string

Unique identifier of the program transfer type.

Allowable Values:

Existing program transfer type token.

program_transfer.tags

string
Conditionally returned

Customer-defined tags for the program transfer.

Allowable Values:

255 char max

program_transfer.memo

string
Conditionally returned

Additional description of the program transfer.

Allowable Values:

99 char max

program_transfer.currency_code

Returned
string

Currency code of the funds to be transferred.

Allowable Values:

A valid three-digit ISO 4217 currency type.

fee_transfer

object
Conditionally returned

Contains information about a fee transfer, including the amount, currency code, and user or business token. See Transfers for more information.

Allowable Values:

Existing fee transfer object.

fee_transfer.tags

string
Conditionally returned

Customer-defined tags for the fee transfer.

Allowable Values:

255 char max

fee_transfer.fees

array of objects
Returned

Contains attributes that define characteristics of one or more fees.

Allowable Values:

An array of existing fee_model objects.

fee_transfer.token

string
Returned

Unique identifier of the fee transfer.

Allowable Values:

36 char max

fee_transfer.user_token

OR

fee_transfer.business_token

string
Returned

Either user_token or business_token are returned, but not both.

Unique identifier of the account holder to which the fee applies.

Allowable Values:

Existing user or business token.

fee_transfer.created_time

datetime
Returned

Date and time when the fee transfer was created.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

peer_transfer

object
Conditionally returned

Contains information about a peer transfer, including sender and recipient tokens, transfer amount and currency code. See Transfers for more information.

Allowable Values:

Existing peer_transfer object.

peer_transfer.token

string
Returned

Unique identifier of the peer transfer request.

Allowable Values:

36 char max

peer_transfer.amount

decimal
Returned

Amount of the peer transfer.

Allowable Values:

Format: 0.00

peer_transfer.tags

string
Conditionally returned

Customer-defined tags for the peer transfer.

Allowable Values:

255 char max

peer_transfer.memo

string
Conditionally returned

Additional comments about the peer transfer.

Allowable Values:

99 char max

peer_transfer.currency_code

string
Returned

The three-digit ISO 4217 currency type.

Allowable Values:

USD

peer_transfer.sender_user_code

OR

peer_transfer.sender_business_code

string
Conditionally returned

Unique identifier of the account holder that sends funds.

Allowable Values:

Existing user or business token.

peer_transfer.recipient_user_code

OR

peer_transfer.recipient_business_code

string
Conditionally returned

Unique identifier of the account holder that receives funds.

Allowable Values:

Existing user or business token.

peer_transfer.created_time

datetime
Returned

Date and time when the peer transfer was created.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

auto_reload

object
Conditionally returned

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

Returned if an auto reload was executed.

Allowable Values:

auto_reload.token

string
Conditionally returned

Unique identifier of the auto reload.

Allowable Values:

36 char max

auto_reload.active

boolean
Conditionally returned

Whether the auto reload is active.

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

Allowable Values:

true, false

Default value:
true

auto_reload.funding_source_token

string
Conditionally returned

Unique identifier of the associated funding source used for the auto reload.

Returned when order_scope contains the gpa object.

Allowable Values:

Existing funding source token.

36 char max

auto_reload.funding_source_address_token

string
Conditionally returned

Unique identifier of the associated funding source address used for the auto reload.

Returned when the funding source is a payment card.

Allowable Values:

Existing funding source address token.

36 char max

auto_reload.association

object
Conditionally returned

Contains the scope of the auto reload: card product, user, or business.

If no value is supplied, the auto reload applies at the program level.

Allowable Values:

card_product_token, user_token, or business_token

auto_reload.association.card_product_token

string
Conditionally returned

Unique identifier of the associated card product.

Allowable Values:

Existing card product token.

36 char max

auto_reload.association.user_token

string
Conditionally returned

Unique identifier of the associated user.

Allowable Values:

Existing user token.

36 char max

auto_reload.association.business_token

string
Conditionally returned

Unique identifier of the associated business.

Allowable Values:

Existing business token.

36 char max

auto_reload.order_scope

object
Returned

Specifies the type of order.

Allowable Values:

gpa object

auto_reload.order_scope.gpa

object
Conditionally returned

Contains information about the GPA order. See Orders for more information.

Allowable Values:

auto_reload.order_scope.gpa.trigger_amount

Returned
Conditionally returned

Threshold that determines when the reload happens.

The reload is triggered when the balance drops below this amount.

Allowable Values:

Must be at least $0.01.

auto_reload.order_scope.gpa.reload_amount

Returned
Conditionally returned

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.

Allowable Values:

Must be at least $0.01.

auto_reload.currency_code

string
Returned

Currency of the funds used in the auto-reload.

Allowable Values:

A valid three-digit ISO 4217 currency code

direct_deposit

object
Conditionally returned

Contains information about a direct deposit. See Direct Deposits for more information.

Allowable Values:

direct_deposit.token

string
Returned

Existing direct deposit record token.

Allowable Values:

direct_deposit.amount

decimal
Returned

Amount being debited or credited.

Allowable Values:

direct_deposit.type

string
Returned

Determines whether funds are being debited from or credited to the account.

Allowable Values:

DEBIT, CREDIT

direct_deposit.state

string
Returned

Current status of the direct deposit record.

Allowable Values:

PENDING, APPLIED, REVERSED, REJECTED

direct_deposit.settlement_date

string
Returned

Date when the credit or debit is applied.

Allowable Values:

Format yyyy-mm-ddThh:mm:ssZ

direct_deposit.state_reason

string
Returned

Explanation for why the direct deposit record is in the current state.

Allowable Values:

255 char max

direct_deposit.state_reason_code

string
Returned

Standard code describing the reason for the current state.

Allowable Values:

See The reason_code field in the Direct Deposit API reference.

direct_deposit.user_token

OR

direct_deposit.business_token

string
Returned

Unique identifier of the user or business associated with the direct deposit record.

Allowable Values:

Existing user or business token.

direct_deposit.created_time

datetime
Returned

Date and time when the direct deposit account was created.

Allowable Values:

direct_deposit.last_modified_time

datetime
Returned

Date and time when the direct deposit account was last modified.

Allowable Values:

direct_deposit.standard_entry_class_code

string
Returned

Three-letter code identifying the type of entry.

Allowable Values:

ACK, ADV, ARC, ATX, BOC, CCD, CIE, COR, CTX, DNE, ENR, IAT, MTE, POP, POS, PPD, RCK, SHR, TEL, TRC, TRX, WEB, XCK

direct_deposit.company_name

string
Returned

Name of the direct deposit originator.

Allowable Values:

16 char max

direct_deposit.company_discretionary_data

string
Returned

Company-specific data provided by the direct deposit originator.

Allowable Values:

20 char max

direct_deposit.company_identification

string
Returned

Alphanumeric code that identifies the direct deposit originator.

Allowable Values:

10 char max

direct_deposit.company_entry_description

string
Returned

Company-specific data provided by the direct deposit originator.

Allowable Values:

20 char max

direct_deposit.individual_identification_number

string
Returned

Accounting number by which the recipient is known to the direct deposit originator.

Allowable Values:

direct_deposit.individual_name

string
Returned

Name of the direct deposit recipient.

Allowable Values:

22 char max

polarity

string
Conditionally returned

Indicates whether the transaction is credit or debit.

Allowable Values:

CREDIT, DEBIT, PENDING_CREDIT, PENDING_DEBIT

real_time_fee_group

object
Conditionally returned

Contains information about a real-time fee group.

Allowable Values:

real_time_fee_group.token

string
Conditionally returned

Unique identifier of the real-time fee group.

Allowable Values:

36 char max

real_time_fee_group.created_time

datetime
Conditionally returned

Date and time when the real-time fee group was created.

Allowable Values:

real_time_fee_group.last_modified_time

datetime
Conditionally returned

Date and time when the real-time fee group was last modified.

Allowable Values:

real_time_fee_group.active

boolean
Conditionally returned

Whether the real-time fee group is active.

Allowable Values:

true, false

Default value:
true

real_time_fee_group.name

string
Conditionally returned

Name of the real-time fee group.

Allowable Values:

50 char max

real_time_fee_group.fee_tokens

array of strings
Conditionally returned

List of fees in the real-time fee group.

Allowable Values:

Existing fee tokens.

fee

object
Conditionally returned

Contains information about fees related to the transaction.

Allowable Values:

fee.token

string
Returned

Unique identifier of the fee.

Allowable Values:

36 char max

fee.active

boolean
Returned

Indicates whether the fee is active.

Allowable Values:

true, false

Default value:
false

fee.name

string
Returned

Name of the fee.

Allowable Values:

50 char max

fee.amount

decimal
Returned

Amount of the fee.

Allowable Values:

fee.tags

string
Conditionally returned

Descriptive metadata about the fee.

Allowable Values:

255 char max

fee.created_time

datetime
Returned

Date and time when the fee was created.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

fee.last_modified_time

datetime
Returned

Date and time when the fee was last modified.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

fee.currency_code

string
Returned

The three-digit ISO 4217 currency type.

Allowable Values:

USD

fee.real_time_assessment

object
Conditionally returned

Contains information about the assessment of real-time fees.

Allowable Values:

fee.real_time_assessment.transaction_type

string
Conditionally returned

Indicates the type of transactions on which the fee is assessed.

Allowable Values:

authorization, pindebit.atm.withdrawal, pindebit

fee.real_time_assessment.international_enabled

boolean
Conditionally returned

Enables fee assessments where the origin of the transaction acquirer is outside the US.

Allowable Values:

true, false

Default value:
false

fee.real_time_assessment.domestic_enabled

boolean
Conditionally returned

Enables fee assessments where the origin of the transaction acquirer is inside the US.

Allowable Values:

true, false

Default value:
false

chargeback

object
Conditionally returned

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

Allowable Values:

chargeback.token

string
Returned

Unique identifier of the chargeback.

Allowable Values:

Valid chargeback token.

chargeback.transaction_token

string
Returned

Unique identifier of the transaction being charged back.

Allowable Values:

Valid transaction token.

36 char max

chargeback.amount

decimal
Returned

Amount of the chargeback.

Allowable Values:

Format: 0.00

chargeback.reason_code

string
Conditionally returned

Identifies the standardized reason for the chargeback.

Allowable Values:

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

chargeback.memo

string
Conditionally returned

Additional comments about the chargeback.

Allowable Values:

1024 char max

chargeback.state

string
Returned

State of the case.

Allowable Values:

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

chargeback.channel

string
Returned

Channel the chargeback came through.

Allowable Values:

GATEWAY, GATEWAY_AUTOMATED, ISSUER, ISSUER_AUTOMATED

chargeback.network

string
Returned

Network handling the chargeback.

Allowable Values:

MARQETA, DISCOVER, MASTERCARD, PULSE, VISA

chargeback.network_case_id

string
Returned

Network-assigned identifier of the chargeback.

Allowable Values:

MARQETA, DISCOVER, MASTERCARD, PULSE, VISA

chargeback.credit_user

boolean
Returned

Whether to credit the user for the chargeback amount.

Allowable Values:

true, false

Default value:
false

chargeback.created_time

datetime
Conditionally returned

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

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

chargeback.last_modified_time

datetime
Conditionally returned

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

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

network

string
Conditionally returned

Indicates which card network was used to complete the transaction (DISCOVER, MASTERCARD, PULSE, VISA, or MARQETA).

Allowable Values:

subnetwork

string
Conditionally returned

Indicates which subnetwork was used to complete the transaction. Possible values include the following:

  • VISANET – Used for VisaNet signature-based transactions.

  • VISANETDEBIT – Used for VisaNet Debit PIN-based transaction.

  • VISAINTERLINK – Used for Visa Interlink PIN-based transactions.

  • VISAPLUS – Used for ATM withdrawals on Visa.

  • MAESTRO – Used for PIN-based transactions on Mastercard.

  • CIRRUS – Used for ATM withdrawals on Mastercard.

  • MASTERCARDDEBIT – Used for signature-based transactions on Mastercard.

  • GATEWAY_JIT – Used for Gateway JIT Funding transactions.

  • MANAGED_JIT – Used for Managed JIT Funding transactions or for transactions that occur while Commando Mode is enabled.

Allowable Values:

acquirer_fee_amount

decimal
Conditionally returned

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

Allowable Values:

fees

array of objects
Conditionally returned

Information about one or more fees.

Allowable Values:

Array of existing fees objects.

fees.type

string
Conditionally returned

Type of fee.

Allowable Values:

ISSUER_FEE, SWITCH_FEE, PINDEBIT_ASSOC_FEE, ACQUIRER_FEE, INTERCHANGE_FEE, CUR_CONV_CARDHOLDER_FEE, CUR_CONV_ISSUER_FEE, CROSS_BORDER_ISSUER_FEE

fees.amount

decimal
Conditionally returned

Amount of the fee.

Allowable Values:

Format: 0.00

fees.credit_debit

string
Conditionally returned

Indicates whether the fee credits (C) or debits (D) the account.

Allowable Values:

C, D

digital_wallet_token

object
Conditionally returned

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.

Allowable Values:

digital_wallet_token.token

string
Conditionally returned

Unique identifier of the digital wallet token.

Allowable Values:

Existing digital wallet token.

36 char max

digital_wallet_token.card_token

string
Conditionally returned

Unique identifier of the card.

Allowable Values:

Existing card token.

36 char max

digital_wallet_token.state

string
Conditionally returned

State of the digital wallet token.

For state descriptions, see Transitioning Token States.

Allowable Values:

REQUESTED, REQUEST_DECLINED, ACTIVE, SUSPENDED, TERMINATED

digital_wallet_token.state_reason

string
Conditionally returned

Reason the digital wallet token transitioned to its current state.

Allowable Values:

255 char max

digital_wallet_token.fulfillment_status

string
Conditionally returned

Digital wallet token’s provisioning status.

For fulfillment status descriptions, see Create Digital Wallet Token Transition.

Allowable Values:

DECISION_RED, DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED

digital_wallet_token.issuer_eligibility_decision

string
Conditionally returned

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

  • 0000 – The token should be provisioned.

  • token.activation.verification.required – Provisioning is pending; further action is required for completion.

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.

Allowable Values:

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

digital_wallet_token.created_time

datetime
Conditionally returned

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

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ

digital_wallet_token.last_modified_time

datetime
Conditionally returned

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

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ

digital_wallet_token.token_service_provider

object
Conditionally returned

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

Allowable Values:

Existing token_service_provider object.

digital_wallet_token.token_service_provider.token_reference_id

object
Conditionally returned

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

Allowable Values:

Existing Token Reference ID.

50 char max

digital_wallet_token. token_service_provider. pan_reference_id

string
Returned

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

Allowable Values:

Existing PAN Reference ID.

50 char max

digital_wallet_token.token_service_provider.token_requestor_id

string
Conditionally returned

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

Mastercard

  • 50110030273 – APPLE_PAY

  • 50120834693 – ANDROID_PAY

  • 50139059239 – SAMSUNG_PAY

Visa

  • 40010030273 – APPLE_PAY

  • 40010075001 – ANDROID_PAY

  • 40010043095 – SAMSUNG_PAY

  • 40010075196 – MICROSOFT_PAY

  • 40010075338 – VISA_CHECKOUT

  • 40010075449 – FACEBOOK

  • 40010075839 – NETFLIX

  • 40010077056 – FITBIT_PAY

  • 40010069887 – GARMIN_PAY

Allowable Values:

  • Mastercard – 50110030273, 50120834693, 50139059239

  • Visa – 40010030273, 40010075001, 40010043095, 40010075196, 40010075338, 40010075449, 40010075839, 40010077056, 40010069887

digital_wallet_token.token_service_provider.token_requestor_name

string
Conditionally returned

Name of the token requestor within the card network.

Allowable Values:

  • MastercardAPPLE_PAY, ANDROID_PAY, SAMSUNG_PAY

  • VisaAPPLE_PAY, ANDROID_PAY, SAMSUNG_PAY, MICROSOFT_PAY, VISA_CHECKOUT, FACEBOOK, NETFLIX, FITBIT_PAY, GARMIN_PAY

digital_wallet_token.token_service_provider.token_type

string
Conditionally returned

Type of the digital wallet token.

Allowable Values:

MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET

digital_wallet_token.token_service_provider.token_pan

string
Conditionally returned

Digital wallet token primary account number (PAN).

Allowable Values:

16 char max

digital_wallet_token.token_service_provider.token_expiration

string
Conditionally returned

Expiration date of the digital wallet token.

Allowable Values:

Format: yyyy-MM-dd HH:mm:ss

digital_wallet_token.token_service_provider.token_score

string
Conditionally returned

Token score assigned by the digital wallet.

Allowable Values:

25 char max

digital_wallet_token.token_service_provider.token_assurance_level

string
Conditionally returned

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

Allowable Values:

0-99

digital_wallet_token.token_service_provider.token_eligibility_decision

string
Conditionally returned

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

Allowable Values:

DECISION_RED, DECISION_YELLOW, DECISION_GREEN

digital_wallet_token.device

object
Conditionally returned

Contains information related to the device being provisioned.

Allowable Values:

Existing device object.

digital_wallet_token.device.token

string
Conditionally returned

Unique identifier of the device object.

Allowable Values:

36 char max

digital_wallet_token.device.type

string
Conditionally returned

Type of device being provisioned.

Allowable Values:

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

digital_wallet_token.device.language_code

string
Conditionally returned

Language the device is configured to use.

Allowable Values:

50 char max

digital_wallet_token.device.device_id

string
Conditionally returned

Identity number of the device.

Allowable Values:

20 char max

digital_wallet_token.device.phone_number

string
Conditionally returned

Device’s telephone number.

Allowable Values:

50 char max

digital_wallet_token.device.name

string
Conditionally returned

Name of the device.

Allowable Values:

50 char max

digital_wallet_token.device.location

string
Conditionally returned

Geographic coordinates of the device.

Allowable Values:

DDD.DD/DDD.DD

latitude/longitude

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

digital_wallet_token.device.ip_address

string
Conditionally returned

Device’s IP address.

Allowable Values:

IP address format.

50 char max

digital_wallet_token.wallet_provider_profile

object
Conditionally returned

Contains information held and provided by the digital wallet provider.

Allowable Values:

Existing wallet_provider_profile object.

digital_wallet_token.wallet_provider_profile.account

object
Conditionally returned

Contains information related to the cardholder and provided by the digital wallet provider.

Allowable Values:

Existing account object.

digital_wallet_token.wallet_provider_profile.account.id

string
Conditionally returned

Wallet provider’s identity number for the cardholder.

Allowable Values:

20 char max

digital_wallet_token.wallet_provider_profile.account.email_address

string
Conditionally returned

Wallet provider’s email address for the cardholder.

Allowable Values:

digital_wallet_token.wallet_provider_profile.account.score

string
Conditionally returned

Score from the digital wallet provider.

Allowable Values:

50 char max

digital_wallet_token.wallet_provider_profile.risk_assessment

object
Conditionally returned

Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token.

Allowable Values:

Existing risk_assessment object.

digital_wallet_token.wallet_provider_profile.risk_assessment.score

string
Conditionally returned

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

Allowable Values:

DECISION_RED, DECISION_YELLOW, DECISION_GREEN

digital_wallet_token.wallet_provider_profile.risk_assessment.version

string
Conditionally returned

Wallet provider’s risk assessment version.

Allowable Values:

digital_wallet_token.wallet_provider_profile.device_score

string
Conditionally returned

Score from the device.

Allowable Values:

50 char max

digital_wallet_token.wallet_provider_profile.pan_source

string
Conditionally returned

Source from which the digital wallet provider obtained the card PAN.

Allowable Values:

KEY_ENTERED, ON_FILE, MOBILE_BANKING_APP

digital_wallet_token.wallet_provider_profile.reason_code

string
Conditionally returned

Reason for the wallet provider’s provisioning decision.

  • 01 – Cardholder’s wallet account is too new relative to launch.

  • 02 – Cardholder’s wallet account is too new relative to provisioning request.

  • 03 – Cardholder’s wallet account/card pair is newer than date threshold.

  • 04 – Changes made to account data within the account threshold.

  • 05 – Suspicious transactions linked to this account.

  • 06 – Account has not had activity in the last year.

  • 07 – Suspended cards in the secure element.

  • 08 – Device was put in lost mode in the last seven days for longer than the duration threshold.

  • 09 – The number of provisioning attempts on this device in 24 hours exceeds threshold.

  • 0A – There have been more than the threshold number of different cards attempted at provisioning to this phone in 24 hours.

  • 0B – The card provisioning attempt contains a distinct name in excess of the threshold.

  • 0C – The device score is less than 3.

  • 0D – The account score is less than 4.

  • 0E – Device provisioning location outside of the cardholder’s wallet account home country.

  • 0G – Suspect fraud.

Allowable Values:

01, 02, 03, 04, 05, 06, 07, 08, 09, 0A, 0B, 0C, 0D, 0E, 0G

digital_wallet_token.wallet_provider_profile.recommendation_reasons

array of strings
Conditionally returned

Reasons for the wallet provider’s recommendation.

Allowable Values:

digital_wallet_token.address_verification

object
Conditionally returned

Contains information held by the card network and used for address verification of the cardholder.

Allowable Values:

Existing address_verification object.

digital_wallet_token.address_verification.request

object
Conditionally returned

Contains information held by the card network and used for address verification of the cardholder. This object is provided when address information was included as part of the tokenization request.

Allowable Values:

digital_wallet_token.address_verification.request.street_address

string
Conditionally returned

The street address of the cardholder. This value is returned as provided by the digital wallet provider.

Allowable Values:

50 char max

digital_wallet_token.address_verification.request.postal_code

string
Conditionally returned

The postal code of the cardholder. This value is returned as provided by the digital wallet provider.

Allowable Values:

50 char max

digital_wallet_token.address_verification.request.zip

string
Conditionally returned

The zip code of the cardholder. This value is returned as provided by the digital wallet provider.

Allowable Values:

digital_wallet_token.user

object
Conditionally returned

Contains information on the digital wallet user.

Allowable Values:

digital_wallet_token.user.authentication

object
Conditionally returned

Contains information on the digital wallet user’s password and email.

Allowable Values:

A valid digital_wallet_token.user.authentication object.

digital_wallet_token.user.authentication.last_password_update_channel

string
Conditionally returned

How the user last updated their password, by a change or reset due to a lost password.

Allowable Values:

USER_CHANGE, USER_RESET

digital_wallet_token.user.authentication.last_password_update_time

datetime
Conditionally returned

Date and time when the user last updated their password.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

digital_wallet_token.user.authentication.email_verified

boolean
Conditionally returned

Whether the user email has been verified.

Allowable Values:

true, false

Default value:
false

digital_wallet_token.user.authentication.email_verified_time

datetime
Conditionally returned

Date and time when the user email was verified.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

digital_wallet_token.user.token

string
Conditionally returned

Unique identifier of the user.

Allowable Values:

36 char max

digital_wallet_token.user.active

boolean
Conditionally returned

Whether the user’s status is active.

Allowable Values:

true, false

Default value:
false

digital_wallet_token.user.honorific

string
Conditionally returned

User’s title/prefix: Ms., Mr., Miss, Mrs.

Allowable Values:

10 char max

digital_wallet_token.user.gender

string
Conditionally returned

Gender of the user.

Allowable Values:

F, M

digital_wallet_token.user.first_name

string
Conditionally returned

First name of the user.

Allowable Values:

40 char max

digital_wallet_token.user.middle_name

string
Conditionally returned

Middle name of the user.

Allowable Values:

40 char max

digital_wallet_token.user.last_name

string
Conditionally returned

Last name of the user.

Allowable Values:

40 char max

digital_wallet_token.user.email

string
Conditionally returned

Valid email address for the user.

Allowable Values:

255 char max

digital_wallet_token.user.address1

string
Conditionally returned

Address of the user.

Allowable Values:

255 char max

digital_wallet_token.user.address2

string
Conditionally returned

Additional address information for the user.

Allowable Values:

255 char max

digital_wallet_token.user.city

string
Conditionally returned

City that corresponds to the user’s address.

Allowable Values:

40 char max

digital_wallet_token.user.state

string
Conditionally returned

State that corresponds to the user’s address.

Allowable Values:

2 char max

digital_wallet_token.user.zip

string
Conditionally returned

Zip code that corresponds to the user’s address.

Allowable Values:

10 char max

digital_wallet_token.user.postal_code

string
Conditionally returned

Postal code that corresponds to the user’s address.

Allowable Values:

10 char max

digital_wallet_token.user.country

string
Conditionally returned

Country where the user resides.

Allowable Values:

40 char max

digital_wallet_token.user.notes

string
Conditionally returned

Any additional information pertaining to the user.

Allowable Values:

255 char max

digital_wallet_token.user.phone

string
Conditionally returned

Telephone number of the user (including area code), prepended by the + symbol and the 1- to 3-digit country calling code. Do not include hyphens, spaces, or parentheses.

Allowable Values:

Format: +15105551212 or +35552260859

digital_wallet_token.user.parent_token

string
Conditionally returned

Unique identifier of a user or business already in the system.

Required if uses_parent_account = true. This user or business is configured as the parent of the current user.

Allowable Values:

Existing user or business token.

digital_wallet_token.user.uses_parent_account

boolean
Conditionally returned

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

If set to true, must also include a parent_token in the request. This value cannot be updated.

Allowable Values:

true, false

Default value:
false

digital_wallet_token.user.ssn

string
Conditionally returned

Full social security number of the user.

Allowable Values:

A valid SSN.

digital_wallet_token.user.passport_number

string
Conditionally returned

Passport number of the user.

Allowable Values:

digital_wallet_token.user.id_card_number

string
Conditionally returned

ID card number of the user.

Allowable Values:

digital_wallet_token.user.nationality

string
Conditionally returned

Nationality of the user.

Allowable Values:

digital_wallet_token.user.company

string
Conditionally returned

Company name of the user.

Allowable Values:

digital_wallet_token.user.ip_address

string
Conditionally returned

IP address of the user.

Allowable Values:

digital_wallet_token.user.password

string
Conditionally returned

Password for user account.

Allowable Values:

  • 8-20 characters

  • Must contain at least one numeral

  • Must contain at least one lowercase letter

  • Must contain at least one uppercase letter

  • Must contain at least one of these symbols: @ # $ % ! ^ & * ( ) \ _ + ~ ` - = [ ] { } , ; : ' " , . / < > ?

digital_wallet_token.user.created_time

datetime
Returned

Date and time when the user account was created.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

digital_wallet_token.user.last_modified_time

datetime
Returned

Date and time when the user account was last modified.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

digital_wallet_token.user.business_token

string
Conditionally returned

Unique identifier of the business user.

Returned if the user is a business.

Allowable Values:

digital_wallet_token.user.metadata

object
Conditionally returned

Contains metadata associated with the user.

Allowable Values:

Customer-defined strings as key/value pairs.

digital_wallet_token.user.account_holder_group_token

string
Conditionally returned

Associates the specified account holder group with the user.

Allowable Values:

Existing account holder group token.

36 char max

digital_wallet_token.user.status

string
Conditionally returned

Status of the user account.

Allowable Values:

UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED

digital_wallet_token.user.identifications

array
Conditionally returned

List of one or more objects containing identifying information about the user.

Allowable Values:

Existing users.identifications array.

digital_wallet_token.user.identifications.type

string
Conditionally returned

Form of identification.

Allowable Values:

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

digital_wallet_token.user.identifications.value

integer
Conditionally returned

Identification number associated with the form of identification.

Allowable Values:

digital_wallet_token.user.identifications.expiration_date

string
Conditionally returned

Expiration date for the form of identification, if applicable.

Allowable Values:

Format: yyyy-MM-dd, yyyy-MM-dd’T’HH:mm:ss.SSSZ, yyyy-MM-dd’T’HH:mm:ss.SSS’Z', EEE dd MMM yyyy HH:mm:ss zzz'

Default value:
false

digital_wallet_token.user.birth_date

string
Conditionally returned

Date of birth of the user.

Allowable Values:

Format: yyyy-MM-dd, yyyy-MM-dd’T’HH:mm:ss.SSSZ, yyyy-MM-dd’T’HH:mm:ss.SSS’Z', EEE dd MMM yyyy HH:mm:ss zzz'

digital_wallet_token.user.passport_expiration_date

string
Conditionally returned

Expiration date for the user’s passport.

Allowable Values:

Format: yyyy-MM-dd, yyyy-MM-dd’T’HH:mm:ss.SSSZ, yyyy-MM-dd’T’HH:mm:ss.SSS’Z', EEE dd MMM yyyy HH:mm:ss zzz'

digital_wallet_token.user.id_card_expiration_date

string
Conditionally returned

Expiration date for the user’s ID card.

Allowable Values:

Format: yyyy-MM-dd, yyyy-MM-dd’T’HH:mm:ss.SSSZ, yyyy-MM-dd’T’HH:mm:ss.SSS’Z', EEE dd MMM yyyy HH:mm:ss zzz'

network_fees

object
Conditionally returned

Contains card network fees assessed against the cardholder.

Allowable Values:

Existing network_fees object.

network_fees.type

string
Optional

Specifies the type of fee.

  • ISSUER_FEE – Fee charged by the issuing bank. Does not impact account balance.

  • SWITCH_FEE – Fee charged per transaction by the card network. Does not impact account balance.

  • PINDEBIT_ASSOC_FEE – Fee associated with a PIN-debit transaction, such as at an ATM. Impacts account balance.

  • ACQUIRER_FEE – Fee charged by the acquiring bank. Impacts account balance.

  • INTERCHANGE_FEE – Fee charged per transaction by the card network. Does not impact account balance.

  • CUR_CONV_CARDHOLDER_FEE – Currency conversion fee charged to the cardholder by the card network. Impacts account balance.

  • CUR_CONV_ISSUER_FEE – Currency conversion fee paid for by the issuer. Does not impact account balance.

  • CROSS_BORDER_ISSUER_FEE – Cross-border fee charged by the network, and paid for by the issuer. Does not impact account balance.

  • CROSS_BORDER_CARDHOLDER_FEE – Cross-border fee charged to the cardholder by the card network. Impacts account balance.

Allowable Values:

ISSUER_FEE, SWITCH_FEE, PINDEBIT_ASSOC_FEE, ACQUIRER_FEE, INTERCHANGE_FEE, CUR_CONV_CARDHOLDER_FEE, CUR_CONV_ISSUER_FEE, CROSS_BORDER_ISSUER_FEE, CROSS_BORDER_CARDHOLDER_FEE

network_fees.amount

decimal
Optional

Specifies the amount of the fee.

Allowable Values:

Format: 0.00

network_fees.credit_debit

string
Optional

Specifies whether the fee credits (C) or debits (D) the account balance.

Allowable Values:

C, D

The default value depends on the setting of the type field, as listed below:

Fee Type Default

ISSUER_FEE

C

SWITCH_FEE

D

PINDEBIT_ASSOC_FEE

D

ACQUIRER_FEE

D

INTERCHANGE_FEE

C

CUR_CONV_CARDHOLDER_FEE

D

CUR_CONV_ISSUER_FEE

C

CROSS_BORDER_ISSUER_FEE

C

CROSS_BORDER_CARDHOLDER_FEE

D

card

object
Conditionally returned

Contains information about a specific card.

Allowable Values:

Existing card object.

card.created_time

datetime
Returned

Date and time when the card was created.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

card.last_modified_time

datetime
Returned

Date and time when the card was last modified.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

card.token

string
Returned

Unique identifier of the card.

Allowable Values:

36 char max

card.user_token

string
Returned

Unique identifier of the cardholder.

Allowable Values:

Existing user token.

36 char max

card.card_product_token

string
Returned

Unique identifier of the card product.

Allowable Values:

Existing card product token.

36 char max

card.last_four

string
Returned

Last four digits of the card PAN.

Allowable Values:

card.pan

string
Returned

Full PAN of the card.

Allowable Values:

Existing card PAN.

card.expiration

string
Returned

Month and year the card expires.

Allowable Values:

Format: MM-YY

card.expiration_time

datetime
Returned

Date and time when the card expires.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

card.cvv_number

string
Conditionally returned

Three-digit card verification value (CVV2) of the chip, included on the back of the card.

Allowable Values:

3 char max

card.chip_cvv_number

string
Conditionally returned

Three-digit card verification value (CVV2) included on the back of the card.

Allowable Values:

card.barcode

string
Conditionally returned

Barcode of the card.

Allowable Values:

card.pin_is_set

boolean
Returned

Whether a PIN was set.

Allowable Values:

true, false

Default value:
false

card.state

string
Returned

State of the card.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED, UNSUPPORTED, UNACTIVATED

card.state_reason

string
Returned

Reason for the state of the card.

Allowable Values:

card.fulfillment_status

string
Returned

Status of the card fulfillment.

Allowable Values:

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

card.reissue_pan_from_card_token

string
Conditionally returned

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

This field reissues a card by copying the PAN and PIN from the specified source card to the newly created card. The reissued card has the same PAN and PIN as the source card but a new expiration date and CVV2 number.

NOTE: By default, the source card is automatically terminated. However, if your program is configured for multiple active cards, you can prevent the source card from being automatically terminated by setting the activation_actions.terminate_reissued_source_card field to false.

Allowable Values:

Existing card token.

card.fulfillment

object
Returned

Contains the physical characteristics of a card and shipment information.

Allowable Values:

card.fulfillment.shipping

object
Conditionally returned

Contains information about the card fulfillment’s shipping address.

Allowable Values:

Existing fulfillment.shipping object.

card.fulfillment.shipping.method

string
Conditionally returned

Shipping company and shipping service level.

Allowable Values:

Perfect Plastic Printing and IDEMIA: USPS_REGULAR, FEDEX_EXPEDITED

Arroweye Solutions: UPS_REGULAR, UPS_EXPEDITED, USPS_REGULAR, USPS_EXPEDITED

card.fulfillment.shipping.return_address

object
Conditionally returned

Address to return the card if it cannot be delivered.

Allowable Values:

card.fulfillment.shipping.return_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

card.fulfillment.shipping.return_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

card.fulfillment.shipping.return_address.address_1

string
Conditionally returned

Street address.

Allowable Values:

225 char max

card.fulfillment.shipping.return_address.address_2

string
Conditionally returned

Additional address information.

Allowable Values:

225 char max

card.fulfillment.shipping.return_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

card.fulfillment.shipping.return_address.state

string
Conditionally returned

State.

Allowable Values:

2 char max

card.fulfillment.shipping.return_address.zip

string
Conditionally returned

Zip code.

Allowable Values:

10 char max

card.fulfillment.shipping.return_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

card.fulfillment.shipping.return_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

card.fulfillment.shipping.return_address.phone

string
Conditionally returned

Phone number.

Allowable Values:

20 char max

card.fulfillment.shipping.recipient_address

object
Conditionally returned

Contains information about the address of the card recipient.

Allowable Values:

card.fulfillment.shipping.recipient_address.first_name

string
Conditionally returned

First name.

Allowable Values:

40 char max

card.fulfillment.shipping.recipient_address.last_name

string
Conditionally returned

Last name.

Allowable Values:

40 char max

card.fulfillment.shipping.recipient_address.address_1

string
Conditionally returned

Street address.

Allowable Values:

225 char max

card.fulfillment.shipping.recipient_address.address_2

string
Conditionally returned

Additional address information.

Allowable Values:

225 char max

card.fulfillment.shipping.recipient_address.city

string
Conditionally returned

City.

Allowable Values:

40 char max

card.fulfillment.shipping.recipient_address.state

string
Conditionally returned

State.

Allowable Values:

2 char max

card.fulfillment.shipping.recipient_address.zip

string
Conditionally returned

Zip code.

Allowable Values:

10 char max

card.fulfillment.shipping.recipient_address.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

card.fulfillment.shipping.recipient_address.country

string
Conditionally returned

Country.

Allowable Values:

40 char max

card.fulfillment.shipping.recipient_address.phone

string
Conditionally returned

Phone number.

Allowable Values:

20 char max

card.fulfillment.shipping.care_of_line

object
Conditionally returned

Person or entity to receive the card on behalf of the recipient.

Allowable Values:

card.fulfillment.card_personalization

object
Returned

Contains information about personalized attributes added to the card.

Allowable Values:

Existing card_personalization object.

card.fulfillment.card_personalization.text

object
Returned

Contains personalized text that appears on the card.

Allowable Values:

Existing fulfillment.card_personalization.text object.

card.fulfillment.card_personalization.text.name_line_1.value

string
Returned

First line of personalized text printed on the face of the card.

Allowable Values:

Valid characters differ according to your fulfillment provider:

  • For Arroweye Solutions, IDEMIA Poland, and IDEMIA Czech Republic, all characters are valid. For specific character and language guidelines, contact your fulfillment provider.

  • For all other providers, valid characters are:

    • A-Z (uppercase letters)

    • a-z (lowercase letters)

    • 0-9 (integers)

    •   (space)

    • . (period)

    • , (comma)

    • / (forward slash)

    • - (hyphen)

    • & (ampersand)

    • ' (single quote)

    • @ (stylized D for Discover cards)

21 char max. Strings longer than 21 characters are truncated.

card.fulfillment.card_personalization.text.name_line_2.value

string
Conditionally returned

Second line of personalized text printed on the face of the card.

Allowable Values:

Valid characters differ according to your fulfillment provider:

  • For Arroweye Solutions, IDEMIA Poland, and IDEMIA Czech Republic, all characters are valid. For specific character and language guidelines, contact your fulfillment provider.

  • For all other providers, valid characters are:

    • A-Z (uppercase letters)

    • a-z (lowercase letters)

    • 0-9 (integers)

    •   (space)

    • . (period)

    • , (comma)

    • / (forward slash)

    • - (hyphen)

    • & (ampersand)

    • ' (single quote)

    • @ (stylized D for Discover cards)

21 char max. Strings longer than 21 characters are truncated.

card.fulfillment.card_personalization.text.name_line_3.value

string
Conditionally returned

Third line of personalized text printed on the face of the card.

Allowable Values:

Valid characters differ according to your fulfillment provider:

  • For Arroweye Solutions, IDEMIA Poland, and IDEMIA Czech Republic, all characters are valid. For specific character and language guidelines, contact your fulfillment provider.

  • For all other providers, valid characters are:

    • A-Z (uppercase letters)

    • a-z (lowercase letters)

    • 0-9 (integers)

    •   (space)

    • . (period)

    • , (comma)

    • / (forward slash)

    • - (hyphen)

    • & (ampersand)

    • ' (single quote)

    • @ (stylized D for Discover cards)

21 char max. Strings longer than 21 characters are truncated.

card.fulfillment.card_personalization.images

object
Conditionally returned

Contains personalized images that appear on the card (for individual card orders only). Also specifies attributes of the card carrier, if your fulfillment provider is Perfect Plastic Printing or IDEMIA.

NOTE: The images object does not store or pass any actual image data. It only specifies image files that you send to your fulfillment provider.

Allowable Values:

Existing fulfillment.card_personalization.images object.

card.fulfillment.card_personalization.images.card

object
Conditionally returned

Specifies personalized images that appear on the card.

Allowable Values:

card.fulfillment.card_personalization.images.card.name

string
Conditionally returned

Specifies a PNG image to display on the card.

Allowable Values:

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

Must end in .png.

card.fulfillment.card_personalization.images.card.thermal_color

string
Conditionally returned

Specifies the color of the image displayed on the card.

Allowable Values:

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

card.fulfillment.card_personalization.images.signature.name

string
Conditionally returned

Specifies a PNG image of the cardholder’s signature.

Allowable Values:

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

Must end in .png.

card.fulfillment.card_personalization.images.carrier_return_window.name

string
Conditionally returned

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

Allowable Values:

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

Must end in .png.

card.fulfillment.card_personalization.carrier

object
Conditionally returned

Contains attributes of the card carrier (if your fulfillment provider is Arroweye Solutions).

Allowable Values:

Existing fulfillment.card_personalization.carrier object.

card.fulfillment.card_personalization.carrier.template_id

string
Conditionally returned

Card carrier template to use.

Allowable Values:

A card carrier template ID.

card.fulfillment.card_personalization.carrier.logo_file

string
Conditionally returned

Image to display on the card carrier.

Allowable Values:

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

card.fulfillment.card_personalization.carrier.logo_thumbnail_file

string
Conditionally returned

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

Allowable Values:

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

card.fulfillment.card_personalization.carrier.message_file

string
Conditionally returned

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

Allowable Values:

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

card.fulfillment.card_personalization.carrier.message_line

string
Conditionally returned

Specifies a custom message that appears on the card carrier.

Allowable Values:

60 char max

card.fulfillment.card_personalization.perso_type

string
Optional

Specifies the method for printing personalized text on the card.

Allowable Values:

EMBOSS, LASER, FLAT

card.fulfillment.card_fulfillment_reason

string
Conditionally returned

Specifies the reason for card fulfillment.

Allowable Values:

NEW, LOST_STOLEN, EXPIRED

card.bulk_issuance_token

string
Conditionally returned

Unique identifier of the bulk issuance.

Allowable Values:

card.translate_pin_from_card_token

string
Conditionally returned

Token of the source card from which to transfer the PIN.

Returned if card is a reissue or replacement that keeps the source card’s PIN.

Allowable Values:

card.activation_actions

object
Conditionally returned

Contains information about performable actions once the card is activated.

Allowable Values:

card.activation_actions.terminate_reissued_source_card

boolean
Conditionally returned

Whether to terminate the source card from which the card was reissued.

Allowable Values:

true, false

Default value:
true

card.activation_actions.swap_digital_wallet_tokens_from_card_token

string
Conditionally returned

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

Not relevant when reissue_pan_from_card_token is set.

Allowable Values:

Existing card token.

36 char max

card.instrument_type

string
Conditionally returned

Type of card.

Allowable Values:

PHYSICAL_MSR, PHYSICAL_ICC, PHYSICAL_CONTACTLESS, PHYSICAL_COMBO, VIRTUAL_PAN

card.expedite

boolean
Conditionally returned

Whether to expedite the card.

Allowable Values:

true, false

Default value:
false

card.metadata

object
Returned

Custom metadata associated with the card used in the transaction.

Allowable Values:

Customer-defined strings as key/value pairs.

user

object
Conditionally returned

Contains customer-defined information about the individual user who funded the transaction.

Allowable Values:

Existing user object.

user.metadata

object
Conditionally returned

Contains metadata associated with the individual user who funded the transaction.

Allowable Values:

Customer-defined strings as key/value pairs.

user.<customer_defined_name_01

Conditionally returned
object

Associates customer-defined metadata with the individual user. You can define the names and values of up to 20 fields, for example:

Copied

Allowable Values:

  • Up to 20 name-value pairs

  • 255 char max per name

  • 255 char max per value.

business

object
Conditionally returned

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

Allowable Values:

business.metadata

object
Conditionally returned

Contains customer-defined metadata to associate with the business that funded the transaction.

Allowable Values:

business.<customer_defined_name_01

Conditionally returned
object

Associates customer-defined metadata with the business. You can define the names and values of up to 20 fields, for example:

Copied

Allowable Values:

  • Up to 20 name-value pairs

  • 255 char max per name

  • 255 char max per value.

acquirer

object
Conditionally returned

Contains information about the merchant’s financial institution.

Allowable Values:

Existing acquirer object.

acquirer.institution_country

string
Conditionally returned

Country of the merchant’s financial institution.

Allowable Values:

Three-digit country code.

acquirer.institution_id_code

string
Conditionally returned

ID code of the merchant’s financial institution.

Allowable Values:

acquirer.retrieval_reference_number

string
Conditionally returned

Retrieval reference number of the merchant’s financial institution.

Allowable Values:

acquirer.system_trace_audit_number

string
Returned

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

Allowable Values:

fraud

object
Conditionally returned

Contains one or more fraud determinations for the transaction and the cardholder’s account. This object can contain fraud determinations calculated by the card network and issuer-processor (Marqeta).

Allowable Values:

fraud.network

object
Conditionally returned

Contains network-provided information about fraud determinations.

Allowable Values:

fraud.network.transaction_risk_score

integer
Conditionally returned

Network-provided risk score for the transaction. A higher score indicates higher risk. Useful for making authorization decisions.

Format: int32

Allowable Values:

Mastercard: 0-999

Visa: 1-99

fraud.network.transaction_risk_score_reason_code

string
Conditionally returned

(Mastercard only) Unique code that describes the main driver of the transaction_risk_score.

Allowable Values:

1-29

fraud.network.transaction_risk_score_reason_description

string
Conditionally returned

(Mastercard only) Description for the transaction_risk_score_reason_code.

Allowable Values:

fraud.network.account_risk_score

string
Conditionally returned

(Visa only) Account holder risk condition code evaluated by the card network. A higher score indicates a greater likelihood that the card number is compromised.

Allowable Values:

1-9

fraud.network.account_risk_score_reason_code


Conditionally returned

(Visa only) Unique code that describes the main driver of the account_risk_score.

Allowable Values:

pos

object
Conditionally returned

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

May be returned if the request uses Transaction Model V2 of the Marqeta Core API. Not returned for V1 requests. See Versioning for details.

Allowable Values:

pos.pan_entry_mode

string
Conditionally returned

Method used for capturing the card PAN during the transaction.

Allowable Values:

MANUAL, MAG_STRIPE, MAG_STRIPE_CONTACTLESS, BAR_CODE, OCR, CARD_ON_FILE, MICR, CHIP, CHIP_CONTACTLESS, CHIP_FALLBACK, OTHER

pos.pin_entry_mode

string
Conditionally returned

Whether the card acceptor/terminal can capture card PINs.

NOTE: This field does not indicate whether a PIN was entered.

Allowable Values:

TRUE, FALSE, DEFECTIVE

pos.terminal_id

string
Conditionally returned

Card acceptor or terminal identification number.

Allowable Values:

pos.terminal_attendance

string
Conditionally returned

Whether the card acceptor/terminal was attended.

Allowable Values:

UNSPECIFIED,