Token Provision Schema - Marqeta Docs

Real-Time Decisioning (RTD) references a JSON object called derived type in an eventType attribute. A derived type object typically corresponds to a bundle of information, such as an address or provisioning data. The following tables describe the derived types used by RTD. Every provisioning processed by RTD is classified as an event. For example, provisioning a card is classified as a TOKEN_PROVISION_RT event. The following sections describe the derived types for the TOKEN_PROVISION_RT event.

Prerequisites

This feature requires additional activation steps. To activate it for your program, contact your Marqeta representative.

TOKEN_PROVISION_RT

The following fields make up the TOKEN_PROVISION_RT schema.

Attribute	Description
tokenmanager_event_type string Required	The specific provisioning step that generated this event. Expected values: `CHECK_ELIGIBILITY`, `TOKEN_ACTIVATION`
created_time string Required	Timestamp of when the event was created, in UTC. Format: yyyy-MM-ddThh:mm:ssZ
program_short_code string Required	The program’s short code identifier. Format: 2-8 chars
network string Required	The card network through which the provisioning request was received. Expected values: `VISA`, `MASTERCARD`
device_data object Optional	Device information provided by the card network. Schema: `device_data` Expected values: See the device_data object.
decisioning_data object Required	The Marqeta platform’s decision about the provisioning request. Schema: `decisioning_data` Expected values: See the decisioning_data object.
token_requestor_data object Required	Information about the entity requesting the token. Schema: `token_requestor_data` Expected values: See the token_requestor_data object.
card_data object Required	Card information associated with the provisioning request. Schema: `card_data` Expected values: See the card_data object.
user_data object Optional	Cardholder information. Schema: `user_data` Expected values: See the user_data object.
token_data object Required	Token identifiers from the card network. Schema: `token_data` Expected values: See the token_data object.
transaction_data object Required	Authorization verification results from the token activation request. Schema: `transaction_data` Expected values: See the transaction_data object.
wallet_provider_data object Required	Information about the wallet provider and how the PAN was supplied. Schema: `wallet_provider_data` Expected values: See the wallet_provider_data object.

device_data

Device information provided by the card network. Available for both CHECK_ELIGIBILITY and TOKEN_ACTIVATION events, though fields may be null depending on what the network supplies.

Attribute	Description
id string Optional	Device identifier provided by the network. Format: 1-50 chars
device_type string Optional	Type of device used in the provisioning request. Expected values: `UNKNOWN`, `MOBILE_PHONE`, `TABLET`, `WATCH`, `MOBILE_PHONE_OR_TABLET`, `PERSONAL_COMPUTER`, `LAPTOP`, `APPLIANCE`, `VEHICLE`, `GAMING_DEVICE`, `HOUSEHOLD_DEVICE`, `WEARABLE_DEVICE`, `AUTOMOBILE_DEVICE`
device_name string Optional	Name of the device. Format: 1-50 chars
device_number string Optional	Device number provided by the network. Format: 1-36 chars
device_location string Optional	Device location coordinates provided by the network. Example: `0/0`
device_ip_address string Optional	IP address of the device. Format: 1-50 chars

decisioning_data

The Marqeta platform’s decision about the provisioning request that was evaluated before RTD is consulted.

Attribute	Description
decision string Required	Whether the Marqeta platform approved or declined the provisioning request. Expected values: `APPROVED`, `DECLINED`
reason_code string Optional	The reason code from the Marqeta platform’s evaluation. For `CHECK_ELIGIBILITY` events, approved requests use `0000` and declined requests use error codes specific to the Marqeta platform. For `TOKEN_ACTIVATION` events, the value comes from the transaction log reason code. Expected values: See Marqeta platform reason codes.

decisioning_data reason codes

The following table lists possible reason codes returned in the reason_code field of the decisioning_data object with their meaning.

Code	Meaning
`0000`	Approved
`card.not.found`	PAN not found in Marqeta system
`card.expiration.mismatch`	Expiry date does not match
`card.terminated`	Card is terminated
`cardholder.not.active`	Cardholder is not active
`cardaccount.verified`	Card account verified (token activation request approved)

token_requestor_data

Information about the entity requesting the token, such as a merchant or digital wallet provider.

Attribute	Description
id string Required	The token requestor ID assigned by the card network. Format: 1-11 chars
name string Optional	Human-readable name of the token requestor, when available. Format: 255 chars max

card_data

Card information associated with the provisioning request. When the Marqeta platform cannot find a matching card (card.not.found), the card_token, card_product_token, card_product_active, and card_state fields will be null. The bin and last_four fields are derived from the PAN provided in the network request and are always present.

Attribute	Description
pan_reference_id string Required	The network’s PAN reference identifier. Format: 1-32 chars
bin string Required	The bank identification number (BIN) — first six digits of the PAN. Always present, even when the card is not found. Format: 6 digits
last_four string Required	Last four digits of the PAN. Always present, even when the card is not found. Format: 4 digits
card_token string Optional	The Marqeta card token. Null when the card is not found. Format: 1-36 chars
card_product_token string Optional	The Marqeta card product token. Null when the card is not found. Format: 1-36 chars
card_product_active string Optional	Indicates whether the card product is active. Sent as a string `"true"` or `"false"`. Null when the card is not found. Expected values: `true`, `false`
card_state string Optional	The current state of the card. Null when the card is not found. Expected values: `ACTIVE`, `SUSPENDED`, `TERMINATED`, `UNACTIVATED`

user_data

The following table lists cardholder information. Fields are null when the card is not found (card.not.found).

Attribute	Description
user_token string Optional	The Marqeta user token for the cardholder. Null when the card is not found. Format: 1-36 chars

token_data

Token identifiers from the card network.

Attribute	Description
token_reference_id string Required	The network’s token reference identifier. Format: 1-32 chars
correlation_id string Optional	Correlation identifier for the provisioning request. Always null for Visa. Always populated for Mastercard — used to correlate provisioning events across the MDES flow. Format: 1-32 chars

transaction_data

Authorization verification results from the token activation request. For CHECK_ELIGIBILITY events, both fields are null. For TOKEN_ACTIVATION events, the fields reflect Address Verification System (AVS) and Card Verification Value 2 (CVV2) results from the token activation.

Attribute	Description
avs_code string Optional	AVS result code. Only populated for `TOKEN_ACTIVATION` events. Expected values: See AVS codes.
cvv2_code string Optional	CVV2 verification result code. Only populated for `TOKEN_ACTIVATION` events. Expected values: See CVV2 codes.

AVS codes

The following table lists possible AVS codes returned in the avs_code field of the transaction_data object with their meaning.

Code	Meaning
`0000`	Address and ZIP code match
`0001`	Address matches, ZIP code does not
`0100`	Address does not match, ZIP code matches
`0101`	Neither address nor ZIP code match
`0200`	Address not present, ZIP code matches
`0201`	Address not present, ZIP code does not match
`0002`	Address and ZIP code not present
`0102`	Address does not match, ZIP code not present
`null`	AVS verification participant never reached

CVV2 codes

The following is a list of possible CVV2 codes returned in the cvv2_code field of the transaction_data object with their meaning.

Code	Meaning
`0000`	CVV2 match
`N7`	CVV2 mismatch
`null`	CVV2 verification participant never reached

wallet_provider_data

Information about the wallet provider and how the PAN was supplied.

Attribute	Description
pan_source string Required	How the PAN was provided for this provisioning request. Expected values: See PAN source values.
wallet_id string Optional	Wallet identifier provided by the network. May be null, particularly for `CHECK_ELIGIBILITY` events. Format: 1-32 chars

PAN source values

The following table lists possible PAN source values returned in the pan_source field of the wallet_provider_data object with their meaning.

Value	Meaning
`KEY_ENTERED`	Cardholder manually entered card data
`ON_FILE`	Card was already on file in the wallet
`MOBILE_BANKING_APP`	Card was provisioned via a mobile banking application

​Prerequisites

​TOKEN_PROVISION_RT

​device_data

​decisioning_data

​decisioning_data reason codes

​token_requestor_data

​card_data

​user_data

​token_data

​transaction_data

​AVS codes

​CVV2 codes

​wallet_provider_data

​PAN source values