GET//
Use this endpoint if you use Marqeta only for tokenization as a service and are not a Marqeta card issuer.
If Marqeta is your card issuer, use the Digital Wallets Management endpoint instead.
/digitalwallettokens/{token} endpoint to retrieve a specific digital wallet token.
Header parameter
| Fields | Description |
|---|---|
| req-sys-id string Optional | Random pseudo-unique identifier of a request, used for troubleshooting between multiple parties. Usually a globally unique identifier (GUID). Allowable Values: 1–36 chars |
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the digital wallet token. Allowable Values: Existing digital wallet token token |
Response body
| Fields | Description |
|---|---|
| encrypted_data object Conditionally returned | Contains encrypted data about the token service provider, device, or address verification. Allowable Values: address_verification, device, token_service_provider |
| encrypted_data.token_service_provider object Conditionally returned | Contains information held and provided by the token service provider (card network). This object is returned when relevant information is provided by the token service provider. Allowable Values: correlation_id, pan_reference_id, token_assurance_level, token_eligibility_decision, token_pan, token_reference_id, token_requestor_id, token_requestor_name, token_score, token_type |
| encrypted_data.token_service_provider.pan_reference_id string Returned | Unique identifier of the digital wallet token’s PAN within the card network. This value may vary, depending on the digital wallet. For example, the pan_reference_id may be different in an Apple Wallet and a Google Wallet for the same digital wallet token.Allowable Values: 1–255 chars |
| encrypted_data.token_service_provider.token_reference_id string Conditionally returned | Identifier that correlates the digital wallet token with the card network. This is the primary identifier for Visa. For Mastercard, this field is not populated until the token is active. Allowable Values: 255 char max |
| encrypted_data.token_service_provider.correlation_id string Conditionally returned | Unique value representing a tokenization request (Mastercard only). Allowable Values: 14 char max |
| encrypted_data.token_service_provider.token_requestor_id string Returned | Identifier of the token requestor. This identifier differs for each card network. Allowable Values: 1–50 chars |
| encrypted_data.token_service_provider.token_requestor_name string Returned | Human-readable name for the token requestor. In your code, we recommend using the token requestor identifier instead, because it is immutable once it has been created. Allowable Values: 1–100 chars |
| encrypted_data.token_service_provider.token_type string Returned | Comma-delimited list of digital wallet token types to display. Allowable Values: DEVICE_CLOUD_BASED, DEVICE_SECURE_ELEMENT, ECOMMERCE_DIGITAL_WALLET, MERCHANT_CARD_ON_FILE, PSEUDO_ACCOUNT |
| encrypted_data.token_service_provider.token_assurance_level string Conditionally returned | Specifies the assurance level of the token-to-PAN binding as defined by the payment network. Represents a general risk value from 00 to 99.Allowable Values: 2 char max |
| encrypted_data.token_service_provider.token_pan string Conditionally returned | Digital wallet token primary account number (PAN), also known as the Digital Account Number, Token Number, or Digital PAN (DPAN). Token PAN appears in masked format. To view the token PAN in clear text, use the /showtokenpan endpoint.Allowable Values: 19 char max |
| encrypted_data.token_service_provider.token_expiration string Conditionally returned | Expiration of the digital wallet token. Allowable Values: Format: MMyy |
| encrypted_data.token_service_provider.token_score string Conditionally returned | Token score assigned by the token service provider. This value is provided when it is received by the token service provider. Allowable Values: 25 char max |
| encrypted_data.token_service_provider.token_eligibility_decision string Conditionally returned | Token service provider’s recommendation as to whether the digital wallet token should be provisioned. Allowable Values: 50 char max |
| encrypted_data.device object Conditionally returned | Contains data about the provisioned device. Allowable Values: device_id, ip_address, language_code, location, name, phone_number, type |
| encrypted_data.device.type string Returned | Specifies the type of device being provisioned. This object is returned when relevant information is provided by the token service provider, typically for device-based digital wallets such as Google Wallet and Apple Wallet only. Allowable Values: APPLIANCE, GAMING_DEVICE, LAPTOP, MOBILE_PHONE, MOBILE_PHONE_OR_TABLET, PERSONAL_COMPUTER, TABLET, UNKNOWN, UNRECOGNIZED, WATCH, VEHICLE |
| encrypted_data.device.device_id string Conditionally returned | Identity number of the device. This value is returned if it is available for a given digital wallet token. Allowable Values: 255 char max |
| encrypted_data.device.phone_number string Conditionally returned | Telephone number of the device, as returned by the digital wallet provider. This value may be the full phone number, the last four digits, or null. Allowable Values: 20 char max |
| encrypted_data.device.name string Conditionally returned | Name of the device, as returned by the digital wallet provider. Allowable Values: 128 char max |
| encrypted_data.device.location string Conditionally returned | Geographic coordinates of the device at the time of the tokenization request, as returned by the digital wallet provider. Allowable Values: 25 char max |
| encrypted_data.device.ip_address string Conditionally returned | IPv4 address, as returned by the digital wallet provider. Allowable Values: 25 char max |
| encrypted_data.device.language_code string Conditionally returned | Language the device is configured to use, such as eng for English.Allowable Values: 36 char max |
| encrypted_data.address_verification object Conditionally returned | Contains the name and address of the cardholder for address verification. Allowable Values: name, postal_code, street_address |
| encrypted_data.address_verification.name string Conditionally returned | Name of the cardholder, as returned by the digital wallet provider. Allowable Values: 255 char max |
| encrypted_data.address_verification.street_address string Conditionally returned | Street address of the cardholder, as returned by the digital wallet provider. Allowable Values: 255 char max |
| encrypted_data.address_verification.postal_code string Conditionally returned | Postal code of the cardholder, such as a United States ZIP code, as returned by the digital wallet provider. Allowable Values: 50 char max |
| card_token string Conditionally returned | Unique identifier of the card. Allowable Values: 1–36 chars |
| created_time datetime Conditionally returned | Date and time when the resource was created, in UTC. Allowable Values: date-time Format: yyyy-MM-ddThh:mm:ssZ |
| fulfillment_status string Conditionally returned | Digital wallet token’s provisioning status. Allowable Values: DECISION_GREEN, DECISION_RED, DECISION_YELLOW, PROVISIONED, REJECTED |
| issuer_eligibility_decision string Conditionally returned | Card issuer’s recommendation as to whether the digital wallet token should be provisioned. Example values: 0000 (Approved), invalid.cid, avs.decline, token.activation, token.activation.verification.required.tspdecision, decision due to TSP risk managerAllowable Values: 255 char max |
| last_modified_time datetime Conditionally returned | Date and time when the resource was created, in UTC. Allowable Values: date-time Format: yyyy-MM-ddThh:mm:ssZ |
| state string Conditionally returned | Current state of the digital wallet token. Allowable Values: 1–255 chars |
| state_reason string Conditionally returned | Descriptive reason for the current state of the digital wallet token. Allowable Values: 255 char max |
| token string Conditionally returned | Unique identifier for the digital wallet token on the Marqeta platform. Allowable Values: 1–36 chars |
| wallet_provider_profile object Conditionally returned | Contains information held and provided by the digital wallet provider. This object is returned when relevant information is provided by the digital wallet provider. Allowable Values: account, device_score, obs_result, pan_source, reason_code, risk_assessment |
| wallet_provider_profile.account object Returned | Contains information related to the cardholder, as provided by the digital wallet provider. Allowable Values: email_address, id, score |
| wallet_provider_profile.account.id string Returned | Digital wallet provider’s unique identity number for the cardholder. This identity number does not correlate with other information. Allowable Values: 1–255 chars |
| wallet_provider_profile.account.email_address string Conditionally returned | Hashed version of the email address linked to the digital wallet. The exact hashing algorithm may vary, depending on the wallet and network. You can use this field to validate that email associated with digital wallet matches what is on file for the account. Data is hexBinary encoded.Allowable Values: Hex-encoded string |
| wallet_provider_profile.account.score string Conditionally returned | Wallet provider’s account score, indicating the confidence level associated with the account. The scale ranges from 1 to 5, where 5 indicates the highest level of confidence. The value in this file may be presented with or without a leading 0. Allowable Values: 2 char max |
| wallet_provider_profile.risk_assessment object Conditionally returned | Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token, as returned by the digital wallet provider. Allowable Values: score, version |
| wallet_provider_profile.risk_assessment.score string Conditionally returned | Digital wallet provider’s decision as to whether the digital wallet token should be provisioned. Allowable Values: DECISION_GREEN, DECISION_RED, DECISION_YELLOW |
| wallet_provider_profile.risk_assessment.version string Conditionally returned | Digital wallet provider’s risk version. NOTE: Changes in the version might indicate differences in other fields. Allowable Values: Version information, as provided by the wallet provider |
| wallet_provider_profile.device_score string Conditionally returned | Wallet provider device score on a scale from 1 to 5, indicating the confidence level of the device, where 5 indicates the highest level of confidence. Allowable Values: 1 to 5 |
| wallet_provider_profile.pan_source string Returned | Source from which the digital wallet provider obtained the card primary account number (PAN), as returned by the digital wallet provider. Allowable Values: CONTACTLESS_TAP, KEY_ENTERED, MOBILE_BANKING_APP, ON_FILE |
| wallet_provider_profile.reason_code string Conditionally returned | Comma-separated list of wallet provider reason codes, describing the reason for the wallet provider’s provisioning decision. NOTE: This list of reason codes is subject to change. Apple Wallet (Visa/Mastercard), Google Wallet/Samsung Wallet (Mastercard only) - 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 - Suspected fraud. - 0H - The phone number score is less than 3. Google Wallet/Samsung Wallet (Visa only) - A0 - Cardholder PAN associated with account within threshold days. - A1 - Wallet account holder name on file does not match cardholder entered name. - A2 - User’s account on device less than threshold days. - A3 - User account was created within threshold days. - A4 - Wallet account created within threshold days. - A5 - Changes made to account data within threshold days. - A6 - The number of provisioning attempts across all cards on this device in the last 24 hours exceeds the threshold. - A7 - The wallet account into which the card is being provisioned contains distinct names greater than threshold. - A8 - Device provisioning location outside of cardholder’s wallet account home country. - A9 - Suspended cards in the wallet account is greater than threshold. - AA - This account has not had activity within threshold period. - AB - Number of days since device was last reported lost is less than threshold days. - AC - Number of transactions in last 12 months less than threshold number. - AD - Number of active tokens greater than threshold. - AE - Number of devices with Same UserID with token is greater than threshold. - AF - Number of active tokens on all devices is greater than threshold. - AG - Issuer deferred ID&V decision. - AH - Issuer encrypted payment instrument data expired. - AI - User/device receiving encrypted payment instrument data is different than the one that is provisioning the token. - AL - Encrypted payment instrument data is pushed to a different device than the one that issuer application authenticated. - AM - Encrypted payment instrument data is pushed to a different user than the cardholder. - AN - Encrypted Payment Instrument Data is being pushed by the Issuer to the same device that the Issuer application authenticated, but without any upfront authentication. - AO - Encrypted Payment Instrument Data is being pushed by the Issuer to the same device that the Issuer application authenticated, but with successful upfront authentication. Allowable Values: 100 char max |
Sample response body
JSON
{
"token": "my_digital_wallet_token_01",
"card_token": "my_card_01",
"state": "ACTIVE",
"state_reason": "Digital wallet token provisioned to digital wallet",
"fulfillment_status": "PROVISIONED",
"issuer_eligibility_decision": "0000",
"created_time": "2022-06-16T22:24:02Z",
"last_modified_time": "2022-09-04T20:12:10Z",
"encrypted_data": {
"token_service_provider": {
"token_reference_id": "DNITHE343434343459",
"pan_reference_id": "V-123343434343434",
"token_requestor_id": "40010030273",
"token_requestor_name": "APPLE_PAY",
"token_type": "DEVICE_SECURE_ELEMENT",
"token_pan": "4111111111111111",
"token_expiration": "1225",
"token_eligibility_decision": "DECISION_GREEN"
},
"device": {
"type": "MOBILE_PHONE",
"language_code": "eng",
"device_id": "01111ABCB11100210111111111111E261D1AA1F11A1",
"phone_number": "18000001111",
"name": "My iPhone",
"location": "+11.11/-11.11",
"ip_address": "1.1.1.1"
},
"address_verification": {
"street_address": "180 grand ave,",
"zip": "94612"
}
},
"wallet_provider_profile": {
"account": {
"id": "ABCD2345",
"email_address": "F11AAAA1A011C11111111111A1AA111F4D3E31DB1111AE2C111211D7C11E11A",
"score": "5"
},
"risk_assessment": {
"score": "DECISION_GREEN",
"version": "0001.00"
},
"device_score": "3",
"pan_source": "ON_FILE"
}
}