> ## Documentation Index
> Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Tokenization-as-a-Service
> Marqeta offers tokenization as a service, allowing you to use Marqeta's tokenization features even if Marqeta is not your issuer processor.
export const EndpointCard = ({method = "API", title, children, href, arrow = true}) => {
const METHOD_STYLES = {
GET: {
bg: "mint-bg-green-400/20 dark:mint-bg-green-400/20",
text: "mint-text-green-700 dark:mint-text-green-400",
border: "mint-border-green-300 dark:mint-border-green-700"
},
POST: {
bg: "mint-bg-blue-400/20 dark:mint-bg-blue-400/20",
text: "mint-text-blue-700 dark:mint-text-blue-400"
},
PUT: {
bg: "mint-bg-yellow-400/20 dark:mint-bg-yellow-400/20",
text: "mint-text-yellow-700 dark:mint-text-yellow-400"
},
PATCH: {
bg: "mint-bg-orange-400/20 dark:mint-bg-orange-400/20",
text: "mint-text-orange-700 dark:mint-text-orange-400"
},
DELETE: {
bg: "mint-bg-red-400/20 dark:mint-bg-red-400/20",
text: "mint-text-red-700 dark:mint-text-red-400"
},
API: {
bg: "mint-bg-black",
text: "mint-text-white"
}
};
const MethodBadge = ({method}) => {
const style = METHOD_STYLES[method?.toUpperCase()] ?? METHOD_STYLES.GET;
return
{method?.toUpperCase()}
;
};
const content =
{}
{}
{title}
{children &&
{children}
}
Create digital wallet provisioning request for Apple Wallet
**Action:** `POST`\
**Endpoint:** `/digitalwalletprovisionrequests/applepay`
{/* */}
Use the `/digitalwalletprovisionrequests/applepay` endpoint to return card data for use in provisioning a digital wallet token into Apple Wallet.
The returned card data is encrypted using the digital wallet provider’s encryption key, thereby reducing your PCI compliance overhead.
Request body
| Fields | Description |
| --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| encrypted\_card\_data
object
Required | Encrypted data object. This object is first encrypted using the recipient’s public key and sent in JSON Web Encryption (JWE) format and then signed using the sender’s private key using JSON Web Signature (JWS). It represents the decrypted format.
**Allowable Values:**
`card_token`, `card_type`, `cardholder_info`, `expiration`, `metadata`, `primary_account_number` |
| encrypted\_card\_data.**expiration**
object
Required | Specifies the expiry date for the card.
**Allowable Values:**
`month`, `year` |
| encrypted\_card\_data.expiration.**month**
string
Required | Specifies the expiry month for the card in MM format. `01`, for example.
**Allowable Values:**
Format: MM |
| encrypted\_card\_data.expiration.**year**
string
Required | Specifies the expiry year for the card in yyyy format. `2024`, for example.
**Allowable Values:**
Format: yyyy |
| encrypted\_card\_data.**card\_token**
string
Optional | Unique identifier of the card.
**Allowable Values:**
1–36 chars |
| encrypted\_card\_data.**primary\_account\_number**
string
Required | Account number of the card being tokenized.
**Allowable Values:**
12–19 chars |
| encrypted\_card\_data.**card\_type**
string
Optional | Specifies the type of card. This field is required for Samsung Wallet.
**Allowable Values:**
`CREDIT`, `DEBIT` |
| encrypted\_card\_data.**cardholder\_info**
object
Optional | Contains personal information about the cardholder.
**Allowable Values:**
`cardholder_address`, `email_address`, `first_name`, `last_name`, `phone_number` |
| encrypted\_card\_data.cardholder\_info.**first\_name**
string
Optional | First or given name of the cardholder.
**Allowable Values:**
40 char max |
| encrypted\_card\_data.cardholder\_info.**last\_name**
string
Optional | Last or family name of the cardholder.
**Allowable Values:**
40 char max |
| encrypted\_card\_data.cardholder\_info.**cardholder\_address**
object
Optional | Specifies the cardholder’s address.
**Allowable Values:**
`address_line_1`, `address_line_2`, `city`, `country_code`, `postal_code`, `state` |
| encrypted\_card\_data.cardholder\_info.cardholder\_address.**address\_line\_1**
string
Required | Street address of the cardholder.
**Allowable Values:**
1–255 chars |
| encrypted\_card\_data.cardholder\_info.cardholder\_address.**address\_line\_2**
string
Optional | Additional address information for the cardholder, such as a suite, floor, room, PO Box or apartment number. `Suite 600`, for example.
**Allowable Values:**
255 char max |
| encrypted\_card\_data.cardholder\_info.cardholder\_address.**postal\_code**
string
Required | Postal code of the cardholder.
**Allowable Values:**
1–50 chars |
| encrypted\_card\_data.cardholder\_info.cardholder\_address.**city**
string
Optional | City of the cardholder.
**Allowable Values:**
40 char max |
| encrypted\_card\_data.cardholder\_info.cardholder\_address.**state**
string
Optional | State or province code associated with the cardholder’s address.
**Allowable Values:**
3 char max |
| encrypted\_card\_data.cardholder\_info.cardholder\_address.**country\_code**
string
Optional | Two-character ISO 3166-1 alpha-2 country code. `US`, for example.
**Allowable Values:**
2 char max |
| encrypted\_card\_data.cardholder\_info.**email\_address**
string
Optional | Email address of the cardholder.
**Allowable Values:**
255 char max |
| encrypted\_card\_data.cardholder\_info.**phone\_number**
string
Optional | Phone number of the cardholder. This number is used when Marqeta performs step-up authentication on your behalf.
**Allowable Values:**
255 char max |
| encrypted\_card\_data.**metadata**
array of objects
Optional | Additional metadata related to the card details object.
**Allowable Values:**
Valid array of card details metadata objects |
| encrypted\_card\_data.metadata\[].**name**
string
Required | Specifies the metadata attribute name, such as `CARD_ART_ID`, `MAX_TOKENS_PER_CARD`, and so on.
**Allowable Values:**
255 char max |
| encrypted\_card\_data.metadata\[].**value**
string
Required | Specifies the value of the metadata attribute.
**Allowable Values:**
255 char max |
| card\_token
string
Optional | Unique identifier of the card.
**Allowable Values:**
1–36 chars |
| device\_type
string
Optional | Specifies the type of device.
**Allowable Values:**
`UNKNOWN`, `MOBILE_PHONE`, `TABLET`, `WATCH`, `MOBILE_PHONE_OR_TABLET`, `PERSONAL_COMPUTER`, `VEHICLE`, `APPLIANCE`, `LAPTOP`, `GAMING_DEVICE`, `UNRECOGNIZED` |
| provisioning\_app\_version
string
Optional | Specifies the version of the application making the provisioning request. This field is used for debugging and fraud prevention.
**Allowable Values:**
50 char max |
| certificates
array of strings
Required | Leaf and sub-CA certificates provided by Apple. Base 64 encoded. The first element of the array should be the leaf certificate, followed by the sub-CA.
**Allowable Values:**
1–8192 chars |
| nonce
string
Required | One-time-use nonce provided by Apple for security purposes.
**Allowable Values:**
1–32 chars |
| nonce\_signature
string
Required | Apple-provided signature to the nonce.
**Allowable Values:**
1–512 chars |
Sample request body
```json JSON expandable lines wrap theme={null}
{
"encrypted_card_data": {
"expiration": {
"month": "01",
"year": "2025"
},
"card_token": "card-token-811",
"primary_account_number": "4111111111111111",
"cardholder_info": {
"first_name": "Jane",
"last_name": "Liu",
"cardholder_address": {
"city": "Oakland",
"state": "CA",
"address_line_1": "180 Grand Ave",
"address_line_2": "Floor 6",
"postal_code": "94612",
"country_code": "US"
},
"email_address": "marqetaTest@marqeta.com",
"phone_number": "1234567890"
}
},
"nonce": "tKVkWRmUTaUiE3zO",
"certificates": [
"MIID/DCCA6OgAwIBAgIIRBkEefDVkQ0wCgYIKoZIzj....",
"MIIC9zCCAnygAwIBAgIIb+/Y9emjp+4wCgYIKoZIzj...."
],
"nonce_signature": "rcQ+z8FCP+jKkgRJ",
"provisioning_app_version": "2.13.7"
}
```
Response body
| Fields | Description |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| created\_time
datetime
Returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
Format: yyyy-MM-ddThh:mm:ssZ |
| last\_modified\_time
datetime
Returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
Format: yyyy-MM-ddThh:mm:ssZ |
| card\_token
string
Conditionally returned | Unique identifier of the card.
**Allowable Values:**
1–36 chars |
| encrypted\_pass\_data
string
Returned | This object is encrypted with a shared key derived from the Apple Public Certificates and the generated ephemeral private key. This is binary data, but is presented here in base64 format. Do not persist this data.
Because the scheme and contents could change, they are only subject to the `maxLength` limit of the NSData object, which is eight exabytes. For more information, see [https://developer.apple.com/documentation/passkit/pkaddpaymentpassrequest/1615926-encryptedpassdata](https://developer.apple.com/documentation/passkit/pkaddpaymentpassrequest/1615926-encryptedpassdata).
**Allowable Values:**
1–1000000 chars |
| activation\_data
string
Returned | Cryptographic one-time passcode (OTP) conforming to the payment network operator or service provider specifications. This is binary data, but is presented here in base64 format and has no practical max length.
For more information, see [https://developer.apple.com/documentation/passkit/pkaddpaymentpassrequest/1615914-activationdata](https://developer.apple.com/documentation/passkit/pkaddpaymentpassrequest/1615914-activationdata).
**Allowable Values:**
1–1000000 chars |
| ephemeral\_public\_key
string
Returned | Ephemeral public key used for the provisioning attempt. This is binary data, but is presented here in base64 format and has no practical max length.
For more information, see [https://developer.apple.com/documentation/passkit/pkaddpaymentpassrequest/1615952-ephemeralpublickey](https://developer.apple.com/documentation/passkit/pkaddpaymentpassrequest/1615952-ephemeralpublickey).
**Allowable Values:**
1–1000000 chars |
Sample response body
```json JSON lines wrap theme={null}
{
"created_time": "2022-07-08T16:37:28Z",
"last_modified_time": "2022-07-08T16:37:28Z",
"card_token": "card-token-9",
"encrypted_pass_data": "UnYokfsEG5fQbKPy+4UJ3BF5N0D....",
"activation_data": "TUJQQUMtMS1GSy03NDgwNTIuMS0tVER....",
"ephemeral_public_key": "BCJ++11ucFSG7Z+ZECshFHSFpA...."
}
```
Create digital wallet provisioning request for Google Wallet
**Action:** `POST`\
**Endpoint:** `/digitalwalletprovisionrequests/googlepay`
{/* */}
Use the `/digitalwalletprovisionrequests/googlepay` endpoint to return card data for use in provisioning a digital wallet token into Google Wallet.
The returned card data is encrypted using the digital wallet provider’s encryption key, thereby reducing your PCI compliance overhead. create digital wallet provisioning request for Google Wallet.
Request body
| Fields | Description |
| --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| encrypted\_card\_data
object
Required | Encrypted data object. This object is first encrypted using the recipient’s public key and sent in JSON Web Encryption (JWE) format and then signed using the sender’s private key using JSON Web Signature (JWS). It represents the decrypted format.
**Allowable Values:**
`card_token`, `card_type`, `cardholder_info`, `expiration`, `metadata`, `primary_account_number` |
| encrypted\_card\_data.**expiration**
object
Required | Specifies the expiry date for the card.
**Allowable Values:**
`month`, `year` |
| encrypted\_card\_data.expiration.**month**
MM
Required | Specifies the expiry month for the card in MM format. `01`, for example.
**Allowable Values:**
Format: MM |
| encrypted\_card\_data.expiration.**year**
yyyy
Required | Specifies the expiry year for the card in yyyy format. `2024`, for example.
**Allowable Values:**
Format: yyyy |
| encrypted\_card\_data.**card\_token**
string
Optional | Unique identifier of the card.
**Allowable Values:**
1–36 chars |
| encrypted\_card\_data.**primary\_account\_number**
string
Required | Account number of the card being tokenized.
**Allowable Values:**
12–19 chars |
| encrypted\_card\_data.**card\_type**
string
Optional | Specifies the type of card. This field is required for Samsung Wallet.
**Allowable Values:**
`CREDIT`, `DEBIT` |
| encrypted\_card\_data.**cardholder\_info**
object
Optional | Contains personal information about the cardholder.
**Allowable Values:**
`cardholder_address`, `email_address`, `first_name`, `last_name`, `phone_number` |
| encrypted\_card\_data.cardholder\_info.**first\_name**
string
Optional | First or given name of the cardholder.
**Allowable Values:**
40 char max |
| encrypted\_card\_data.cardholder\_info.**last\_name**
string
Optional | Last or family name of the cardholder.
**Allowable Values:**
40 char max |
| encrypted\_card\_data.cardholder\_info.**cardholder\_address**
object
Optional | Specifies the cardholder’s address.
**Allowable Values:**
`address_line_1`, `address_line_2`, `city`, `country_code`, `postal_code`, `state` |
| encrypted\_card\_data.cardholder\_info.cardholder\_address.**address\_line\_1**
string
Required | Street address of the cardholder.
**Allowable Values:**
1–255 chars |
| encrypted\_card\_data.cardholder\_info.cardholder\_address.**address\_line\_2**
string
Optional | Additional address information for the cardholder, such as a suite, floor, room, PO Box or apartment number. `Suite 600`, for example.
**Allowable Values:**
255 char max |
| encrypted\_card\_data.cardholder\_info.cardholder\_address.**postal\_code**
string
Required | Postal code of the cardholder.
**Allowable Values:**
1–50 chars |
| encrypted\_card\_data.cardholder\_info.cardholder\_address.**city**
string
Optional | City of the cardholder.
**Allowable Values:**
40 char max |
| encrypted\_card\_data.cardholder\_info.cardholder\_address.**state**
string
Optional | State or province code associated with the cardholder’s address.
**Allowable Values:**
3 char max |
| encrypted\_card\_data.cardholder\_info.cardholder\_address.**country\_code**
string
Optional | Two-character ISO 3166-1 alpha-2 country code. `US`, for example.
**Allowable Values:**
2 char max |
| encrypted\_card\_data.cardholder\_info.**email\_address**
string
Optional | Email address of the cardholder.
**Allowable Values:**
255 char max |
| encrypted\_card\_data.cardholder\_info.**phone\_number**
string
Optional | Phone number of the cardholder. This number is used when Marqeta performs step-up authentication on your behalf.
**Allowable Values:**
255 char max |
| encrypted\_card\_data.**metadata**
array of objects
Optional | Additional metadata related to the card details object.
**Allowable Values:**
Valid array of card details metadata objects |
| encrypted\_card\_data.metadata\[].**name**
string
Required | Specifies the metadata attribute name, such as `CARD_ART_ID`, `MAX_TOKENS_PER_CARD`, and so on.
**Allowable Values:**
255 char max |
| encrypted\_card\_data.metadata\[].**value**
string
Required | Specifies the value of the metadata attribute.
**Allowable Values:**
255 char max |
| card\_token
string
Optional | Unique identifier of the card.
**Allowable Values:**
1–36 chars |
| device\_type
string
Optional | Specifies the type of device.
**Allowable Values:**
`UNKNOWN`, `MOBILE_PHONE`, `TABLET`, `WATCH`, `MOBILE_PHONE_OR_TABLET`, `PERSONAL_COMPUTER`, `VEHICLE`, `APPLIANCE`, `LAPTOP`, `GAMING_DEVICE`, `UNRECOGNIZED` |
| provisioning\_app\_version
string
Optional | Specifies the version of the application making the provisioning request. This field is used for debugging and fraud prevention.
**Allowable Values:**
50 char max |
| wallet\_account\_id
string
Required | User’s Google Wallet account ID, as provided by Google during the provisioning process. Google refers to this field as `ActiveWalletId`.
**Allowable Values:**
1–50 chars |
| device\_id
string
Required | Unique identifier of the user’s Google device, as provided by Google during the provisioning process. Google refers to this field as `StableHardwareId`.
**Allowable Values:**
1–24 chars |
Sample request body
```json JSON expandable lines wrap theme={null}
{
"encrypted_card_data": {
"expiration": {
"month": "01",
"year": "2025"
},
"card_token": "card-token-811",
"primary_account_number": "4111111111111111",
"cardholder_info": {
"first_name": "Jane",
"last_name": "Liu",
"cardholder_address": {
"city": "Oakland",
"state": "CA",
"address_line_1": "180 Grand Ave",
"address_line_2": "Floor 6",
"postal_code": "94612",
"country_code": "US"
},
"email_address": "marqetaTest@marqeta.com",
"phone_number": "1234567890"
}
},
"device_id": "W85OGhjZTk2dsr452dgsr51j",
"wallet_user_id": "ae25OGhjZTk2dsr452dgsr51",
"provisioning_app_version": "2.13.3",
"wallet_account_id": "ae123GhjZTk1dsr123dgsr12"
}
```
Response body
| Fields | Description |
| ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| created\_time
datetime
Returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
Format: yyyy-MM-ddThh:mm:ssZ |
| last\_modified\_time
datetime
Returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
Format: yyyy-MM-ddThh:mm:ssZ |
| card\_token
string
Conditionally returned | Unique identifier of the card.
**Allowable Values:**
1–36 chars |
| push\_tokenize\_request\_data
object
Returned | Contains data pertaining to a Google push tokenization request.
**Allowable Values:**
`display_name`, `last_digits`, `network`, `opaque_payment_card`, `token_service_provider`, `user_address` |
| push\_tokenize\_request\_data.**display\_name**
string
Returned | Name of the card as displayed in the digital wallet, typically showing the card brand and last four digits of the primary account number (PAN). `Visa 5678`, for example.
**Allowable Values:**
255 char max |
| push\_tokenize\_request\_data.**last\_digits**
string
Returned | Last four digits of the funding primary account number (FPAN), which is the primary account number of the physical or virtual card.
**Allowable Values:**
4 chars |
| push\_tokenize\_request\_data.**network**
string
Returned | Card network, as defined by Google; expected to align with the value of the `token_service_provider` field.
**Allowable Values:**
`Mastercard`, `Visa` |
| push\_tokenize\_request\_data.**token\_service\_provider**
string
Returned | Token service provider, as defined by Google; expected to align with the value of the `network` field.
**Allowable Values:**
`TOKEN_PROVIDER_MASTERCARD`, `TOKEN_PROVIDER_VISA` |
| push\_tokenize\_request\_data.**opaque\_payment\_card**
string
Returned | Encrypted card data passed to Google in base64 format. This data should not be modified in transit. For more information, see [https://developers.google.com/pay/issuers/apis/push-provisioning/android/push-provisioning-objects#opaque\_payment\_card\_opc](https://developers.google.com/pay/issuers/apis/push-provisioning/android/push-provisioning-objects#opaque_payment_card_opc).
**Allowable Values:**
1–5000 chars |
| push\_tokenize\_request\_data.**user\_address**
object
Returned | Contains cardholder address information for a Google Wallet push tokenization request. Although not required, Marqeta recommends that you provide all the information in this object. Any missing or invalid address information may result in the user being prompted to complete or correct the address. For more information, see [https://developers.google.com/pay/issuers/apis/push-provisioning/android/push-provisioning-objects#useraddress](https://developers.google.com/pay/issuers/apis/push-provisioning/android/push-provisioning-objects#useraddress).
**Allowable Values:**
`address1`, `address2`, `city`, `country`, `name`, `phone`, `postal_code` |
| push\_tokenize\_request\_data.user\_address.**name**
string
Conditionally returned | Name of the cardholder.
**Allowable Values:**
255 char max |
| push\_tokenize\_request\_data.user\_address.**address1**
string
Returned | Street address of the cardholder.
**Allowable Values:**
1–255 chars |
| push\_tokenize\_request\_data.user\_address.**address2**
string
Conditionally returned | Secondary address information, such as a suite or apartment number
**Allowable Values:**
255 char max |
| push\_tokenize\_request\_data.user\_address.**city**
string
Conditionally returned | City of the cardholder.
**Allowable Values:**
255 char max |
| push\_tokenize\_request\_data.user\_address.**state**
string
Conditionally returned | State or province code of the address.
**Allowable Values:**
3 char max |
| push\_tokenize\_request\_data.user\_address.**postal\_code**
string
Returned | Postal code of the cardholder, such as a United States ZIP code.
**Allowable Values:**
1–50 chars |
| push\_tokenize\_request\_data.user\_address.**country**
string
Conditionally returned | Two-character ISO 3166-1 alpha-2 country code.
**Allowable Values:**
2 char max |
| push\_tokenize\_request\_data.user\_address.**phone**
string
Conditionally returned | Phone number of the cardholder.
**Allowable Values:**
50 char max |
Sample response body
```json JSON expandable lines wrap theme={null}
{
"created_time": "2022-09-09T18:08:07Z",
"last_modified_time": "2022-09-09T18:08:07Z",
"card_token": "my_card_01",
"push_tokenize_request_data": {
"display_name": "Visa Card",
"last_digits": "1008",
"network": "Visa",
"token_service_provider": "TOKEN_PROVIDER_VISA",
"opaque_payment_card": "eyJraWQiOiIzVkhSWVVSUlRVT1....",
"user_address": {
"name": "Jane Liu",
"address1": "180 Grand Avenue",
"city": "Oakland",
"state": "CA",
"zip": "94612",
"country": "US",
"phone": "18000001111",
"postal_code": "94612"
}
}
}
```
Create digital wallet provisioning request for Samsung Wallet
**Action:** `POST`\
**Endpoint:** `/digitalwalletprovisionrequests/samsungpay`
{/* */}
Use the `/digitalwalletprovisionrequests/samsungpay` endpoint to return card data for use in provisioning a digital wallet token into Samsung Wallet.
The returned card data is encrypted using the digital wallet provider’s encryption key, thereby reducing your PCI compliance overhead.
Request body
| Fields | Description |
| --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| encrypted\_card\_data
object
Required | Encrypted data object. This object is first encrypted using the recipient’s public key and sent in JSON Web Encryption (JWE) format and then signed using the sender’s private key using JSON Web Signature (JWS). It represents the decrypted format.
**Allowable Values:**
`card_token`, `card_type`, `cardholder_info`, `expiration`, `metadata`, `primary_account_number` |
| encrypted\_card\_data.**expiration**
object
Required | Specifies the expiry date for the card.
**Allowable Values:**
`month`, `year` |
| encrypted\_card\_data.expiration.**month**
MM
Required | Specifies the expiry month for the card in MM format. `01`, for example.
**Allowable Values:**
Format: MM |
| encrypted\_card\_data.expiration.**year**
yyyy
Required | Specifies the expiry year for the card in yyyy format. `2024`, for example.
**Allowable Values:**
Format: yyyy |
| encrypted\_card\_data.**card\_token**
string
Optional | Unique identifier of the card.
**Allowable Values:**
1–36 chars |
| encrypted\_card\_data.**primary\_account\_number**
string
Required | Account number of the card being tokenized.
**Allowable Values:**
12–19 chars |
| encrypted\_card\_data.**card\_type**
string
Optional | Specifies the type of card. This field is required for Samsung Wallet.
**Allowable Values:**
`CREDIT`, `DEBIT` |
| encrypted\_card\_data.**cardholder\_info**
object
Optional | Contains personal information about the cardholder.
**Allowable Values:**
`cardholder_address`, `email_address`, `first_name`, `last_name`, `phone_number` |
| encrypted\_card\_data.cardholder\_info.**first\_name**
string
Optional | First or given name of the cardholder.
**Allowable Values:**
40 char max |
| encrypted\_card\_data.cardholder\_info.**last\_name**
string
Optional | Last or family name of the cardholder.
**Allowable Values:**
40 char max |
| encrypted\_card\_data.cardholder\_info.**cardholder\_address**
object
Optional | Specifies the cardholder’s address.
**Allowable Values:**
`address_line_1`, `address_line_2`, `city`, `country_code`, `postal_code`, `state` |
| encrypted\_card\_data.cardholder\_info.cardholder\_address.**address\_line\_1**
string
Required | Street address of the cardholder.
**Allowable Values:**
1–255 chars |
| encrypted\_card\_data.cardholder\_info.cardholder\_address.**address\_line\_2**
string
Optional | Additional address information for the cardholder, such as a suite, floor, room, PO Box or apartment number. `Suite 600`, for example.
**Allowable Values:**
255 char max |
| encrypted\_card\_data.cardholder\_info.cardholder\_address.**postal\_code**
string
Required | Postal code of the cardholder.
**Allowable Values:**
1–50 chars |
| encrypted\_card\_data.cardholder\_info.cardholder\_address.**city**
string
Optional | City of the cardholder.
**Allowable Values:**
40 char max |
| encrypted\_card\_data.cardholder\_info.cardholder\_address.**state**
string
Optional | State or province code associated with the cardholder’s address.
**Allowable Values:**
3 char max |
| encrypted\_card\_data.cardholder\_info.cardholder\_address.**country\_code**
string
Optional | Two-character ISO 3166-1 alpha-2 country code. `US`, for example.
**Allowable Values:**
2 char max |
| encrypted\_card\_data.cardholder\_info.**email\_address**
string
Optional | Email address of the cardholder.
**Allowable Values:**
255 char max |
| encrypted\_card\_data.cardholder\_info.**phone\_number**
string
Optional | Phone number of the cardholder. This number is used when Marqeta performs step-up authentication on your behalf.
**Allowable Values:**
255 char max |
| encrypted\_card\_data.**metadata**
array of objects
Optional | Additional metadata related to the card details object.
**Allowable Values:**
Valid array of card details metadata objects |
| encrypted\_card\_data.metadata\[].**name**
string
Required | Specifies the metadata attribute name, such as `CARD_ART_ID`, `MAX_TOKENS_PER_CARD`, and so on.
**Allowable Values:**
255 char max |
| encrypted\_card\_data.metadata\[].**value**
string
Required | Specifies the value of the metadata attribute.
**Allowable Values:**
255 char max |
| card\_token
string
Optional | Unique identifier of the card.
**Allowable Values:**
1–36 chars |
| device\_type
string
Optional | Specifies the type of device.
**Allowable Values:**
`UNKNOWN`, `MOBILE_PHONE`, `TABLET`, `WATCH`, `MOBILE_PHONE_OR_TABLET`, `PERSONAL_COMPUTER`, `VEHICLE`, `APPLIANCE`, `LAPTOP`, `GAMING_DEVICE`, `UNRECOGNIZED` |
| provisioning\_app\_version
string
Optional | Specifies the version of the application making the provisioning request. This field is used for debugging and fraud prevention.
**Allowable Values:**
50 char max |
| wallet\_user\_id
string
Required | User’s Samsung wallet account identifier, as provided by Samsung during the provisioning process.
**Allowable Values:**
1–50 chars |
| device\_id
string
Required | User’s Samsung device unique identifier, as provided by Samsung during the provisioning process.
**Allowable Values:**
1–24 chars |
Sample request body
```json JSON expandable lines wrap theme={null}
{
"encrypted_card_data": {
"expiration": {
"month": "01",
"year": "2025"
},
"card_token": "card-token-811",
"card_type": "CREDIT",
"primary_account_number": "4111111111111111",
"cardholder_info": {
"first_name": "Jane",
"last_name": "Liu",
"cardholder_address": {
"city": "Oakland",
"state": "CA",
"address_line_1": "180 Grand Ave",
"address_line_2": "Floor 6",
"postal_code": "94612",
"country_code": "US"
},
"email_address": "marqetaTest@marqeta.com",
"phone_number": "1234567890"
}
},
"device_id": "W85OGhjZTk2dsr452dgsr51j",
"wallet_user_id": "ae25OGhjZTk2dsr452dgsr51",
"provisioning_app_version": "2.13.3"
}
```
Response body
| Fields | Description |
| ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| created\_time
datetime
Returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
Format: yyyy-MM-ddThh:mm:ssZ |
| last\_modified\_time
datetime
Returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
Format: yyyy-MM-ddThh:mm:ssZ |
| card\_token
string
Conditionally returned | Unique identifier of the card.
**Allowable Values:**
1–36 chars |
| push\_tokenize\_request\_data
object
Returned | Contains data pertaining to a Samsung push tokenization request.
**Allowable Values:**
`card_type`, `display_name`, `extra_provision_payload`, `last_digits`, `network`, `token_service_provider` |
| push\_tokenize\_request\_data.**display\_name**
string
Returned | Name of the card as displayed in the digital wallet, typically showing the card brand and last four digits of the primary account number (PAN). `Visa 5678`, for example.
**Allowable Values:**
255 char max |
| push\_tokenize\_request\_data.**last\_digits**
string
Returned | Last four digits of the funding primary account number (FPAN), which is the primary account number of the physical or virtual card.
**Allowable Values:**
4 chars |
| push\_tokenize\_request\_data.**network**
string
Returned | Card network, as defined by Google; expected to align with the value of the `token_service_provider` field.
**Allowable Values:**
`Visa`, `Mastercard` |
| push\_tokenize\_request\_data.**token\_service\_provider**
string
Returned | Token service provider, as defined Google; expected to align with the value of the `network` field.
**Allowable Values:**
`MC`, `VI` |
| push\_tokenize\_request\_data.**extra\_provision\_payload**
string
Returned | Encrypted card or cardholder details.
**Allowable Values:**
Any value |
| push\_tokenize\_request\_data.**card\_type**
string
Returned | Specifies the type of payment card.
**Allowable Values:**
`CREDIT`, `DEBIT`, `GIFT`, `LOYALTY`, `PAYMENT` |
Sample response body
```json JSON lines wrap theme={null}
{
"created_time": "2022-09-09T18:08:05Z",
"last_modified_time": "2022-09-09T18:08:05Z",
"card_token": "my_card_01",
"push_tokenize_request_data": {
"display_name": "Mastercard Card",
"last_digits": "6591",
"network": "Mastercard",
"token_service_provider": "MC",
"extra_provision_payload": "ewogICJjYXJkSW5mbyIgOiB7CiAgICAicHVibGl....",
"card_type": "PAYMENT"
}
}
```
List digital wallet tokens
**Action:** `GET`\
**Endpoint:** `/digitalwallettokens`
{/* */}
Use the `/digitalwallettokens` endpoint to retrieve a list of digital wallet tokens.
URL query parameters
| Fields | Description |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count
integer
Optional | Number of resources to retrieve.
**Allowable Values:**
Any integer |
| start\_index
integer
Optional | Sort order index of the first resource to retrieve.
**Allowable Values:**
Any integer |
| fields
string
Optional | Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields.
**Allowable Values:**
Comma-delimited list of fields, or blank |
| sort\_by
string
Optional | Field on which to sort. Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`. Prefix the field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order.
**Allowable Values:**
`createdTime`, `lastModifiedTime`, or any field in the resource model |
| start\_date
string
Optional | Date when the digital wallet token becomes active.
**Allowable Values:**
Format: yyyy-MM-dd |
| end\_date
string
Optional | Expiration date of the digital wallet token.
**Allowable Values:**
Format: yyyy-MM-dd |
| pan\_reference\_id
string
Optional | Unique identifier of the digital wallet token’s primary account number (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:**
Any value |
| token\_reference\_id
string
Optional | Unique identifier of the digital wallet token within the card network. The `token_reference_id` is unique at the card network level. This is the primary identifier for Visa.
**Allowable Values:**
Any value |
| correlation\_id
string
Optional | Unique value representing a tokenization request (Mastercard only).
**Allowable Values:**
Any value |
| token\_type
string
Optional | Comma-delimited list of digital wallet token types to display.
**Allowable Values:**
255 char max
**Example Values:**`DEVICE_SECURE_ELEMENT`, `MERCHANT_CARD_ON_FILE`, `DEVICE_CLOUD_BASED`, `ECOMMERCE_DIGITAL_WALLET`, `PSEUDO_ACCOUNT`. |
| token\_requestor\_name
string
Optional | Name of the token requestor within the card network.
**NOTE:** The list of example values for this field is maintained by the card networks and is subject to change.
**Allowable Values:**
255 char max
**Example Values:**
- **Mastercard** - `APPLE_PAY`, `ANDROID_PAY`, `SAMSUNG_PAY`
- **Visa** - `APPLE_PAY`, `ANDROID_PAY`, `SAMSUNG_PAY`, `MICROSOFT_PAY`, `VISA_CHECKOUT`, `FACEBOOK`, `NETFLIX`, `FITBIT_PAY`, `GARMIN_PAY` |
| state
string
Optional | Comma-delimited list of digital wallet token states to display.
**Allowable Values:**
255 char max
**Example Values:**`REQUESTED`, `REQUEST_DECLINED`, `TERMINATED`, `SUSPENDED`, `ACTIVE` |
| embed
string
Optional | Optional embedded `user` object.
**Allowable Values:**
Existing `user` object |
Response body
| Fields | Description |
| ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count
integer
Returned | Number of resources returned.
This field is returned if there are resources in your returned array.
**Allowable Values:**
Any integer |
| start\_index
integer
Returned | Sort order index of the first resource in the returned array.
This field is returned if there are resources in your returned array.
**Allowable Values:**
Any integer |
| end\_index
integer
Returned | Sort order index of the last resource in the returned array.
This field is returned if there are resources in your returned array.
**Allowable Values:**
Any integer |
| is\_more
boolean
Conditionally returned | A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that no more unreturned resources exist.
This field is returned if there are resources in your returned array.
**Allowable Values:**
`true`, `false` |
| data
array of undefineds
Conditionally returned | Array of digital wallet token objects.
**Allowable Values:**
Valid data array of one or more digital wallet token objects.
Objects are returned as appropriate to your query. |
| data\[].**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` |
| data\[].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` |
| data\[].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 |
| data\[].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 |
| data\[].encrypted\_data.token\_service\_provider.**correlation\_id**
string
Conditionally returned | Unique value representing a tokenization request (Mastercard only).
**Allowable Values:**
14 char max |
| data\[].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 |
| data\[].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 |
| data\[].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` |
| data\[].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 |
| data\[].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:**
Any value |
| data\[].encrypted\_data.token\_service\_provider.**token\_expiration**
MMyy
Conditionally returned | Expiration of the digital wallet token.
**Allowable Values:**
Format: MMyy |
| data\[].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 |
| data\[].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 |
| data\[].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` |
| data\[].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`, `WATCH`, `VEHICLE`, `UNKNOWN`, `UNRECOGNIZED` |
| data\[].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 |
| data\[].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 |
| data\[].encrypted\_data.device.**name**
string
Conditionally returned | Name of the device, as returned by the digital wallet provider.
**Allowable Values:**
128 char max |
| data\[].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 |
| data\[].encrypted\_data.device.**ip\_address**
string
Conditionally returned | IPv4 address, as returned by the digital wallet provider.
**Allowable Values:**
25 char max |
| data\[].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 |
| data\[].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` |
| data\[].encrypted\_data.address\_verification.**name**
string
Conditionally returned | Name of the cardholder, as returned by the digital wallet provider.
**Allowable Values:**
255 char max |
| data\[].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 |
| data\[].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 |
| data\[].**card\_token**
string
Conditionally returned | Unique identifier of the card.
**Allowable Values:**
1–36 chars |
| data\[].**created\_time**
datetime
Conditionally returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
Format: yyyy-MM-ddThh:mm:ssZ |
| data\[].**fulfillment\_status**
string
Conditionally returned | Digital wallet token’s provisioning status.
**Allowable Values:**
`DECISION_GREEN`, `DECISION_RED`, `DECISION_YELLOW`, `PROVISIONED`, `REJECTED` |
| data\[].**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`
**Allowable Values:**
255 char max |
| data\[].**last\_modified\_time**
datetime
Conditionally returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
Format: yyyy-MM-ddThh:mm:ssZ |
| data\[].**state**
string
Conditionally returned | Current state of the digital wallet token.
**Allowable Values:**
1–255 chars |
| data\[].**state\_reason**
string
Conditionally returned | Descriptive reason for the current state of the digital wallet token.
**Allowable Values:**
255 char max |
| data\[].**token**
string
Conditionally returned | Unique identifier for the digital wallet token on the Marqeta platform.
**Allowable Values:**
1–36 chars |
| data\[].**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`, `pan_source`, `reason_code`, `risk_assessment` |
| data\[].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` |
| data\[].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 |
| data\[].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:**
Any value |
| data\[].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 |
| data\[].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` |
| data\[].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` |
| data\[].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:**
Any value |
| data\[].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:**
Any value |
| data\[].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:**
`KEY_ENTERED`, `MOBILE_BANKING_APP`, `ON_FILE` |
| data\[].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 |
Retrieve digital wallet token
**Action:** `GET`\
**Endpoint:** `/digitalwallettokens/{token}`
{/* */}
Use the `/digitalwallettokens/{token}` endpoint to retrieve a specific digital wallet token.
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:**
Any value |
| encrypted\_data.token\_service\_provider.**token\_expiration**
MMyy
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`, `WATCH`, `VEHICLE`, `UNKNOWN`, `UNRECOGNIZED` |
| 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:**
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`
**Allowable Values:**
255 char max |
| last\_modified\_time
datetime
Conditionally returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
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`, `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:**
Any value |
| 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:**
Any value |
| 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:**
Any value |
| 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:**
`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 JSON expandable lines wrap theme={null}
{
"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"
}
}
```
List digital wallet tokens by card
**Action:** `GET`\
**Endpoint:** `/digitalwallettokens/card/{card_token}`
{/* */}
Use the `digitalwallettokens/card/{card_token}` endpoint to retrieve a list of digital wallet tokens for the specified card.
URL path parameters
| Fields | Description |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| card\_token
string
Required | Token that identifies the card and correlates it with the card issuer. This token is used to minimize the need to exchange card details during subsequent API calls, and also for troubleshooting. Use a globally unique identifier (GUID) or a pseudo-unique identifier for this token.
**Allowable Values:**
Existing card token |
URL query parameters
| Fields | Description |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count
integer
Optional | Number of resources to retrieve.
**Allowable Values:**
Any integer |
| start\_index
integer
Optional | Sort order index of the first resource to retrieve.
**Allowable Values:**
Any integer |
| sort\_by
string
Optional | Field on which to sort. Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`. Prefix the field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order.
**Allowable Values:**
`createdTime`, `lastModifiedTime`, or any field in the resource model
**Default Values:**`-createdTime` |
Response body
| Fields | Description |
| ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count
integer
Returned | Number of resources returned.
This field is returned if there are resources in your returned array.
**Allowable Values:**
Any integer |
| start\_index
integer
Returned | Sort order index of the first resource in the returned array.
This field is returned if there are resources in your returned array.
**Allowable Values:**
Any integer |
| end\_index
integer
Returned | Sort order index of the last resource in the returned array.
This field is returned if there are resources in your returned array.
**Allowable Values:**
Any integer |
| is\_more
boolean
Conditionally returned | A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that no more unreturned resources exist.
This field is returned if there are resources in your returned array.
**Allowable Values:**
`true`, `false` |
| data
array of undefineds
Conditionally returned | Array of digital wallet token objects.
**Allowable Values:**
Valid data array of one or more digital wallet token objects.
Objects are returned as appropriate to your query. |
| data\[].**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` |
| data\[].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` |
| data\[].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 |
| data\[].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 |
| data\[].encrypted\_data.token\_service\_provider.**correlation\_id**
string
Conditionally returned | Unique value representing a tokenization request (Mastercard only).
**Allowable Values:**
14 char max |
| data\[].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 |
| data\[].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 |
| data\[].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` |
| data\[].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 |
| data\[].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:**
Any value |
| data\[].encrypted\_data.token\_service\_provider.**token\_expiration**
MMyy
Conditionally returned | Expiration of the digital wallet token.
**Allowable Values:**
Format: MMyy |
| data\[].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 |
| data\[].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 |
| data\[].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` |
| data\[].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`, `WATCH`, `VEHICLE`, `UNKNOWN`, `UNRECOGNIZED` |
| data\[].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 |
| data\[].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 |
| data\[].encrypted\_data.device.**name**
string
Conditionally returned | Name of the device, as returned by the digital wallet provider.
**Allowable Values:**
128 char max |
| data\[].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 |
| data\[].encrypted\_data.device.**ip\_address**
string
Conditionally returned | IPv4 address, as returned by the digital wallet provider.
**Allowable Values:**
25 char max |
| data\[].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 |
| data\[].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` |
| data\[].encrypted\_data.address\_verification.**name**
string
Conditionally returned | Name of the cardholder, as returned by the digital wallet provider.
**Allowable Values:**
255 char max |
| data\[].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 |
| data\[].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 |
| data\[].**card\_token**
string
Conditionally returned | Unique identifier of the card.
**Allowable Values:**
1–36 chars |
| data\[].**created\_time**
datetime
Conditionally returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
Format: yyyy-MM-ddThh:mm:ssZ |
| data\[].**fulfillment\_status**
string
Conditionally returned | Digital wallet token’s provisioning status.
**Allowable Values:**
`DECISION_GREEN`, `DECISION_RED`, `DECISION_YELLOW`, `PROVISIONED`, `REJECTED` |
| data\[].**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`
**Allowable Values:**
255 char max |
| data\[].**last\_modified\_time**
datetime
Conditionally returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
Format: yyyy-MM-ddThh:mm:ssZ |
| data\[].**state**
string
Conditionally returned | Current state of the digital wallet token.
**Allowable Values:**
1–255 chars |
| data\[].**state\_reason**
string
Conditionally returned | Descriptive reason for the current state of the digital wallet token.
**Allowable Values:**
255 char max |
| data\[].**token**
string
Conditionally returned | Unique identifier for the digital wallet token on the Marqeta platform.
**Allowable Values:**
1–36 chars |
| data\[].**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`, `pan_source`, `reason_code`, `risk_assessment` |
| data\[].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` |
| data\[].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 |
| data\[].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:**
Any value |
| data\[].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 |
| data\[].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` |
| data\[].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` |
| data\[].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:**
Any value |
| data\[].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:**
Any value |
| data\[].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:**
`KEY_ENTERED`, `MOBILE_BANKING_APP`, `ON_FILE` |
| data\[].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 |
Retrieve digital wallet token with PAN visible
**Action:** `GET`\
**Endpoint:** `/digitalwallettokens/{token}/showtokenpan`
{/* */}
Use the `/digitalwallettokens/{token}/showtokenpan` endpoint to retrieve a digital wallet token with the entire primary account number (PAN) displayed. The PAN returned is of the digital wallet token, and not of the card. For security reasons, the PAN is not fully visible on the digital wallet token returned by `GET /digitalwallettokens/{token}`.
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:**
Any value |
| encrypted\_data.token\_service\_provider.**token\_expiration**
MMyy
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`, `WATCH`, `VEHICLE`, `UNKNOWN`, `UNRECOGNIZED` |
| 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:**
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`
**Allowable Values:**
255 char max |
| last\_modified\_time
datetime
Conditionally returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
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`, `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:**
Any value |
| 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:**
Any value |
| 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:**
Any value |
| 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:**
`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 JSON expandable lines wrap theme={null}
{
"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"
}
}
```
Create digital wallet token transition
**Action:** `POST`\
**Endpoint:** `/digitalwallettokentransitions`
{/* */}
Use the `/digitalwallettokentransitions` endpoint to transition a digital wallet token from one state to another.
Request body
| Fields | Description |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token
string
Optional | Unique identifier of the digital wallet token transition, and not the identifier of the digital wallet token itself. If you do not include a value for the token field, the system will generate one automatically. This value is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.
**Allowable Values:**
1–36 chars |
| reason\_code
string
Required | Code describing the reason for the transition. Marqeta does not validate what is provided, although Marqeta-sourced changes use standard codes.
**Allowable Values:**
1–255 chars |
| token\_reference\_id
string
Optional | Unique identifier of the digital wallet token within the card network. `token_reference_id` is unique at the card network level. This is the primary identifier for Visa.
**Allowable Values:**
1–255 chars |
| channel
string
Required | Mechanism by which the transition was initiated. `API`, for example.
**Allowable Values:**
`ADMIN`, `API`, `DIGITAL_WALLET`, `FRAUD`, `IVR`, `MARQETA_DASHBOARD`, `SYSTEM`, `TOKEN_SERVICE_PROVIDER` |
| state
string
Required | Specifies the state to which the digital wallet token transitions.
**Allowable Values:**
`ACTIVE`, `REQUESTED`, `REQUEST_DECLINED`, `SUSPENDED`, `TERMINATED` |
| digital\_wallet\_token
object
Required | Hashed version of Marqeta’s unique identifier for the digital wallet tokens.
**Allowable Values:**
`token` |
| digital\_wallet\_token.**token**
string
Required | Marqeta’s unique identifier for the digital wallet token.
**Allowable Values:**
1–36 chars |
| reason
string
Optional | Descriptive reason for the transition.
**Allowable Values:**
255 char max |
Sample request body
```json JSON lines wrap theme={null}
{
"state": "ACTIVE",
"reason_code": "01",
"reason": "Customer Request",
"digital_wallet_token": {
"token": "my_digital_wallet_token_01"
},
"channel": "API"
}
```
Response body
| Fields | Description |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token
string
Returned | Unique identifier for the digital wallet token transition.
**Allowable Values:**
1–36 chars |
| digital\_wallet\_token
object
Returned | Hashed version of Marqeta’s unique identifier for the digital wallet tokens.
**Allowable Values:**
`token` |
| digital\_wallet\_token.**token**
string
Returned | Marqeta’s unique identifier for the digital wallet token.
**Allowable Values:**
1–36 chars |
| type
string
Returned | Type of digital wallet token transition. `state.activated`, for example.
**Allowable Values:**
`card.swap`, `state.activated`, `state.reinstated`, `state.suspended`, `state.terminated` |
| channel
string
Returned | Mechanism by which the transition was initiated.
**Allowable Values:**
`API` |
| state
string
Returned | Specifies the state to which the digital wallet token transitions.
**Allowable Values:**
`ACTIVE`, `SUSPENDED`, `TERMINATED` |
| fulfillment\_status
string
Returned | Digital wallet token’s provisioning status.
**Allowable Values:**
`DECISION_GREEN`, `DECISION_RED`, `DECISION_YELLOW`, `PROVISIONED`, `REJECTED` |
| reason
string
Conditionally returned | Descriptive reason for the transition.
**Allowable Values:**
255 char max |
| reason\_code
string
Returned | Code describing the reason for the transition. Marqeta does not validate what is provided, although Marqeta-sourced changes use standard codes.
**Allowable Values:**
1–255 chars |
| created\_time
datetime
Returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
Format: yyyy-MM-ddThh:mm:ssZ |
Sample response body
```json JSON lines wrap theme={null}
{
"token": "my_dwt_transition_01",
"digital_wallet_token": {
"token": "my_digital_wallet_token_01"
},
"type": "state.activated",
"channel": "API",
"state": "ACTIVE",
"fulfillment_status": "PROVISIONED",
"reason": "Customer Request",
"reason_code": "01",
"created_time": "2022-09-10T06:30:20Z"
}
```
List digital wallet token transitions
**Action:** `GET`\
**Endpoint:** `/digitalwallettokentransitions/digitalwallettoken/{token}`
{/* */}
Use the `/digitalwallettokentransitions/digitalwallettoken/{token}` endpoint to return an array of all transitions for a particular digital wallet token.
This endpoint supports [field filtering](/core-api/field-filtering/), [pagination](/core-api/sorting-and-pagination/), and [sorting](/core-api/sorting-and-pagination/).
URL path parameters
| Fields | Description |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| token
string
Required | Unique identifier of the digital wallet token transition.
**Allowable Values:**
Existing digital wallet token transition token |
URL query parameters
| Fields | Description |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count
integer
Optional | Number of resources to retrieve.
**Allowable Values:**
Any integer |
| start\_index
integer
Optional | Sort order index of the first resource to retrieve.
**Allowable Values:**
Any integer |
| sort\_by
string
Optional | Field on which to sort. Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`. Prefix the field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order.
**Allowable Values:**
`createdTime`, `lastModifiedTime`, or any field in the resource model
**Default value:**`id` |
| fields
string
Optional | Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields.
**Allowable Values:**
Comma-delimited list of fields, or blank |
Response body
| Fields | Description |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| count
integer
Returned | Number of resources returned.
This field is returned if there are resources in your returned array.
**Allowable Values:**
Any integer |
| start\_index
integer
Returned | Sort order index of the first resource in the returned array.
This field is returned if there are resources in your returned array.
**Allowable Values:**
Any integer |
| end\_index
integer
Returned | Sort order index of the last resource in the returned array.
This field is returned if there are resources in your returned array.
**Allowable Values:**
Any integer |
| is\_more
boolean
Conditionally returned | A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that no more unreturned resources exist.
This field is returned if there are resources in your returned array.
**Allowable Values:**
`true`, `false` |
| data
array of objects
Conditionally returned | Array of digital wallet token transition objects.
Objects are returned as appropriate to your query.
**Allowable Values:**
Valid array of one or more digital wallet token transition objects |
| data\[].**token**
string
Returned | Unique identifier of the digital wallet token transition, and not the identifier of the digital wallet token itself.
**Allowable Values:**
1–36 chars |
| data\[].**digital\_wallet\_token**
object
Returned | Hashed version of Marqeta’s unique identifier for the digital wallet tokens.
**Allowable Values:**
`token` |
| data\[].digital\_wallet\_token.**token**
string
Returned | Marqeta’s unique identifier for the digital wallet token.
**Allowable Values:**
1–36 chars |
| data\[].**card\_swap**
object
Conditionally returned | Hashed version of the `card_swap` object. Specifies the old and new payment card tokens that were swapped.
**Allowable Values:**
`newCardToken`, `previousCardToken` |
| data\[].card\_swap.**previousCardToken**
string
Returned | Unique identifier of the old card from which the digital wallet tokens are transferred.
**Allowable Values:**
1–36 chars |
| data\[].card\_swap.**newCardToken**
string
Returned | Unique identifier of the new card to which the digital wallet tokens are transferred.
**Allowable Values:**
1–36 chars |
| data\[].**type**
string
Returned | Type of digital wallet token transition. `state.activated`, for example.
**Allowable Values:**
`card.swap`, `fulfillment.requested`, `state.activated`, `state.reinstated`, `state.request_declined`, `state.suspended`, `state.terminated` |
| data\[].**channel**
string
Returned | Mechanism by which the transition was initiated. `API`, for example.
**Allowable Values:**
`ADMIN`, `API`, `DIGITAL_WALLET`, `FRAUD`, `IVR`, `MARQETA_DASHBOARD`, `SYSTEM`, `TOKEN_SERVICE_PROVIDER` |
| data\[].**state**
string
Returned | Specifies the state to which to transition the digital wallet token.
**Allowable Values:**
`ACTIVE`, `REQUESTED`, `REQUEST_DECLINED`, `SUSPENDED`, `TERMINATED` |
| data\[].**fulfillment\_status**
string
Returned | Digital wallet token’s provisioning status.
**Allowable Values:**
`DECISION_GREEN`, `DECISION_RED`, `DECISION_YELLOW`, `PROVISIONED`, `REJECTED` |
| data\[].**reason**
string
Conditionally returned | Descriptive reason for the transition.
**Allowable Values:**
255 char max |
| data\[].**reason\_code**
string
Returned | Code describing the reason for the transition. Marqeta does not validate what is provided, although Marqeta-sourced changes use standard codes.
**Allowable Values:**
1–255 chars |
| data\[].**created\_time**
datetime
Returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
Format: yyyy-MM-ddThh:mm:ssZ |
Retrieve digital wallet token transition
**Action:** `GET`\
**Endpoint:** `/digitalwallettokentransitions/{token}`
{/* */}
Use the `/digitalwallettokentransitions/{token}` endpoint to retrieve a specific digital wallet transition.
URL path parameters
| Fields | Description |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| token
string
Required | Unique identifier of the digital wallet token transition.
**Allowable Values:**
Existing digital wallet token transition token |
URL query parameters
| Fields | Description |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fields
string
Optional | Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields.
**Allowable Values:**
Comma-delimited list of fields, or blank |
Response body
| Fields | Description |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token
string
Returned | Unique identifier of the digital wallet token transition, and not the identifier of the digital wallet token itself.
**Allowable Values:**
1–36 chars |
| digital\_wallet\_token
object
Returned | Hashed version of Marqeta’s unique identifier for the digital wallet tokens.
**Allowable Values:**
`token` |
| digital\_wallet\_token.**token**
string
Returned | Marqeta’s unique identifier for the digital wallet token.
**Allowable Values:**
1–36 chars |
| card\_swap
object
Conditionally returned | Hashed version of the `card_swap` object. Specifies the old and new payment card tokens that were swapped.
**Allowable Values:**
`newCardToken`, `previousCardToken` |
| card\_swap.**previousCardToken**
string
Returned | Unique identifier of the old card from which the digital wallet tokens are transferred.
**Allowable Values:**
1–36 chars |
| card\_swap.**newCardToken**
string
Returned | Unique identifier of the new card to which the digital wallet tokens are transferred.
**Allowable Values:**
1–36 chars |
| type
string
Returned | Type of digital wallet token transition. `state.activated`, for example.
**Allowable Values:**
`card.swap`, `fulfillment.requested`, `state.activated`, `state.reinstated`, `state.request_declined`, `state.suspended`, `state.terminated` |
| channel
string
Returned | Mechanism by which the transition was initiated. `API`, for example.
**Allowable Values:**
`ADMIN`, `API`, `DIGITAL_WALLET`, `FRAUD`, `IVR`, `MARQETA_DASHBOARD`, `SYSTEM`, `TOKEN_SERVICE_PROVIDER` |
| state
string
Returned | Specifies the state to which to transition the digital wallet token.
**Allowable Values:**
`ACTIVE`, `REQUESTED`, `REQUEST_DECLINED`, `SUSPENDED`, `TERMINATED` |
| fulfillment\_status
string
Returned | Digital wallet token’s provisioning status.
**Allowable Values:**
`DECISION_GREEN`, `DECISION_RED`, `DECISION_YELLOW`, `PROVISIONED`, `REJECTED` |
| reason
string
Conditionally returned | Descriptive reason for the transition.
**Allowable Values:**
255 char max |
| reason\_code
string
Returned | Code describing the reason for the transition. Marqeta does not validate what is provided, although Marqeta-sourced changes use standard codes.
**Allowable Values:**
1–255 chars |
| created\_time
datetime
Returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
Format: yyyy-MM-ddThh:mm:ssZ |
Sample response body
```json JSON lines wrap theme={null}
{
"token": "bb50c999-9c4e-3f99-90a0-a12ab30fe81b",
"digital_wallet_token": {
"token": "c45c201-ad5e-3f23-76a0-a08cb36fa90a"
},
"type": "fulfillment.requested",
"channel": "TOKEN_SERVICE_PROVIDER",
"state": "REQUESTED",
"fulfillment_status": "DECISION_GREEN",
"reason": "Token creation",
"reason_code": "21",
"created_time": "2022-09-06T22:52:13Z"
}
```
```json JSON lines wrap theme={null}
{
"token": "cb40c400-ba4f-3f97-80b0-c09ab30fe63d",
"digital_wallet_token": {
"token": "cb45c201-ad5e-3f23-76a0-a08cb36fa90a"
},
"card_swap": {
"previousCardToken": "card-token-1",
"newCardToken": "card-token-2"
},
"type": "card.swap",
"channel": "SYSTEM",
"state": "ACTIVE",
"fulfillment_status": "PROVISIONED",
"reason": "New card",
"reason_code": "14",
"created_time": "2022-09-10T06:29:30Z"
}
```
Update expiry dates
**Action:** `PUT`\
**Endpoint:** `/cardactions/updateexpiration`
{/* */}
Use the `/cardactions/updateexpiration` endpoint to update the expiry dates of a digital wallet token.
Request body
| Fields | Description |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| encrypted\_card\_data
object
Required | Specifies details for updating digital wallet token expiration dates.
**Allowable Values:**
`new_card_token`, `new_pan_expiry`, `old_card_token`, `old_pan_expiry`, `primary_account_number` |
| encrypted\_card\_data.**primary\_account\_number**
string
Required | Account number of the card being tokenized.
**Allowable Values:**
12–19 chars |
| encrypted\_card\_data.**old\_card\_token**
string
Required | Unique identifier of the card.
**Allowable Values:**
1–36 chars |
| encrypted\_card\_data.**old\_pan\_expiry**
object
Required | Specifies the expiry date for the card.
**Allowable Values:**
`month`, `year` |
| encrypted\_card\_data.old\_pan\_expiry.**month**
MM
Required | Specifies the expiry month for the card in MM format. `01`, for example.
**Allowable Values:**
Format: MM |
| encrypted\_card\_data.old\_pan\_expiry.**year**
yyyy
Required | Specifies the expiry year for the card in yyyy format. `2024`, for example.
**Allowable Values:**
Format: yyyy |
| encrypted\_card\_data.**new\_card\_token**
string
Required | Unique identifier of the card.
**Allowable Values:**
1–36 chars |
| encrypted\_card\_data.**new\_pan\_expiry**
object
Required | Specifies the expiry date for the card.
**Allowable Values:**
`month`, `year` |
| encrypted\_card\_data.new\_pan\_expiry.**month**
MM
Required | Specifies the expiry month for the card in MM format. `01`, for example.
**Allowable Values:**
Format: MM |
| encrypted\_card\_data.new\_pan\_expiry.**year**
yyyy
Required | Specifies the expiry year for the card in yyyy format. `2024`, for example.
**Allowable Values:**
Format: yyyy |
Response body
| Fields | Description |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| success
boolean
Conditionally returned | Indicates success if `true`, failure if `false`.
**Allowable Values:**
`true`, `false` |
Transfer digital wallet tokens
**Action:** `PUT`\
**Endpoint:** `/cardactions/cardswap`
{/* */}
Use the `/cardactions/cardswap` endpoint to transfer digital wallet tokens to a new card with a different primary account number (PAN).
Request body
| Fields | Description |
| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| encrypted\_card\_data
object
Required | Contains details about the cards to be swapped.
**Allowable Values:**
`new_card_token`, `new_pan_expiry`, `new_primary_account_number`, `old_card_token`, `old_pan_expiry`, `old_primary_account_number` |
| encrypted\_card\_data.**old\_primary\_account\_number**
string
Required | Primary account number for the existing payment card from which the digital wallet tokens are transferred.
**Allowable Values:**
12–19 chars |
| encrypted\_card\_data.**old\_pan\_expiry**
object
Required | Specifies the expiry date for the card.
**Allowable Values:**
`month`, `year` |
| encrypted\_card\_data.old\_pan\_expiry.**month**
MM
Required | Specifies the expiry month for the card in MM format. `01`, for example.
**Allowable Values:**
Format: MM |
| encrypted\_card\_data.old\_pan\_expiry.**year**
yyyy
Required | Specifies the expiry year for the card in yyyy format. `2024`, for example.
**Allowable Values:**
Format: yyyy |
| encrypted\_card\_data.**old\_card\_token**
string
Required | Unique identifier of the card.
**Allowable Values:**
1–36 chars |
| encrypted\_card\_data.**new\_primary\_account\_number**
string
Required | Primary account number of the new card to which the digital wallet token are transferred.
**Allowable Values:**
12–19 chars |
| encrypted\_card\_data.**new\_pan\_expiry**
object
Required | Specifies the expiry date for the card.
**Allowable Values:**
`month`, `year` |
| encrypted\_card\_data.new\_pan\_expiry.**month**
MM
Required | Specifies the expiry month for the card in MM format. `01`, for example.
**Allowable Values:**
Format: MM |
| encrypted\_card\_data.new\_pan\_expiry.**year**
yyyy
Required | Specifies the expiry year for the card in yyyy format. `2024`, for example.
**Allowable Values:**
Format: yyyy |
| encrypted\_card\_data.**new\_card\_token**
string
Required | Unique identifier of the new payment card token to which the digital wallet tokens are transferred.
**Allowable Values:**
1–36 chars |
Response body
| Fields | Description |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| success
boolean
Conditionally returned | Indicates success if `true`, failure if `false`.
**Allowable Values:**
`true`, `false` |
Create webhooks
**Action:** `POST`\
**Endpoint:** `/webhooks/{event_type}`
{/* */}
Use the `/webhooks/{event_type}` endpoint to send a batch of events to a webhook.
URL path parameters
| Fields | Description |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| event\_type
string
Required | Digital wallet token event type.
**Allowable Values:**
`digitalwallettoken`, `digitalwallettokentransition` |
Sample request body
Digital Wallet Token Webhooks
```json JSON expandable lines wrap theme={null}
{
"digitalwallettokens": [
{
"token": "my_webhook_event_01",
"event_type": "digitalwallettoken.provisioningrequest",
"webhook_details": {
"token": "my_provisioning_request_01",
"card_token": "my_card_01",
"state": "REQUEST_DECLINED",
"fulfillment_status": "REJECTED",
"issuer_eligibility_decision": "avs.decline",
"created_time": "2022-09-11T00:20:23Z",
"last_modified_time": "2022-09-11T00:20:23Z",
"encrypted_data": {
"card_data": {
"primary_account_number": "41111199999",
"expiration_date": {
"month": "01",
"year": "2024"
}
},
"token_service_provider": {
"token_reference_id": "DNITHE343434343459",
"pan_reference_id": "V-123343434343434",
"token_requestor_id": "40010083275",
"token_requestor_name": "UNKNOWN",
"token_type": "MERCHANT_CARD_ON_FILE",
"token_eligibility_decision": "DECISION_GREEN"
},
"device": {
"language_code": "eng"
},
"address_verification": {
"street_address": "180 Grand Ave",
"zip": "94612"
}
},
"wallet_provider_profile": {
"account": {
"id": "40010083275",
"email_address": "A11AAAA1A011C11111111111A1AA111F...."
},
"risk_assessment": {},
"pan_source": "KEY_ENTERED"
}
}
}
]
}
```
Digital Wallet Token Transition Webhooks
```json JSON expandable lines wrap theme={null}
{
"digitalwallettokentransitions": [
{
"token": "my_webhook_event_02",
"event_type": "digitalWalletTokenTransition.requested",
"webhook_details": {
"token": "my_digital_wallet_token_transition_01",
"digital_wallet_token": {
"token": "my_digital_wallet_token_01"
},
"type": "fulfillment.requested",
"channel": "TOKEN_SERVICE_PROVIDER",
"state": "REQUESTED",
"fulfillment_status": "DECISION_GREEN",
"reason": "Token creation",
"reason_code": "21",
"created_time": "2022-09-06T22:52:13Z"
}
},
{
"token": "my_webhook_event_03",
"event_type": "digitalWalletTokenTransition.terminated",
"webhook_details": {
"token": "my_digital_wallet_transition_token_02",
"digital_wallet_token": {
"token": "my_digital_wallet_token_02"
},
"type": "fulfillment.requested",
"channel": "TOKEN_SERVICE_PROVIDER",
"state": "REQUESTED",
"fulfillment_status": "DECISION_GREEN",
"reason": "Token creation",
"reason_code": "21",
"created_time": "2022-09-06T22:52:13Z"
}
}
]
}
```
## Related topics
- [Digital Wallets and Tokenization](/docs/developer-guides/digital-wallets-and-tokenization.md)
- [Card Products in Europe](/docs/developer-guides/mq-eu-card-products.md)
- [Tokenization in Europe](/docs/developer-guides/mq-eu-tokenization.md)
- [Managing Tokenization Risk](/docs/developer-guides/mq-eu-managing-tokenization-risk.md)
- [Accessing Tokenization Implementation Guides](/docs/developer-guides/accessing-tokenization-implementation-guides.md)