> ## 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.
# Digital Wallets Management
> Use the digital wallet management endpoints to provision digital wallet tokens and manage their lifecycle.
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 token provisioning request for Apple Wallet
**Action:** `POST`\
**Endpoint:** `/digitalwalletprovisionrequests/applepay`
{/* */}
Use this 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.
| Fields | Description |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
Request body
| Fields | Description |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| card\_token
string
Required | Unique identifier of the card resource to use for the provisioning request.
**Allowable Values:**
1–36 chars |
| certificates
array of strings
Required | Base64-encoded leaf and sub-CA certificates provided by Apple.
The first element of the array should be the leaf certificate, followed by the sub-CA.
**Allowable Values:**
An array of one or more certificates provided by Apple |
| device\_type
string
Required | Type of device into which the digital wallet token will be provisioned.
**Allowable Values:**
`MOBILE_PHONE`, `WATCH`, `TABLET` |
| nonce
string
Required | One-time-use nonce provided by Apple for security purposes.
**Allowable Values:**
Base64-encoded nonce from Apple |
| nonce\_signature
string
Required | Apple-provided signature to the nonce.
**Allowable Values:**
Base64-encoded nonce signature from Apple |
| provisioning\_app\_version
string
Required | Version of the application making the provisioning request. Used for debugging and fraud prevention.
**Allowable Values:**
1–50 chars |
Sample request body
```json JSON lines wrap theme={null}
{
"card_token": "my_card_token_1234",
"device_type": "MOBILE_PHONE",
"provisioning_app_version": "2.13.7",
"certificates": [
"my_certificate_ZIzj...",
"my_certificate_SgMA..."
],
"nonce": "my_nonce_JJCF",
"nonce_signature": "my_nonce_signature_wbBn"
}
```
Response body
| Fields | Description |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| activation\_data
string
Returned | Cryptographic one-time passcode conforming to the payment network operator or service provider specifications.
**Allowable Values:**
Any value |
| card\_token
string
Returned | Unique identifier of the card resource to use for the provisioning request.
**Allowable Values:**
1–36 chars |
| created\_time
datetime
Returned | Date and time when the digital wallet provisioning request was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| encrypted\_pass\_data
string
Returned | Payload encrypted with a shared key derived from the Apple Public Certificates and the generated ephemeral private key.
**Allowable Values:**
Any value |
| ephemeral\_public\_key
string
Returned | Ephemeral public key used for the provisioning attempt.
**Allowable Values:**
Any value |
| last\_modified\_time
datetime
Returned | Date and time when the digital wallet token provisioning request was last updated, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
Sample response body
```json JSON lines wrap theme={null}
{
"created_time": "2025-03-22T21:22:19Z",
"last_modified_time": "2025-03-22T21:22:19Z",
"card_token": "my_card_token_1234",
"encrypted_pass_data": "my_encrypted_pass_data_KGga...",
"activation_data": "my_activation_data_VERF...",
"ephemeral_public_key": "my_ephemeral_public_key_omvw..."
}
```
Submit a post-tokenization authentication decision
**Action:** `POST`\
**Endpoint:** `/digitalwallets/postTokenizationAuthenticationDecision`
{/* */}
Use this endpoint to submit a post-tokenization authentication decision from the customer to Marqeta in a secure card on file scenario. Marqeta validates the request, stores it, and forwards the authentication decision to Mastercard MDES in real time. Marqeta then returns the MDES response back to the customer synchronously. This enables issuers to notify Mastercard Digital Enablement Service (MDES) of the cardholder’s authentication outcome following tokenization, ensuring that the token requestor receives timely and accurate decisioning.
Request body
| Fields | Description |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| tokenUniqueReference
string
Required | Unique identifier of the token allocated to the card.
**Allowable Values:**
1–64 chars |
| authRequestCorrelationId
string
Optional | Correlates multiple authentication requests.
**Allowable Values:**
1–64 chars |
| authenticationMethod
string
Required | Authentication method used to verify the cardholder.
**Allowable Values:**
`Issuer Application`, `Web Portal` |
| decision
string
Required | Issuer decision after cardholder authentication.
**Allowable Values:**
`SUCCESS`, `FAILED` |
| commentText
string
Optional | Optional comment related to the decision.
**Allowable Values:**
500 char max |
Response body
| Fields | Description |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| status
string
Returned | Indicates if the operation was successful.
**Allowable Values:**
`SUCCESS`, `FAILED` |
| message
string
Returned | Human-readable description of the outcome.
**Allowable Values:**
255 char max |
Create digital wallet token provisioning request for Google Wallet
**Action:** `POST`\
**Endpoint:** `/digitalwalletprovisionrequests/androidpay`
{/* */}
Use this 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.
Request body
| Fields | Description |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| card\_token
string
Required | Unique identifier of the card resource to use for the provisioning request.
**Allowable Values:**
1–36 chars |
| device\_id
string
Required | Unique identifier of the user’s Google device, as provided by Google during the provisioning process.
**Allowable Values:**
1–24 chars |
| device\_type
string
Required | Type of device into which the digital wallet token will be provisioned.
**Allowable Values:**
`MOBILE_PHONE`, `TABLET`, `WATCH` |
| provisioning\_app\_version
string
Required | Version of the application making the provisioning request. Used for debugging and fraud prevention.
**Allowable Values:**
1–50 chars |
| wallet\_account\_id
string
Required | User’s Google Wallet account ID, as provided by Google during the provisioning process.
**Allowable Values:**
1–50 chars |
Sample request body
```json JSON lines wrap theme={null}
{
"card_token": "my_card_token_0987",
"device_type": "MOBILE_PHONE",
"provisioning_app_version": "2.13.3",
"wallet_account_id": "my_wallet_account_id_sr51",
"device_id": "my_device_id_r51j"
}
```
Response body
| Fields | Description |
| -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| card\_token
string
Returned | Unique identifier of the card resource to use for the provisioning request.
**Allowable Values:**
1–36 chars |
| created\_time
datetime
Returned | Date and time when the digital wallet provisioning request was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| last\_modified\_time
datetime
Returned | Date and time when the digital wallet token provisioning request was last updated, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| push\_tokenize\_request\_data
object
Returned | Contains details about a card tokenization push request.
**Allowable Values:**
`card_type`, `display_name`, `opaque_payment_card`, `last_digits`, `network`, `token_service_provider` |
| push\_tokenize\_request\_data.**display\_name**
string
Conditionally 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:**
Any value |
| push\_tokenize\_request\_data.**opaque\_payment\_card**
string
Conditionally returned | Encrypted data field created by the issuer and passed to Google Wallet during the push provisioning process.
**Allowable Values:**
Any value |
| push\_tokenize\_request\_data.**last\_digits**
string
Conditionally returned | Last four digits of the primary account number of the physical or virtual card.
**Allowable Values:**
4 chars |
| push\_tokenize\_request\_data.**network**
string
Conditionally returned | Specifies the card network of the physical or virtual card.
**Allowable Values:**
`Visa`, `Mastercard` |
| push\_tokenize\_request\_data.**token\_service\_provider**
string
Conditionally returned | Specifies the network that provides the digital wallet token service.
**Allowable Values:**
`TOKEN_PROVIDER_VISA`, `TOKEN_PROVIDER_MASTERCARD` |
| push\_tokenize\_request\_data.**user\_address**
object
Conditionally returned | Specifies the cardholder address.
**Allowable Values:**
`name`, `address1`, `address2`, `city`, `state`, `postal_code`, `country`, `phone` |
| push\_tokenize\_request\_data.user\_address.**name**
string
Returned | Name of the cardholder.
**Allowable Values:**
Any value |
| push\_tokenize\_request\_data.user\_address.**address1**
string
Returned | Street address of the cardholder.
**Allowable Values:**
Any value |
| push\_tokenize\_request\_data.user\_address.**address2**
string
Returned | Additional address information for the cardholder, such as a suite or apartment number.
`Suite 600`, for example.
**Allowable Values:**
Any value |
| push\_tokenize\_request\_data.user\_address.**city**
string
Returned | City of the cardholder.
**Allowable Values:**
Any value |
| push\_tokenize\_request\_data.user\_address.**state**
string
Returned | Two-character state, provincial, or territorial abbreviation.
For the complete list, see Valid state, provincial, territorial, and federal abbreviations.
**Allowable Values:**
Any value |
| push\_tokenize\_request\_data.user\_address.**postal\_code**
string
Returned | Postal code of the cardholder, such as a United States ZIP code. `94612`, for example.
**Allowable Values:**
255 char max |
| push\_tokenize\_request\_data.user\_address.**country**
string
Returned | Two-character ISO alpha-2 country code. `US`, for example.
**Allowable Values:**
255 char max |
| push\_tokenize\_request\_data.user\_address.**phone**
string
Returned | Telephone number of the cardholder.
**Allowable Values:**
255 char max |
Sample response body
```json JSON expandable lines wrap theme={null}
{
"created_time": "2024-11-06T22:43:20Z",
"last_modified_time": "2024-11-06T22:43:20Z",
"card_token": "my_card_token_1111",
"push_tokenize_request_data": {
"display_name": "Visa Card",
"last_digits": "3264",
"network": "Visa",
"token_service_provider": "TOKEN_PROVIDER_VISA",
"opaque_payment_card": "my_opaque_payment_card_RUza...",
"user_address": {
"name": "John Doe",
"address1": "180 Grand Ave",
"address2": "Suite 500",
"city": "Oakland",
"state": "CA",
"postal_code": "94612",
"country": "US",
"phone": "5105551212"
}
}
}
```
Create digital wallet token provisioning request for Samsung Wallet
**Action:** `POST`\
**Endpoint:** `/digitalwalletprovisionrequests/samsungpay`
{/* */}
**Note**\
This endpoint is limited in availability. For more information, contact your Marqeta representative.
Use this 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 |
| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| card\_token
string
Required | Unique identifier of the card resource to use for the provisioning request.
**Allowable Values:**
1–36 chars |
| device\_id
string
Required | User’s Samsung device unique identifier, as provided by Samsung during the provisioning process.
**Allowable Values:**
1–24 chars |
| device\_type
string
Required | Type of device into which the digital wallet token will be provisioned.
**Allowable Values:**
`MOBILE_PHONE`, `TABLET`, `WATCH` |
| provisioning\_app\_version
string
Required | Version of the application making the provisioning request. Used for debugging and fraud prevention.
**Allowable Values:**
1–50 chars |
| wallet\_user\_id
string
Required | User’s Samsung Wallet account ID, as provided by Samsung during the provisioning process.
**Allowable Values:**
1–50 chars |
Response body
| Fields | Description |
| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| card\_token
string
Returned | Unique identifier of the card resource to use for the provisioning request.
**Allowable Values:**
1–36 chars |
| created\_time
datetime
Returned | Date and time when the digital wallet provisioning request was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| last\_modified\_time
datetime
Returned | Date and time when the digital wallet token provisioning request was last updated, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| push\_tokenize\_request\_data
object
Conditionally returned | Contains details about a card tokenization push request.
**Allowable Values:**
`card_type`, `display_name`, `extra_provision_payload`, `last_digits`, `network`, `token_service_provider` |
| push\_tokenize\_request\_data.**card\_type**
string
Conditionally returned | Specifies the type of card.
**Allowable Values:**
`PAYMENT`, `DEBIT`, `CREDIT`, `LOYALTY`, `GIFT` |
| push\_tokenize\_request\_data.**display\_name**
string
Conditionally 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:**
Any value |
| push\_tokenize\_request\_data.**extra\_provision\_payload**
string
Conditionally returned | Encrypted card or cardholder details.
**Allowable Values:**
Any value |
| push\_tokenize\_request\_data.**last\_digits**
string
Conditionally returned | Last four digits of the primary account number of the physical or virtual card.
**Allowable Values:**
4 chars |
| push\_tokenize\_request\_data.**network**
string
Conditionally returned | Specifies the card network of the physical or virtual card.
**Allowable Values:**
`Visa`, `Mastercard` |
| push\_tokenize\_request\_data.**token\_service\_provider**
string
Conditionally returned | Specifies the network that provides the digital wallet token service, as determined by the Samsung Wallet library.
**Allowable Values:**
`VI`, `MC` |
Create digital wallet token provisioning request for XPay
**Action:** `POST`\
**Endpoint:** `/digitalwalletprovisionrequests/xpay`
{/* */}
**Note**\
This endpoint is limited in availability. For more information, contact your Marqeta representative.
Use this endpoint to return card data for use in provisioning a digital wallet token into an XPay digital 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 |
| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| card\_token
string
Required | Unique identifier of the card resource to use for the provisioning request.
**Allowable Values:**
1–36 chars |
| device\_id
string
Required | Unique identifier of the user’s XPay device, as provided by XPay during the provisioning process.
**Allowable Values:**
1–24 chars |
| device\_type
string
Required | Type of device into which the digital wallet token will be provisioned.
**Allowable Values:**
`MOBILE_PHONE`, `TABLET`, `WATCH` |
| provisioning\_app\_version
string
Required | Version of the application making the provisioning request. Used for debugging and fraud prevention.
**Allowable Values:**
1–50 chars |
| token\_requestor\_id
string
Required | Unique numerical identifier of the digital wallet token requestor within the card network. These ID numbers map to `token_requestor_name` field values as follows:
**Mastercard**
- 50110030273 – `APPLE_PAY`
- 50120834693 – `ANDROID_PAY`
- 50139059239 – `SAMSUNG_PAY`
**Visa**
- 40010030273 – `APPLE_PAY`
- 40010075001 – `ANDROID_PAY`
- 40010043095 – `SAMSUNG_PAY`
- 40010075196 – `MICROSOFT_PAY`
- 40010075338 – `VISA_CHECKOUT`
- 40010075449 – `FACEBOOK`
- 40010075839 – `NETFLIX`
- 40010077056 – `FITBIT_PAY`
- 40010069887 – `GARMIN_PAY`
**Allowable Values:**
11 char max
**Example Values:**
- **Mastercard** – 50110030273, 50120834693, 50139059239
- **Visa** – 40010030273, 40010075001, 40010075338, 40010075449, 40010075839, 40010043095 |
| wallet\_account\_id
string
Required | User’s XPay account identifier, as provided by XPay during the provisioning process.
**Allowable Values:**
1–50 chars |
Response body
| Fields | Description |
| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| card\_token
string
Returned | Unique identifier of the card resource to use for the provisioning request.
**Allowable Values:**
1–36 chars |
| created\_time
datetime
Returned | Date and time when the digital wallet provisioning request was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| last\_modified\_time
datetime
Returned | Date and time when the digital wallet token provisioning request was last updated, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| push\_tokenize\_request\_data
object
Conditionally returned | Contains details about a card tokenization push request.
**Allowable Values:**
`card_type`, `display_name`, `extra_provision_payload`, `last_digits`, `network`, `token_service_provider` |
| push\_tokenize\_request\_data.**card\_type**
string
Conditionally returned | Specifies the type of card.
**Allowable Values:**
`PAYMENT`, `DEBIT`, `CREDIT`, `LOYALTY`, `GIFT` |
| push\_tokenize\_request\_data.**display\_name**
string
Conditionally 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:**
Any value |
| push\_tokenize\_request\_data.**extra\_provision\_payload**
string
Conditionally returned | Encrypted card or cardholder details.
**Allowable Values:**
Any value |
| push\_tokenize\_request\_data.**last\_digits**
string
Conditionally returned | Last four digits of the primary account number of the physical or virtual card.
**Allowable Values:**
4 chars |
| push\_tokenize\_request\_data.**network**
string
Conditionally returned | Specifies the card network of the physical or virtual card.
**Allowable Values:**
`Visa`, `Mastercard` |
| push\_tokenize\_request\_data.**token\_service\_provider**
string
Conditionally returned | Specifies the network that provides the digital wallet token service.
**Allowable Values:**
`TOKEN_PROVIDER_VISA`, `TOKEN_PROVIDER_MASTERCARD` |
Create digital wallet token transition
**Action:** `POST`\
**Endpoint:** `/digitalwallettokentransitions`
{/* */}
Use this endpoint to transition a digital wallet token from one state to another.
Request body
| Fields | Description |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| channel
string
Optional | Mechanism by which the transition was initiated.
**Allowable Values:**
`TOKEN_SERVICE_PROVIDER`, `TOKEN_SERVICE_PROVIDER_API`, `DIGITAL_WALLET`, `API`, `IVR`, `FRAUD`, `ADMIN`, `SYSTEM` |
| digital\_wallet\_token
object
Required | Contains identifiers of the digital wallet token resource and the card resource.
**Allowable Values:**
Unique identifiers of the digital wallet token resource and the card resource |
| digital\_wallet\_token.**token**
string
Required | Unique identifier of the digital wallet token resource.
**Allowable Values:**
1–36 chars |
| digital\_wallet\_token.**card\_token**
string
Optional | Unique identifier of the card resource to use for the provisioning request.
**Allowable Values:**
1–36 chars |
| reason
string
Optional | The reason for the transition.
**Allowable Values:**
255 char max |
| reason\_code
string
Optional | Standard code describing the reason for the transition.
**NOTE:** This field is required if your program uses v2 of the `user_card_state_version`, which is a program-specific configuration value that is managed by Marqeta and cannot be accessed via the API. To learn more about the `user_card_state_version` program configuration, contact your Marqeta representative.
- **00:** Object activated for the first time
- **01:** Requested by you
- **02:** Inactivity over time
- **03:** This address cannot accept mail or the addressee is unknown
- **04:** Negative account balance
- **05:** Account under review
- **06:** Suspicious activity was identified
- **07:** Activity outside the program parameters was identified
- **08:** Confirmed fraud was identified
- **09:** Matched with an Office of Foreign Assets Control list
- **10:** Card was reported lost
- **11:** Card information was cloned
- **12:** Account or card information was compromised
- **13:** Temporary status change while on hold/leave
- **14:** Initiated by Marqeta
- **15:** Initiated by issuer
- **16:** Card expired
- **17:** Failed KYC
- **18:** Changed to `ACTIVE` because information was properly validated
- **19:** Changed to `ACTIVE` because account activity was properly validated
- **20:** Change occurred prior to the normalization of reason codes
- **21:** Initiated by a third party, often a digital wallet provider
- **22:** PIN retry limit reached
- **23:** Card was reported stolen
- **24:** Address issue
- **25:** Name issue
- **26:** SSN issue
- **27:** DOB issue
- **28:** Email issue
- **29:** Phone issue
- **30:** Account/fulfillment mismatch
- **31:** Other reason
- **32:** Unblock request
- **86:** Notification of death
**Allowable Values:**
`00`, `01`, `02`, `03`, `04`, `05`, `06`, `07`, `08`, `09`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, `18`, `19`, `20`, `21`, `22`, `23`, `24`, `25`, `26`, `27`, `28`, `29`, `30`, `31`, `32`, `86` |
| state
string
Required | Specifies the state to which the digital wallet token will transition.
The original state is `REQUESTED`. You cannot modify the state if its current value is either `REQUEST_DECLINED` or `TERMINATED`.
**Allowable Values:**
`ACTIVE`, `SUSPENDED`, `TERMINATED` |
| token
string
Optional | The unique identifier of the digital wallet token transition (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 |
| token\_reference\_id
string
Optional | The unique identifier of the digital wallet token within the card network. The `token_reference_id` is unique at the card network level.
**Allowable Values:**
255 char max |
Sample request body
```json JSON lines wrap theme={null}
{
"token": "my_transition_04",
"digital_wallet_token": {
"token": "my_digital_wallet_token_0987"
},
"state": "ACTIVE",
"reason": "Passed additional identity verification",
"reason_code": "18"
}
```
Response body
| Fields | Description |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| card\_swap
object
Conditionally returned | Contains identifiers for swapping digital wallet tokens between cards.
**Allowable Values:**
`new_card_token`, `previous_card_token` |
| card\_swap.**new\_card\_token**
string
Returned | Unique identifier of the new card resource to which the digital wallet tokens are assigned.
**Allowable Values:**
1–36 chars |
| card\_swap.**previous\_card\_token**
string
Returned | Unique identifier of the existing card resource that has digital wallet tokens assigned to it.
**Allowable Values:**
1–36 chars |
| channel
string
Returned | Mechanism by which the transition was initiated.
**Allowable Values:**
`TOKEN_SERVICE_PROVIDER`, `DIGITAL_WALLET`, `API`, `IVR`, `FRAUD`, `ADMIN`, `SYSTEM`, `TOKEN_SERVICE_PROVIDER_API` |
| created\_time
datetime
Conditionally returned | Date and time when the transition was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| digital\_wallet\_token
object
Returned | Contains identifiers of the digital wallet token resource and the card resource.
**Allowable Values:**
Unique identifiers of the digital wallet token resource and the card resource |
| digital\_wallet\_token.**token**
string
Returned | Unique identifier of the digital wallet token resource.
**Allowable Values:**
1–36 chars |
| digital\_wallet\_token.**card\_token**
string
Conditionally returned | Unique identifier of the card resource to use for the provisioning request.
**Allowable Values:**
1–36 chars |
| fulfillment\_status
string
Returned | Provisioning status of the digital wallet token.
**Allowable Values:**
`DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN`, `REJECTED`, `PROVISIONED` |
| reason
string
Conditionally returned | Reason for the transition.
**Allowable Values:**
255 char max |
| reason\_code
string
Conditionally returned | Standard code describing the reason for the transition:
- **00:** Object activated for the first time
- **01:** Requested by you
- **02:** Inactivity over time
- **03:** This address cannot accept mail or the addressee is unknown
- **04:** Negative account balance
- **05:** Account under review
- **06:** Suspicious activity was identified
- **07:** Activity outside the program parameters was identified
- **08:** Confirmed fraud was identified
- **09:** Matched with an Office of Foreign Assets Control list
- **10:** Card was reported lost
- **11:** Card information was cloned
- **12:** Account or card information was compromised
- **13:** Temporary status change while on hold/leave
- **14:** Initiated by Marqeta
- **15:** Initiated by issuer
- **16:** Card expired
- **17:** Failed KYC
- **18:** Changed to `ACTIVE` because information was properly validated
- **19:** Changed to `ACTIVE` because account activity was properly validated
- **20:** Change occurred prior to the normalization of reason codes
- **21:** Initiated by a third party, often a digital wallet provider
- **22:** PIN retry limit reached
- **23:** Card was reported stolen
- **24:** Address issue
- **25:** Name issue
- **26:** SSN issue
- **27:** DOB issue
- **28:** Email issue
- **29:** Phone issue
- **30:** Account/fulfillment mismatch
- **31:** Other reason
- **32:** Unblock request
- **86:** Notification of death
**Allowable Values:**
`00`, `01`, `02`, `03`, `04`, `05`, `06`, `07`, `08`, `09`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, `18`, `19`, `20`, `21`, `22`, `23`, `24`, `25`, `26`, `27`, `28`, `29`, `30`, `31`, `32`, `86` |
| state
string
Returned | Specifies the state to which the digital wallet token is transitioning.
**Allowable Values:**
`REQUESTED`, `REQUEST_DECLINED`, `ACTIVE`, `SUSPENDED`, `TERMINATED` |
| 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 |
| type
string
Returned | Type of digital wallet token transition. `state.activated`, for example.
**Allowable Values:**
36 char max |
Sample response body
```json JSON lines wrap theme={null}
{
"token": "my_transition_04",
"digital_wallet_token": {
"token": "my_digital_wallet_token_0987"
},
"type": "state.activated",
"channel": "API",
"state": "ACTIVE",
"fulfillment_status": "PROVISIONED",
"reason": "Passed additional identity verification",
"reason_code": "18",
"created_time": "2025-02-23T18:57:45Z"
}
```
Retrieve digital wallet token transition
**Action:** `GET`\
**Endpoint:** `/digitalwallettokentransitions/{token}`
{/* */}
Use this endpoint to retrieve a specific digital wallet token transition.
This endpoint supports [field filtering](/core-api/field-filtering/).
URL path parameters
| Fields | Description |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| token
string
Required | Unique identifier of the digital wallet token (DWT) transition.
**Allowable Values:**
Existing DWT 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 |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| card\_swap
object
Conditionally returned | Contains identifiers for swapping digital wallet tokens between cards.
**Allowable Values:**
`new_card_token`, `previous_card_token` |
| card\_swap.**new\_card\_token**
string
Returned | Unique identifier of the new card resource to which the digital wallet tokens are assigned.
**Allowable Values:**
1–36 chars |
| card\_swap.**previous\_card\_token**
string
Returned | Unique identifier of the existing card resource that has digital wallet tokens assigned to it.
**Allowable Values:**
1–36 chars |
| channel
string
Returned | Mechanism by which the transition was initiated.
**Allowable Values:**
`TOKEN_SERVICE_PROVIDER`, `DIGITAL_WALLET`, `API`, `IVR`, `FRAUD`, `ADMIN`, `SYSTEM`, `TOKEN_SERVICE_PROVIDER_API` |
| created\_time
datetime
Conditionally returned | Date and time when the transition was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| digital\_wallet\_token
object
Returned | Contains identifiers of the digital wallet token resource and the card resource.
**Allowable Values:**
Unique identifiers of the digital wallet token resource and the card resource |
| digital\_wallet\_token.**token**
string
Returned | Unique identifier of the digital wallet token resource.
**Allowable Values:**
1–36 chars |
| digital\_wallet\_token.**card\_token**
string
Conditionally returned | Unique identifier of the card resource to use for the provisioning request.
**Allowable Values:**
1–36 chars |
| fulfillment\_status
string
Returned | Provisioning status of the digital wallet token.
**Allowable Values:**
`DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN`, `REJECTED`, `PROVISIONED` |
| reason
string
Conditionally returned | Reason for the transition.
**Allowable Values:**
255 char max |
| reason\_code
string
Conditionally returned | Standard code describing the reason for the transition:
- **00:** Object activated for the first time
- **01:** Requested by you
- **02:** Inactivity over time
- **03:** This address cannot accept mail or the addressee is unknown
- **04:** Negative account balance
- **05:** Account under review
- **06:** Suspicious activity was identified
- **07:** Activity outside the program parameters was identified
- **08:** Confirmed fraud was identified
- **09:** Matched with an Office of Foreign Assets Control list
- **10:** Card was reported lost
- **11:** Card information was cloned
- **12:** Account or card information was compromised
- **13:** Temporary status change while on hold/leave
- **14:** Initiated by Marqeta
- **15:** Initiated by issuer
- **16:** Card expired
- **17:** Failed KYC
- **18:** Changed to `ACTIVE` because information was properly validated
- **19:** Changed to `ACTIVE` because account activity was properly validated
- **20:** Change occurred prior to the normalization of reason codes
- **21:** Initiated by a third party, often a digital wallet provider
- **22:** PIN retry limit reached
- **23:** Card was reported stolen
- **24:** Address issue
- **25:** Name issue
- **26:** SSN issue
- **27:** DOB issue
- **28:** Email issue
- **29:** Phone issue
- **30:** Account/fulfillment mismatch
- **31:** Other reason
- **32:** Unblock request
- **86:** Notification of death
**Allowable Values:**
`00`, `01`, `02`, `03`, `04`, `05`, `06`, `07`, `08`, `09`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, `18`, `19`, `20`, `21`, `22`, `23`, `24`, `25`, `26`, `27`, `28`, `29`, `30`, `31`, `32`, `86` |
| state
string
Returned | Specifies the state to which the digital wallet token is transitioning.
**Allowable Values:**
`REQUESTED`, `REQUEST_DECLINED`, `ACTIVE`, `SUSPENDED`, `TERMINATED` |
| 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 |
| type
string
Returned | Type of digital wallet token transition. `state.activated`, for example.
**Allowable Values:**
36 char max |
Sample response body
```json JSON lines wrap theme={null}
{
"token": "my_transition_04",
"digital_wallet_token": {
"token": "my_digital_wallet_token_0987"
},
"type": "state.activated",
"channel": "API",
"state": "ACTIVE",
"fulfillment_status": "PROVISIONED",
"reason": "Passed additional identity verification",
"reason_code": "18",
"created_time": "2025-02-23T18:57:45Z"
}
```
List transitions for digital wallet token
**Action:** `GET`\
**Endpoint:** `/digitalwallettokentransitions/digitalwallettoken/{token}`
{/* */}
Use this 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 (DWT).
**Allowable Values:**
Existing DWT token |
URL query parameters
| Fields | Description |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count
integer
Optional | Number of digital wallet transitions to retrieve.
**Allowable Values:**
Any integer
**Default value:**
5 |
| start\_index
integer
Optional | The sort order index of the first digital wallet token in the returned array.
**Allowable Values:**
Any integer
**Default value:**
0 |
| 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
**Default value:**
`-id` |
Response body
| Fields | Description |
| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count
integer
Conditionally returned | Number of resources returned.
This field is returned if there are resources in your returned array.
**Allowable Values:**
Any integer |
| data
array of objects
Conditionally returned | Array of digital wallet token transition resources.
Resources are returned as appropriate to your query.
**Allowable Values:**
One or more digital wallet token transition resources |
| data\[].**card\_swap**
object
Conditionally returned | Contains identifiers for swapping digital wallet tokens between cards.
**Allowable Values:**
`new_card_token`, `previous_card_token` |
| data\[].card\_swap.**new\_card\_token**
string
Returned | Unique identifier of the new card resource to which the digital wallet tokens are assigned.
**Allowable Values:**
1–36 chars |
| data\[].card\_swap.**previous\_card\_token**
string
Returned | Unique identifier of the existing card resource that has digital wallet tokens assigned to it.
**Allowable Values:**
1–36 chars |
| data\[].**channel**
string
Returned | Mechanism by which the transition was initiated.
**Allowable Values:**
`TOKEN_SERVICE_PROVIDER`, `DIGITAL_WALLET`, `API`, `IVR`, `FRAUD`, `ADMIN`, `SYSTEM`, `TOKEN_SERVICE_PROVIDER_API` |
| data\[].**created\_time**
datetime
Conditionally returned | Date and time when the transition was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].**digital\_wallet\_token**
object
Returned | Contains identifiers of the digital wallet token resource and the card resource.
**Allowable Values:**
Unique identifiers of the digital wallet token resource and the card resource |
| data\[].digital\_wallet\_token.**token**
string
Returned | Unique identifier of the digital wallet token resource.
**Allowable Values:**
1–36 chars |
| data\[].digital\_wallet\_token.**card\_token**
string
Conditionally returned | Unique identifier of the card resource to use for the provisioning request.
**Allowable Values:**
1–36 chars |
| data\[].**fulfillment\_status**
string
Returned | Provisioning status of the digital wallet token.
**Allowable Values:**
`DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN`, `REJECTED`, `PROVISIONED` |
| data\[].**reason**
string
Conditionally returned | Reason for the transition.
**Allowable Values:**
255 char max |
| data\[].**reason\_code**
string
Conditionally returned | Standard code describing the reason for the transition:
- **00:** Object activated for the first time
- **01:** Requested by you
- **02:** Inactivity over time
- **03:** This address cannot accept mail or the addressee is unknown
- **04:** Negative account balance
- **05:** Account under review
- **06:** Suspicious activity was identified
- **07:** Activity outside the program parameters was identified
- **08:** Confirmed fraud was identified
- **09:** Matched with an Office of Foreign Assets Control list
- **10:** Card was reported lost
- **11:** Card information was cloned
- **12:** Account or card information was compromised
- **13:** Temporary status change while on hold/leave
- **14:** Initiated by Marqeta
- **15:** Initiated by issuer
- **16:** Card expired
- **17:** Failed KYC
- **18:** Changed to `ACTIVE` because information was properly validated
- **19:** Changed to `ACTIVE` because account activity was properly validated
- **20:** Change occurred prior to the normalization of reason codes
- **21:** Initiated by a third party, often a digital wallet provider
- **22:** PIN retry limit reached
- **23:** Card was reported stolen
- **24:** Address issue
- **25:** Name issue
- **26:** SSN issue
- **27:** DOB issue
- **28:** Email issue
- **29:** Phone issue
- **30:** Account/fulfillment mismatch
- **31:** Other reason
- **32:** Unblock request
- **86:** Notification of death
**Allowable Values:**
`00`, `01`, `02`, `03`, `04`, `05`, `06`, `07`, `08`, `09`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, `18`, `19`, `20`, `21`, `22`, `23`, `24`, `25`, `26`, `27`, `28`, `29`, `30`, `31`, `32`, `86` |
| data\[].**state**
string
Returned | Specifies the state to which the digital wallet token is transitioning.
**Allowable Values:**
`REQUESTED`, `REQUEST_DECLINED`, `ACTIVE`, `SUSPENDED`, `TERMINATED` |
| 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\[].**type**
string
Returned | Type of digital wallet token transition. `state.activated`, for example.
**Allowable Values:**
36 char max |
| end\_index
integer
Conditionally 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` |
| start\_index
integer
Conditionally 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 |
Sample response body
```json JSON expandable lines wrap theme={null}
{
"count": 2,
"start_index": 0,
"end_index": 1,
"is_more": false,
"data": [
{
"token": "my_transition_04",
"digital_wallet_token": {
"token": "my_digital_wallet_token_0987"
},
"type": "state.activated",
"channel": "API",
"state": "ACTIVE",
"fulfillment_status": "PROVISIONED",
"reason": "Passed additional identity verification",
"reason_code": "18",
"created_time": "2025-02-23T18:57:45Z"
},
{
"token": "my_transition_04",
"digital_wallet_token": {
"token": "my_digital_wallet_token_0987"
},
"type": "fulfillment.requested",
"channel": "TOKEN_SERVICE_PROVIDER",
"state": "REQUESTED",
"fulfillment_status": "DECISION_YELLOW",
"reason": "Additional identity verification required",
"reason_code": "21",
"created_time": "2024-02-23T18:44:21Z"
}
]
}
```
List digital wallet tokens
**Action:** `GET`\
**Endpoint:** `/digitalwallettokens`
{/* */}
Use this endpoint to retrieve a list of digital wallet tokens.
URL query parameters
| Fields | Description |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count
integer
Optional | Number of digital wallet token resources to retrieve.
**Allowable Values:**
1–100
**Default value:**
10 |
| start\_index
integer
Optional | Sort order index of the first digital wallet token resource in the returned array.
**Allowable Values:**
Any integer
**Default value:**
0 |
| 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
**Default value:**
`-createdTime` |
| 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 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 Apple Wallet and Google Wallet for the same digital wallet token.
**Allowable Values:**
255 char max |
| 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.
**Allowable Values:**
255 char max |
| correlation\_id
string
Optional | Unique value representing a tokenization request (Mastercard only).
**Allowable Values:**
255 char max |
| 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 | An optional embedded user object.
**Allowable Values:**
`user` |
Response body
| Fields | Description |
| --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count
integer
Conditionally returned | Number of resources returned.
This field is returned if there are resources in your returned array.
**Allowable Values:**
Any integer |
| data
array of objects
Conditionally returned | Array of digital wallet token resources.
Resources are returned as appropriate to your query.
**Allowable Values:**
Valid array of one or more digital wallet token resources |
| data\[].**address\_verification**
object
Conditionally returned | Contains address verification information.
**Allowable Values:**
`name`, `postal_code`, `street_address`, `zip` |
| data\[].address\_verification.**name**
string
Conditionally returned | Name of the cardholder.
**Allowable Values:**
40 char max |
| data\[].address\_verification.**postal\_code**
string
Conditionally returned | Postal code.
**Allowable Values:**
10 char max |
| data\[].address\_verification.**street\_address**
string
Conditionally returned | Street address provided by the cardholder.
**Allowable Values:**
40 char max |
| data\[].address\_verification.**zip**
string
Conditionally returned | United States ZIP code.
**Allowable Values:**
10 char max |
| data\[].**card\_token**
string
Conditionally returned | Unique identifier of the card.
**Allowable Values:**
Existing card token |
| data\[].**created\_time**
datetime
Conditionally returned | Date and time when the digital wallet token object was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].**device**
object
Conditionally returned | Contains information related to the device being provisioned.
**Allowable Values:**
`device_id`, `ip_address`, `language_code`, `location`, `name`, `phone_number`, `token`, `type` |
| data\[].device.**device\_id**
string
Conditionally returned | Identity number of the device.
**Allowable Values:**
24 char max |
| data\[].device.**ip\_address**
string
Conditionally returned | Device’s IP address.
**Allowable Values:**
IP address format, 50 char max |
| data\[].device.**language\_code**
string
Conditionally returned | Language the device is configured to use.
**Allowable Values:**
50 char max |
| data\[].device.**location**
string
Conditionally returned | Geographic coordinates of the device.
**Allowable Values:**
Latitude and longitude in `DDD.DD/DDD.DD` format.
**NOTE:** Both the longitude and latitude are prefixed with either a `+` or `-` symbol, for example: `+42.29/-71.07`. |
| data\[].device.**name**
string
Conditionally returned | Name of the device.
**Allowable Values:**
50 char max |
| data\[].device.**phone\_number**
string
Conditionally returned | Device’s telephone number.
**Allowable Values:**
50 char max |
| data\[].device.**token**
string
Conditionally returned | Unique identifier of the device object.
**Allowable Values:**
36 char max |
| data\[].device.**type**
string
Conditionally returned | Type of device being provisioned.
**Allowable Values:**
`MOBILE_PHONE`, `WATCH`, `TABLET`, `MOBILE_PHONE_OR_TABLET`, `VEHICLE`, `APPLIANCE`, `LAPTOP`, `GAMING_DEVICE`, `WEARABLE_DEVICE`, `UNKNOWN` |
| data\[].**fulfillment\_status**
string
Conditionally returned | Digital wallet token’s provisioning status.
For fulfillment status descriptions, see Create digital wallet token transition.
**Allowable Values:**
`DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN`, `REJECTED`, `PROVISIONED` |
| data\[].**issuer\_eligibility\_decision**
string
Conditionally returned | The Marqeta platform’s decision as to whether the digital wallet token should be provisioned.
- **0000** – The token should be provisioned.
- **token.activation.verification.required** – Provisioning is pending; further action is required for completion.
For all other values, check the value of the `fulfillment_status` field to definitively ascertain the provisioning outcome.
**NOTE:** The value `invalid.cid` indicates an invalid CVV2 number.
**Allowable Values:**
0000, `cardaccount.verified`, `card.suspicious`, `token.activation.verification.required`, `token.activation-request.decline`, `card.not.active`, `invalid.cid`, `card.expired`, `card.suspended`, `cardholder.not.active` |
| data\[].**last\_modified\_time**
datetime
Conditionally returned | Date and time when the digital wallet token object was last modified, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].**metadata**
object
Conditionally returned | Contains additional information about the digital wallet token.
**Allowable Values:**
`cardproduct_preferred_notification_language`, `issuer_product_config_id` |
| data\[].metadata.**cardproduct\_preferred\_notification\_language**
string
Conditionally returned | Language specified in the `config.transaction_controls.notification_language` field of the card product:
- **ces** – Czech
- **deu** – German
- **eng** – English
- **fra** – French
- **ell** – Greek
- **ita** – Italian
- **nld** – Dutch
- **pol** – Polish
- **por** – Portuguese
- **ron** – Romanian
- **spa** – Spanish
- **swe** – Swedish
By default, notifications are sent in English.
The ISO maintains the full list of ISO 3166 two- and three-digit numeric country codes.
**Allowable Values:**
`ces`, `deu`, `eng`, `fra`, `ell`, `ita`, `nld`, `pol`, `por`, `ron`, `spa`, `swe` |
| data\[].metadata.**issuer\_product\_config\_id**
string
Conditionally returned | Unique identifier of the product configuration on the Marqeta platform.
**Allowable Values:**
255 char max |
| data\[].**state**
string
Conditionally returned | State of the digital wallet token.
For state descriptions, see Transitioning Token States.
**Allowable Values:**
`REQUESTED`, `REQUEST_DECLINED`, `ACTIVE`, `SUSPENDED`, `TERMINATED` |
| data\[].**state\_reason**
string
Conditionally returned | Reason why the digital wallet token transitioned to its current state.
**Allowable Values:**
255 char max |
| data\[].**token**
string
Conditionally returned | Unique identifier of the digital wallet token.
**Allowable Values:**
Existing digital wallet token. |
| data\[].**token\_service\_provider**
object
Conditionally returned | Contains information held and provided by the token service provider (card network).
**Allowable Values:**
`correlation_id`, `pan_reference_id`, `token_assurance_level`, `token_eligibility_decision`, `token_expiration`, `token_pan`, `token_reference_id`, `token_requestor_id`, `token_requestor_name`, `token_score`, `token_type` |
| data\[].token\_service\_provider.**correlation\_id**
string
Conditionally returned | For Mastercard only. Unique value representing a tokenization request.
**Allowable Values:**
Existing correlation identifier |
| data\[].token\_service\_provider.**pan\_reference\_id**
string
Conditionally returned | Unique identifier of the digital wallet token primary account number (PAN) within the card network.
**Allowable Values:**
Existing PAN Reference ID |
| data\[].token\_service\_provider.**token\_assurance\_level**
string
Conditionally returned | For Mastercard only. Represents the confidence level in the digital wallet token.
**Allowable Values:**
0-99 |
| data\[].token\_service\_provider.**token\_eligibility\_decision**
string
Conditionally returned | Digital wallet’s decision as to whether the digital wallet token should be provisioned.
**Allowable Values:**
`DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN` |
| data\[].token\_service\_provider.**token\_expiration**
string
Conditionally returned | Expiration date of the digital wallet token.
**Allowable Values:**
Format: MMyy |
| data\[].token\_service\_provider.**token\_pan**
string
Conditionally returned | Primary account number (PAN) of the digital wallet token.
**Allowable Values:**
16 char max |
| data\[].token\_service\_provider.**token\_reference\_id**
string
Conditionally returned | Unique identifier of the digital wallet token within the card network.
**Allowable Values:**
Existing Token Reference ID |
| data\[].token\_service\_provider.**token\_requestor\_id**
string
Conditionally returned | Unique numerical identifier of the token requestor within the card network. These ID numbers map to `token_requestor_name` field values as follows:
**Mastercard**
- 50110030273 – `APPLE_PAY`
- 50120834693 – `ANDROID_PAY`
- 50139059239 – `SAMSUNG_PAY`
**Visa**
- 40010030273 – `APPLE_PAY`
- 40010075001 – `ANDROID_PAY`
- 40010043095 – `SAMSUNG_PAY`
- 40010075196 – `MICROSOFT_PAY`
- 40010075338 – `VISA_CHECKOUT`
- 40010075449 – `FACEBOOK`
- 40010075839 – `NETFLIX`
- 40010077056 – `FITBIT_PAY`
- 40010069887 – `GARMIN_PAY`
**Allowable Values:**
11 char max
**Example Values:**
- **Mastercard** – 50110030273, 50120834693, 50139059239
- **Visa** – 40010030273, 40010075001, 40010075338, 40010075449, 40010075839, 40010043095 |
| data\[].token\_service\_provider.**token\_requestor\_name**
string
Conditionally returned | 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` |
| data\[].token\_service\_provider.**token\_score**
string
Conditionally returned | Token score assigned by the digital wallet.
**Allowable Values:**
25 char max |
| data\[].token\_service\_provider.**token\_type**
string
Conditionally returned | Type of the digital wallet token.
**Allowable Values:**
`MERCHANT_CARD_ON_FILE`, `DEVICE_SECURE_ELEMENT`, `DEVICE_CLOUD_BASED`, `ECOMMERCE_DIGITAL_WALLET` |
| data\[].**transaction\_device**
object
Conditionally returned | Contains information about the device used in the transaction to enhance the risk decisioning process. Use this data to improve fraud prevention and dispute resolution.
**Allowable Values:**
`binding_id`, `ip_address`, `location`, `phone_number` |
| data\[].transaction\_device.**binding\_id**
string
Conditionally returned | Unique identifier of the data component bound to the credential.
**Allowable Values:**
48 char max |
| data\[].transaction\_device.**ip\_address**
string
Conditionally returned | IP address of the device. The presence of the IP address helps determine if the transaction was initiated from an unusual network, helping establish a pattern of safe device usage that further confirms the authenticity of the consumer who initiated the transaction.
**Allowable Values:**
IP address format, 39 char max |
| data\[].transaction\_device.**location**
string
Conditionally returned | Geographic coordinates of the device. Contains the latitude and longitude of the device used when the cardholder was authenticated during checkout. This field helps to determine if the transaction was initiated from an unexpected location.
**Allowable Values:**
Latitude and longitude in `DDD.DD/DDD.DD` format. |
| data\[].transaction\_device.**phone\_number**
string
Conditionally returned | Telephone number of the device. Contains the phone number that was used to authenticate the consumer during checkout, or the consumer’s preferred phone number. The presence of the phone number helps establish the consumer’s authenticity when matching the phone number provided during checkout to a list of known phone numbers for the consumer.
**Allowable Values:**
15 char max |
| data\[].**user**
object
Conditionally returned | Contains information about a cardholder.
**Allowable Values:**
`account_holder_group_token`, `active`, `address1`, `address2`, `authentication`, `birth_date`, `birth_place`, `business_token`, `city`, `company`, `corporate_card_holder`, `country`, `created_time`, `email`, `first_name`, `gender`, `honorific`, `id_card_expiration_date`, `id_card_number`, `identifications`, `ip_address`, `last_modified_time`, `last_name`, `metadata`, `middle_name`, `nationality`, `notes`, `parent_token`, `passport_expiration_date`, `passport_number`, `password`, `phone`, `postal_code`, `ssn`, `state`, `status`, `title`, `token`, `uses_parent_account`, `zip` |
| data\[].user.**account\_holder\_group\_token**
string
Conditionally returned | Associates the specified account holder group with the cardholder.
**Allowable Values:**
36 char max |
| data\[].user.**active**
boolean
Conditionally returned | Specifies if the cardholder is in the `ACTIVE` state on the Marqeta platform.
**Allowable Values:**
`true`, `false` |
| data\[].user.**address1**
string
Conditionally returned | Cardholder’s address.
**Allowable Values:**
255 char max |
| data\[].user.**address2**
string
Conditionally returned | Additional address information for the cardholder.
**Allowable Values:**
255 char max |
| data\[].user.**authentication**
object
Conditionally returned | Contains the cardholder’s email address and password information.
**Allowable Values:**
`email_verified`, `email_verified_time`, `last_password_update_channel`, `last_password_update_time` |
| data\[].user.authentication.**email\_verified**
boolean
Conditionally returned | Specifies whether the email address has been verified.
**Allowable Values:**
`true`, `false` |
| data\[].user.authentication.**email\_verified\_time**
datetime
Conditionally returned | Date and time when the email address was verified.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].user.authentication.**last\_password\_update\_channel**
string
Conditionally returned | Specifies the channel through which the password was last changed.
**Allowable Values:**
`USER_CHANGE`, `USER_RESET` |
| data\[].user.authentication.**last\_password\_update\_time**
datetime
Conditionally returned | Date and time when the password was last changed.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].user.**birth\_date**
string
Conditionally returned | Cardholder’s date of birth.
**Allowable Values:**
Format: yyyy-MM-dd |
| data\[].user.**birth\_place**
string
Conditionally returned | Country where the cardholder was born.
**Allowable Values:**
255 char max
ISO 3166 two-character country codes. For example, the country code for the United States is `US`.
The ISO maintains the full list of ISO-3166 country codes. |
| data\[].user.**business\_token**
string
Conditionally returned | Unique identifier of the business resource.
**Allowable Values:**
Existing business resource token |
| data\[].user.**city**
string
Conditionally returned | City where the cardholder resides.
**Allowable Values:**
40 char max |
| data\[].user.**company**
string
Conditionally returned | Company name.
**Allowable Values:**
255 char max |
| data\[].user.**corporate\_card\_holder**
boolean
Conditionally returned | Specifies if the cardholder holds a corporate card.
**Allowable Values:**
`true`, `false` |
| data\[].user.**country**
string
Conditionally returned | Country where the cardholder resides.
**Allowable Values:**
40 char max |
| data\[].user.**created\_time**
datetime
Returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].user.**email**
string
Conditionally returned | Valid email address of the cardholder.
**Allowable Values:**
1–255 chars |
| data\[].user.**first\_name**
string
Conditionally returned | Cardholder’s first name.
**Allowable Values:**
40 char max |
| data\[].user.**gender**
string
Conditionally returned | Gender of the cardholder.
**Allowable Values:**
`F`, `M` |
| data\[].user.**honorific**
string
Conditionally returned | Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on.
**Allowable Values:**
10 char max |
| data\[].user.**id\_card\_expiration\_date**
string
Conditionally returned | Expiration date of the cardholder’s identification.
**Allowable Values:**
Format: yyyy-MM-dd |
| data\[].user.**id\_card\_number**
string
Conditionally returned | Cardholder’s identification card number.
**Allowable Values:**
255 char max |
| data\[].user.**identifications**
array of objects
Conditionally returned | One or more objects containing identifications associated with the cardholder.
**Allowable Values:**
Valid array of one or more `identifications` objects |
| data\[].user.identifications\[].**expiration\_date**
string
Conditionally returned | Expiration date of the identification, if applicable.
**Allowable Values:**
Format: yyyy-MM-dd |
| data\[].user.identifications\[].**type**
string
Conditionally returned | Type of identification.
**Allowable Values:**
`SSN`, `TIN`, `SIN`, `NIN`, `PASSPORT_NUMBER`, `DRIVERS_LICENSE`, `BUSINESS_NUMBER`, `BUSINESS_TAX_ID`, `TAXPAYER_REFERENCE` |
| data\[].user.identifications\[].**value**
string
Conditionally returned | Number associated with the identification.
**Allowable Values:**
255 char max |
| data\[].user.**ip\_address**
string
Conditionally returned | Cardholder’s IP address.
**Allowable Values:**
39 char max |
| data\[].user.**last\_modified\_time**
datetime
Returned | Date and time when the resource was last updated, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].user.**last\_name**
string
Conditionally returned | Cardholder’s last name.
**Allowable Values:**
40 char max |
| data\[].user.**metadata**
object
Conditionally returned | Associates any additional metadata you provide with the cardholder.
**Allowable Values:**
You can define the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"` |
| data\[].user.**middle\_name**
string
Conditionally returned | Cardholder’s middle name.
**Allowable Values:**
40 char max |
| data\[].user.**nationality**
string
Conditionally returned | Cardholder’s nationality.
**Allowable Values:**
255 char max |
| data\[].user.**notes**
string
Conditionally returned | Any additional information pertaining to the cardholder.
**Allowable Values:**
255 char max |
| data\[].user.**parent\_token**
string
Conditionally returned | Unique identifier of the parent user or business resource.
**Allowable Values:**
1–36 chars |
| data\[].user.**passport\_expiration\_date**
string
Conditionally returned | Expiration date of the cardholder’s passport.
**Allowable Values:**
Format: yyyy-MM-dd |
| data\[].user.**passport\_number**
string
Conditionally returned | Cardholder’s passport number.
**Allowable Values:**
40 char max |
| data\[].user.**password**
string
Conditionally returned | Password to the cardholder’s user account on the Marqeta platform.
**Allowable Values:**
1–255 chars |
| data\[].user.**phone**
string
Conditionally returned | Cardholder’s telephone number.
**Allowable Values:**
255 char max |
| data\[].user.**postal\_code**
string
Conditionally returned | Postal code of the cardholder’s address.
**Allowable Values:**
10 char max |
| data\[].user.**ssn**
string
Conditionally returned | Cardholder’s Social Security Number (SSN).
**Allowable Values:**
Nine digits only, no delimiters. |
| data\[].user.**state**
string
Conditionally returned | State or province where the cardholder resides.
**Allowable Values:**
2 char max |
| data\[].user.**status**
string
Conditionally returned | Specifies the status of the cardholder on the Marqeta platform.
**Allowable Values:**
`UNVERIFIED`, `LIMITED`, `ACTIVE`, `SUSPENDED`, `CLOSED` |
| data\[].user.**title**
string
Conditionally returned | Professional title of the cardholder, such as Chief Comptroller.
**Allowable Values:**
255 char max |
| data\[].user.**token**
string
Conditionally returned | Unique identifier of the cardholder.
**Allowable Values:**
1–36 chars |
| data\[].user.**uses\_parent\_account**
boolean
Conditionally returned | Indicates whether the child shares balances with the parent (`true`), or the child’s balances are independent of the parent (`false`).
**Allowable Values:**
`true`, `false` |
| data\[].user.**zip**
string
Conditionally returned | United States ZIP code of the cardholder’s address.
**Allowable Values:**
10 char max |
| data\[].**wallet\_provider\_profile**
object
Conditionally returned | Contains information held and provided by the digital wallet provider.
**Allowable Values:**
`account`, `device_score`, `pan_source`, `reason_code`, `recommendation_reasons`, `risk_assessment` |
| data\[].wallet\_provider\_profile.**account**
object
Conditionally returned | Contains information related to the cardholder and provided by the digital wallet provider.
**Allowable Values:**
`email_address`, `id`, `score` |
| data\[].wallet\_provider\_profile.account.**email\_address**
string
Conditionally returned | Digital wallet provider’s email address for the cardholder.
**Allowable Values:**
255 char max |
| data\[].wallet\_provider\_profile.account.**id**
string
Conditionally returned | Digital wallet provider’s identity number for the cardholder.
**Allowable Values:**
20 char max |
| data\[].wallet\_provider\_profile.account.**score**
string
Conditionally returned | Score from the digital wallet provider.
**Allowable Values:**
50 char max |
| data\[].wallet\_provider\_profile.**device\_score**
string
Conditionally returned | Score from the device.
**Allowable Values:**
50 char max |
| data\[].wallet\_provider\_profile.**pan\_source**
string
Conditionally returned | Source from which the digital wallet provider obtained the card primary account number (PAN).
**Allowable Values:**
`KEY_ENTERED`, `ON_FILE`, `MOBILE_BANKING_APP` |
| data\[].wallet\_provider\_profile.**reason\_code**
string
Conditionally returned | Reason for the wallet provider’s provisioning decision.
- **01** – Cardholder’s wallet account is too new relative to launch.
- **02** – Cardholder’s wallet account is too new relative to provisioning request.
- **03** – Cardholder’s wallet account/card pair is newer than date threshold.
- **04** – Changes made to account data within the account threshold.
- **05** – Suspicious transactions linked to this account.
- **06** – Account has not had activity in the last year.
- **07** – Suspended cards in the secure element.
- **08** – Device was put in lost mode in the last seven days for longer than the duration threshold.
- **09** – The number of provisioning attempts on this device in 24 hours exceeds threshold.
- **0A** – There have been more than the threshold number of different cards attempted at provisioning to this phone in 24 hours.
- **0B** – The card provisioning attempt contains a distinct name in excess of the threshold.
- **0C** – The device score is less than 3.
- **0D** – The account score is less than 4.
- **0E** – Device provisioning location outside of the cardholder’s wallet account home country.
- **0G** – Suspect fraud.
**Allowable Values:**
01, 02, 03, 04, 05, 06, 07, 08, 09, 0A, 0B, 0C, 0D, 0E, 0G |
| data\[].wallet\_provider\_profile.**recommendation\_reasons**
array of strings
Conditionally returned | Array of recommendation reasons from the digital wallet provider.
**Allowable Values:**
Valid array of one or more recommendation reasons |
| data\[].wallet\_provider\_profile.**risk\_assessment**
object
Conditionally returned | Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token.
**Allowable Values:**
`score`, `version` |
| data\[].wallet\_provider\_profile.risk\_assessment.**score**
string
Conditionally returned | Wallet provider’s decision as to whether the digital wallet token should be provisioned.
**Allowable Values:**
`DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN` |
| data\[].wallet\_provider\_profile.risk\_assessment.**version**
string
Conditionally returned | Wallet provider’s risk assessment version.
**Allowable Values:**
Version information, as provided by the wallet provider |
| end\_index
integer
Conditionally 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` |
| start\_index
integer
Conditionally 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 |
Retrieve digital wallet token
**Action:** `GET`\
**Endpoint:** `/digitalwallettokens/{token}`
{/* */}
Use this endpoint to retrieve a specific digital wallet token.
URL path parameters
| Fields | Description |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| token
string
Required | Unique identifier of the digital wallet token (DWT).
**Allowable Values:**
Existing DWT token |
Response body
| Fields | Description |
| ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| address\_verification
object
Conditionally returned | Contains address verification information.
**Allowable Values:**
`name`, `postal_code`, `street_address`, `zip` |
| address\_verification.**name**
string
Conditionally returned | Name of the cardholder.
**Allowable Values:**
40 char max |
| address\_verification.**postal\_code**
string
Conditionally returned | Postal code.
**Allowable Values:**
10 char max |
| address\_verification.**street\_address**
string
Conditionally returned | Street address provided by the cardholder.
**Allowable Values:**
40 char max |
| address\_verification.**zip**
string
Conditionally returned | United States ZIP code.
**Allowable Values:**
10 char max |
| card\_token
string
Conditionally returned | Unique identifier of the card.
**Allowable Values:**
Existing card token |
| created\_time
datetime
Conditionally returned | Date and time when the digital wallet token object was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| device
object
Conditionally returned | Contains information related to the device being provisioned.
**Allowable Values:**
`device_id`, `ip_address`, `language_code`, `location`, `name`, `phone_number`, `token`, `type` |
| device.**device\_id**
string
Conditionally returned | Identity number of the device.
**Allowable Values:**
24 char max |
| device.**ip\_address**
string
Conditionally returned | Device’s IP address.
**Allowable Values:**
IP address format, 50 char max |
| device.**language\_code**
string
Conditionally returned | Language the device is configured to use.
**Allowable Values:**
50 char max |
| device.**location**
string
Conditionally returned | Geographic coordinates of the device.
**Allowable Values:**
Latitude and longitude in `DDD.DD/DDD.DD` format.
**NOTE:** Both the longitude and latitude are prefixed with either a `+` or `-` symbol, for example: `+42.29/-71.07`. |
| device.**name**
string
Conditionally returned | Name of the device.
**Allowable Values:**
50 char max |
| device.**phone\_number**
string
Conditionally returned | Device’s telephone number.
**Allowable Values:**
50 char max |
| device.**token**
string
Conditionally returned | Unique identifier of the device object.
**Allowable Values:**
36 char max |
| device.**type**
string
Conditionally returned | Type of device being provisioned.
**Allowable Values:**
`MOBILE_PHONE`, `WATCH`, `TABLET`, `MOBILE_PHONE_OR_TABLET`, `VEHICLE`, `APPLIANCE`, `LAPTOP`, `GAMING_DEVICE`, `WEARABLE_DEVICE`, `UNKNOWN` |
| fulfillment\_status
string
Conditionally returned | Digital wallet token’s provisioning status.
For fulfillment status descriptions, see Create digital wallet token transition.
**Allowable Values:**
`DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN`, `REJECTED`, `PROVISIONED` |
| issuer\_eligibility\_decision
string
Conditionally returned | The Marqeta platform’s decision as to whether the digital wallet token should be provisioned.
- **0000** – The token should be provisioned.
- **token.activation.verification.required** – Provisioning is pending; further action is required for completion.
For all other values, check the value of the `fulfillment_status` field to definitively ascertain the provisioning outcome.
**NOTE:** The value `invalid.cid` indicates an invalid CVV2 number.
**Allowable Values:**
0000, `cardaccount.verified`, `card.suspicious`, `token.activation.verification.required`, `token.activation-request.decline`, `card.not.active`, `invalid.cid`, `card.expired`, `card.suspended`, `cardholder.not.active` |
| last\_modified\_time
datetime
Conditionally returned | Date and time when the digital wallet token object was last modified, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| metadata
object
Conditionally returned | Contains additional information about the digital wallet token.
**Allowable Values:**
`cardproduct_preferred_notification_language`, `issuer_product_config_id` |
| metadata.**cardproduct\_preferred\_notification\_language**
string
Conditionally returned | Language specified in the `config.transaction_controls.notification_language` field of the card product:
- **ces** – Czech
- **deu** – German
- **eng** – English
- **fra** – French
- **ell** – Greek
- **ita** – Italian
- **nld** – Dutch
- **pol** – Polish
- **por** – Portuguese
- **ron** – Romanian
- **spa** – Spanish
- **swe** – Swedish
By default, notifications are sent in English.
The ISO maintains the full list of ISO 3166 two- and three-digit numeric country codes.
**Allowable Values:**
`ces`, `deu`, `eng`, `fra`, `ell`, `ita`, `nld`, `pol`, `por`, `ron`, `spa`, `swe` |
| metadata.**issuer\_product\_config\_id**
string
Conditionally returned | Unique identifier of the product configuration on the Marqeta platform.
**Allowable Values:**
255 char max |
| state
string
Conditionally returned | State of the digital wallet token.
For state descriptions, see Transitioning Token States.
**Allowable Values:**
`REQUESTED`, `REQUEST_DECLINED`, `ACTIVE`, `SUSPENDED`, `TERMINATED` |
| state\_reason
string
Conditionally returned | Reason why the digital wallet token transitioned to its current state.
**Allowable Values:**
255 char max |
| token
string
Conditionally returned | Unique identifier of the digital wallet token.
**Allowable Values:**
Existing digital wallet token. |
| token\_service\_provider
object
Conditionally returned | Contains information held and provided by the token service provider (card network).
**Allowable Values:**
`correlation_id`, `pan_reference_id`, `token_assurance_level`, `token_eligibility_decision`, `token_expiration`, `token_pan`, `token_reference_id`, `token_requestor_id`, `token_requestor_name`, `token_score`, `token_type` |
| token\_service\_provider.**correlation\_id**
string
Conditionally returned | For Mastercard only. Unique value representing a tokenization request.
**Allowable Values:**
Existing correlation identifier |
| token\_service\_provider.**pan\_reference\_id**
string
Conditionally returned | Unique identifier of the digital wallet token primary account number (PAN) within the card network.
**Allowable Values:**
Existing PAN Reference ID |
| token\_service\_provider.**token\_assurance\_level**
string
Conditionally returned | For Mastercard only. Represents the confidence level in the digital wallet token.
**Allowable Values:**
0-99 |
| token\_service\_provider.**token\_eligibility\_decision**
string
Conditionally returned | Digital wallet’s decision as to whether the digital wallet token should be provisioned.
**Allowable Values:**
`DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN` |
| token\_service\_provider.**token\_expiration**
string
Conditionally returned | Expiration date of the digital wallet token.
**Allowable Values:**
Format: MMyy |
| token\_service\_provider.**token\_pan**
string
Conditionally returned | Primary account number (PAN) of the digital wallet token.
**Allowable Values:**
16 char max |
| token\_service\_provider.**token\_reference\_id**
string
Conditionally returned | Unique identifier of the digital wallet token within the card network.
**Allowable Values:**
Existing Token Reference ID |
| token\_service\_provider.**token\_requestor\_id**
string
Conditionally returned | Unique numerical identifier of the token requestor within the card network. These ID numbers map to `token_requestor_name` field values as follows:
**Mastercard**
- 50110030273 – `APPLE_PAY`
- 50120834693 – `ANDROID_PAY`
- 50139059239 – `SAMSUNG_PAY`
**Visa**
- 40010030273 – `APPLE_PAY`
- 40010075001 – `ANDROID_PAY`
- 40010043095 – `SAMSUNG_PAY`
- 40010075196 – `MICROSOFT_PAY`
- 40010075338 – `VISA_CHECKOUT`
- 40010075449 – `FACEBOOK`
- 40010075839 – `NETFLIX`
- 40010077056 – `FITBIT_PAY`
- 40010069887 – `GARMIN_PAY`
**Allowable Values:**
11 char max
**Example Values:**
- **Mastercard** – 50110030273, 50120834693, 50139059239
- **Visa** – 40010030273, 40010075001, 40010075338, 40010075449, 40010075839, 40010043095 |
| token\_service\_provider.**token\_requestor\_name**
string
Conditionally returned | 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` |
| token\_service\_provider.**token\_score**
string
Conditionally returned | Token score assigned by the digital wallet.
**Allowable Values:**
25 char max |
| token\_service\_provider.**token\_type**
string
Conditionally returned | Type of the digital wallet token.
**Allowable Values:**
`MERCHANT_CARD_ON_FILE`, `DEVICE_SECURE_ELEMENT`, `DEVICE_CLOUD_BASED`, `ECOMMERCE_DIGITAL_WALLET` |
| transaction\_device
object
Conditionally returned | Contains information about the device used in the transaction to enhance the risk decisioning process. Use this data to improve fraud prevention and dispute resolution.
**Allowable Values:**
`binding_id`, `ip_address`, `location`, `phone_number` |
| transaction\_device.**binding\_id**
string
Conditionally returned | Unique identifier of the data component bound to the credential.
**Allowable Values:**
48 char max |
| transaction\_device.**ip\_address**
string
Conditionally returned | IP address of the device. The presence of the IP address helps determine if the transaction was initiated from an unusual network, helping establish a pattern of safe device usage that further confirms the authenticity of the consumer who initiated the transaction.
**Allowable Values:**
IP address format, 39 char max |
| transaction\_device.**location**
string
Conditionally returned | Geographic coordinates of the device. Contains the latitude and longitude of the device used when the cardholder was authenticated during checkout. This field helps to determine if the transaction was initiated from an unexpected location.
**Allowable Values:**
Latitude and longitude in `DDD.DD/DDD.DD` format. |
| transaction\_device.**phone\_number**
string
Conditionally returned | Telephone number of the device. Contains the phone number that was used to authenticate the consumer during checkout, or the consumer’s preferred phone number. The presence of the phone number helps establish the consumer’s authenticity when matching the phone number provided during checkout to a list of known phone numbers for the consumer.
**Allowable Values:**
15 char max |
| user
object
Conditionally returned | Contains information about a cardholder.
**Allowable Values:**
`account_holder_group_token`, `active`, `address1`, `address2`, `authentication`, `birth_date`, `birth_place`, `business_token`, `city`, `company`, `corporate_card_holder`, `country`, `created_time`, `email`, `first_name`, `gender`, `honorific`, `id_card_expiration_date`, `id_card_number`, `identifications`, `ip_address`, `last_modified_time`, `last_name`, `metadata`, `middle_name`, `nationality`, `notes`, `parent_token`, `passport_expiration_date`, `passport_number`, `password`, `phone`, `postal_code`, `ssn`, `state`, `status`, `title`, `token`, `uses_parent_account`, `zip` |
| user.**account\_holder\_group\_token**
string
Conditionally returned | Associates the specified account holder group with the cardholder.
**Allowable Values:**
36 char max |
| user.**active**
boolean
Conditionally returned | Specifies if the cardholder is in the `ACTIVE` state on the Marqeta platform.
**Allowable Values:**
`true`, `false` |
| user.**address1**
string
Conditionally returned | Cardholder’s address.
**Allowable Values:**
255 char max |
| user.**address2**
string
Conditionally returned | Additional address information for the cardholder.
**Allowable Values:**
255 char max |
| user.**authentication**
object
Conditionally returned | Contains the cardholder’s email address and password information.
**Allowable Values:**
`email_verified`, `email_verified_time`, `last_password_update_channel`, `last_password_update_time` |
| user.authentication.**email\_verified**
boolean
Conditionally returned | Specifies whether the email address has been verified.
**Allowable Values:**
`true`, `false` |
| user.authentication.**email\_verified\_time**
datetime
Conditionally returned | Date and time when the email address was verified.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| user.authentication.**last\_password\_update\_channel**
string
Conditionally returned | Specifies the channel through which the password was last changed.
**Allowable Values:**
`USER_CHANGE`, `USER_RESET` |
| user.authentication.**last\_password\_update\_time**
datetime
Conditionally returned | Date and time when the password was last changed.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| user.**birth\_date**
string
Conditionally returned | Cardholder’s date of birth.
**Allowable Values:**
Format: yyyy-MM-dd |
| user.**birth\_place**
string
Conditionally returned | Country where the cardholder was born.
**Allowable Values:**
255 char max
ISO 3166 two-character country codes. For example, the country code for the United States is `US`.
The ISO maintains the full list of ISO-3166 country codes. |
| user.**business\_token**
string
Conditionally returned | Unique identifier of the business resource.
**Allowable Values:**
Existing business resource token |
| user.**city**
string
Conditionally returned | City where the cardholder resides.
**Allowable Values:**
40 char max |
| user.**company**
string
Conditionally returned | Company name.
**Allowable Values:**
255 char max |
| user.**corporate\_card\_holder**
boolean
Conditionally returned | Specifies if the cardholder holds a corporate card.
**Allowable Values:**
`true`, `false` |
| user.**country**
string
Conditionally returned | Country where the cardholder resides.
**Allowable Values:**
40 char max |
| user.**created\_time**
datetime
Returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| user.**email**
string
Conditionally returned | Valid email address of the cardholder.
**Allowable Values:**
1–255 chars |
| user.**first\_name**
string
Conditionally returned | Cardholder’s first name.
**Allowable Values:**
40 char max |
| user.**gender**
string
Conditionally returned | Gender of the cardholder.
**Allowable Values:**
`F`, `M` |
| user.**honorific**
string
Conditionally returned | Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on.
**Allowable Values:**
10 char max |
| user.**id\_card\_expiration\_date**
string
Conditionally returned | Expiration date of the cardholder’s identification.
**Allowable Values:**
Format: yyyy-MM-dd |
| user.**id\_card\_number**
string
Conditionally returned | Cardholder’s identification card number.
**Allowable Values:**
255 char max |
| user.**identifications**
array of objects
Conditionally returned | One or more objects containing identifications associated with the cardholder.
**Allowable Values:**
Valid array of one or more `identifications` objects |
| user.identifications\[].**expiration\_date**
string
Conditionally returned | Expiration date of the identification, if applicable.
**Allowable Values:**
Format: yyyy-MM-dd |
| user.identifications\[].**type**
string
Conditionally returned | Type of identification.
**Allowable Values:**
`SSN`, `TIN`, `SIN`, `NIN`, `PASSPORT_NUMBER`, `DRIVERS_LICENSE`, `BUSINESS_NUMBER`, `BUSINESS_TAX_ID`, `TAXPAYER_REFERENCE` |
| user.identifications\[].**value**
string
Conditionally returned | Number associated with the identification.
**Allowable Values:**
255 char max |
| user.**ip\_address**
string
Conditionally returned | Cardholder’s IP address.
**Allowable Values:**
39 char max |
| user.**last\_modified\_time**
datetime
Returned | Date and time when the resource was last updated, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| user.**last\_name**
string
Conditionally returned | Cardholder’s last name.
**Allowable Values:**
40 char max |
| user.**metadata**
object
Conditionally returned | Associates any additional metadata you provide with the cardholder.
**Allowable Values:**
You can define the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"` |
| user.**middle\_name**
string
Conditionally returned | Cardholder’s middle name.
**Allowable Values:**
40 char max |
| user.**nationality**
string
Conditionally returned | Cardholder’s nationality.
**Allowable Values:**
255 char max |
| user.**notes**
string
Conditionally returned | Any additional information pertaining to the cardholder.
**Allowable Values:**
255 char max |
| user.**parent\_token**
string
Conditionally returned | Unique identifier of the parent user or business resource.
**Allowable Values:**
1–36 chars |
| user.**passport\_expiration\_date**
string
Conditionally returned | Expiration date of the cardholder’s passport.
**Allowable Values:**
Format: yyyy-MM-dd |
| user.**passport\_number**
string
Conditionally returned | Cardholder’s passport number.
**Allowable Values:**
40 char max |
| user.**password**
string
Conditionally returned | Password to the cardholder’s user account on the Marqeta platform.
**Allowable Values:**
1–255 chars |
| user.**phone**
string
Conditionally returned | Cardholder’s telephone number.
**Allowable Values:**
255 char max |
| user.**postal\_code**
string
Conditionally returned | Postal code of the cardholder’s address.
**Allowable Values:**
10 char max |
| user.**ssn**
string
Conditionally returned | Cardholder’s Social Security Number (SSN).
**Allowable Values:**
Nine digits only, no delimiters. |
| user.**state**
string
Conditionally returned | State or province where the cardholder resides.
**Allowable Values:**
2 char max |
| user.**status**
string
Conditionally returned | Specifies the status of the cardholder on the Marqeta platform.
**Allowable Values:**
`UNVERIFIED`, `LIMITED`, `ACTIVE`, `SUSPENDED`, `CLOSED` |
| user.**title**
string
Conditionally returned | Professional title of the cardholder, such as Chief Comptroller.
**Allowable Values:**
255 char max |
| user.**token**
string
Conditionally returned | Unique identifier of the cardholder.
**Allowable Values:**
1–36 chars |
| user.**uses\_parent\_account**
boolean
Conditionally returned | Indicates whether the child shares balances with the parent (`true`), or the child’s balances are independent of the parent (`false`).
**Allowable Values:**
`true`, `false` |
| user.**zip**
string
Conditionally returned | United States ZIP code of the cardholder’s address.
**Allowable Values:**
10 char max |
| wallet\_provider\_profile
object
Conditionally returned | Contains information held and provided by the digital wallet provider.
**Allowable Values:**
`account`, `device_score`, `pan_source`, `reason_code`, `recommendation_reasons`, `risk_assessment` |
| wallet\_provider\_profile.**account**
object
Conditionally returned | Contains information related to the cardholder and provided by the digital wallet provider.
**Allowable Values:**
`email_address`, `id`, `score` |
| wallet\_provider\_profile.account.**email\_address**
string
Conditionally returned | Digital wallet provider’s email address for the cardholder.
**Allowable Values:**
255 char max |
| wallet\_provider\_profile.account.**id**
string
Conditionally returned | Digital wallet provider’s identity number for the cardholder.
**Allowable Values:**
20 char max |
| wallet\_provider\_profile.account.**score**
string
Conditionally returned | Score from the digital wallet provider.
**Allowable Values:**
50 char max |
| wallet\_provider\_profile.**device\_score**
string
Conditionally returned | Score from the device.
**Allowable Values:**
50 char max |
| wallet\_provider\_profile.**pan\_source**
string
Conditionally returned | Source from which the digital wallet provider obtained the card primary account number (PAN).
**Allowable Values:**
`KEY_ENTERED`, `ON_FILE`, `MOBILE_BANKING_APP` |
| wallet\_provider\_profile.**reason\_code**
string
Conditionally returned | Reason for the wallet provider’s provisioning decision.
- **01** – Cardholder’s wallet account is too new relative to launch.
- **02** – Cardholder’s wallet account is too new relative to provisioning request.
- **03** – Cardholder’s wallet account/card pair is newer than date threshold.
- **04** – Changes made to account data within the account threshold.
- **05** – Suspicious transactions linked to this account.
- **06** – Account has not had activity in the last year.
- **07** – Suspended cards in the secure element.
- **08** – Device was put in lost mode in the last seven days for longer than the duration threshold.
- **09** – The number of provisioning attempts on this device in 24 hours exceeds threshold.
- **0A** – There have been more than the threshold number of different cards attempted at provisioning to this phone in 24 hours.
- **0B** – The card provisioning attempt contains a distinct name in excess of the threshold.
- **0C** – The device score is less than 3.
- **0D** – The account score is less than 4.
- **0E** – Device provisioning location outside of the cardholder’s wallet account home country.
- **0G** – Suspect fraud.
**Allowable Values:**
01, 02, 03, 04, 05, 06, 07, 08, 09, 0A, 0B, 0C, 0D, 0E, 0G |
| wallet\_provider\_profile.**recommendation\_reasons**
array of strings
Conditionally returned | Array of recommendation reasons from the digital wallet provider.
**Allowable Values:**
Valid array of one or more recommendation reasons |
| wallet\_provider\_profile.**risk\_assessment**
object
Conditionally returned | Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token.
**Allowable Values:**
`score`, `version` |
| wallet\_provider\_profile.risk\_assessment.**score**
string
Conditionally returned | Wallet provider’s decision as to whether the digital wallet token should be provisioned.
**Allowable Values:**
`DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN` |
| wallet\_provider\_profile.risk\_assessment.**version**
string
Conditionally returned | Wallet provider’s risk assessment version.
**Allowable Values:**
Version information, as provided by the wallet provider |
Sample response body
```json JSON expandable lines wrap theme={null}
{
"token": "my_token_0000",
"card_token": "my_card_token_1989",
"state": "ACTIVE",
"state_reason": "Card activated by cardholder",
"fulfillment_status": "PROVISIONED",
"issuer_eligibility_decision": "cardaccount.verified",
"created_time": "2025-10-03T18:55:45Z",
"last_modified_time": "2025-01-26T22:36:10Z",
"token_service_provider": {
"token_reference_id": "my_token_reference_id_1600",
"pan_reference_id": "my_pan_reference_id_0073",
"token_requestor_id": "my_token_requestor_id_0373",
"token_requestor_name": "Token Requestor Name",
"token_type": "DEVICE_SECURE_ELEMENT",
"token_score": "02",
"token_eligibility_decision": "DECISION_GREEN"
},
"device": {
"type": "MOBILE_PHONE",
"language_code": "eng",
"device_id": "my_device_id_9575",
"phone_number": "12345678900",
"name": "Phone Name",
"location": "+37.81/-122.26",
"ip_address": "x.x.x.x"
},
"wallet_provider_profile": {
"account": {
"score": "05"
},
"risk_assessment": {
"score": "DECISION_YELLOW",
"version": "0001.00"
},
"device_score": "03",
"pan_source": "KEY_ENTERED"
},
"address_verification": {
"name": "Address Verification Name",
"street_address": "223 Elm Street",
"postal_code": "94703"
}
}
```
List digital wallet tokens for card
**Action:** `GET`\
**Endpoint:** `/digitalwallettokens/card/{card_token}`
{/* */}
Use this endpoint to return an array of all digital wallet tokens for a particular card.
This endpoint supports [pagination](/core-api/sorting-and-pagination/).
URL path parameters
| Fields | Description |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| card\_token
string
Required | Unique identifier of the card. Used to minimize the need to exchange card details during subsequent calls, and also for troubleshooting.
**Allowable Values:**
Existing card token |
URL query parameters
| Fields | Description |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count
integer
Optional | Number of digital wallet token resources to retrieve.
**Allowable Values:**
Any integer
**Default value:**
5 |
| start\_index
integer
Optional | Sort order index of the first digital wallet token resource in the returned array.
**Allowable Values:**
Any integer
**Default value:**
0 |
| 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:**
`-createdTime` |
Response body
| Fields | Description |
| --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count
integer
Conditionally returned | Number of resources returned.
This field is returned if there are resources in your returned array.
**Allowable Values:**
Any integer |
| data
array of objects
Conditionally returned | Array of digital wallet token resources.
Resources are returned as appropriate to your query.
**Allowable Values:**
Valid array of one or more digital wallet token resources |
| data\[].**address\_verification**
object
Conditionally returned | Contains address verification information.
**Allowable Values:**
`name`, `postal_code`, `street_address`, `zip` |
| data\[].address\_verification.**name**
string
Conditionally returned | Name of the cardholder.
**Allowable Values:**
40 char max |
| data\[].address\_verification.**postal\_code**
string
Conditionally returned | Postal code.
**Allowable Values:**
10 char max |
| data\[].address\_verification.**street\_address**
string
Conditionally returned | Street address provided by the cardholder.
**Allowable Values:**
40 char max |
| data\[].address\_verification.**zip**
string
Conditionally returned | United States ZIP code.
**Allowable Values:**
10 char max |
| data\[].**card\_token**
string
Conditionally returned | Unique identifier of the card.
**Allowable Values:**
Existing card token |
| data\[].**created\_time**
datetime
Conditionally returned | Date and time when the digital wallet token object was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].**device**
object
Conditionally returned | Contains information related to the device being provisioned.
**Allowable Values:**
`device_id`, `ip_address`, `language_code`, `location`, `name`, `phone_number`, `token`, `type` |
| data\[].device.**device\_id**
string
Conditionally returned | Identity number of the device.
**Allowable Values:**
24 char max |
| data\[].device.**ip\_address**
string
Conditionally returned | Device’s IP address.
**Allowable Values:**
IP address format, 50 char max |
| data\[].device.**language\_code**
string
Conditionally returned | Language the device is configured to use.
**Allowable Values:**
50 char max |
| data\[].device.**location**
string
Conditionally returned | Geographic coordinates of the device.
**Allowable Values:**
Latitude and longitude in `DDD.DD/DDD.DD` format.
**NOTE:** Both the longitude and latitude are prefixed with either a `+` or `-` symbol, for example: `+42.29/-71.07`. |
| data\[].device.**name**
string
Conditionally returned | Name of the device.
**Allowable Values:**
50 char max |
| data\[].device.**phone\_number**
string
Conditionally returned | Device’s telephone number.
**Allowable Values:**
50 char max |
| data\[].device.**token**
string
Conditionally returned | Unique identifier of the device object.
**Allowable Values:**
36 char max |
| data\[].device.**type**
string
Conditionally returned | Type of device being provisioned.
**Allowable Values:**
`MOBILE_PHONE`, `WATCH`, `TABLET`, `MOBILE_PHONE_OR_TABLET`, `VEHICLE`, `APPLIANCE`, `LAPTOP`, `GAMING_DEVICE`, `WEARABLE_DEVICE`, `UNKNOWN` |
| data\[].**fulfillment\_status**
string
Conditionally returned | Digital wallet token’s provisioning status.
For fulfillment status descriptions, see Create digital wallet token transition.
**Allowable Values:**
`DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN`, `REJECTED`, `PROVISIONED` |
| data\[].**issuer\_eligibility\_decision**
string
Conditionally returned | The Marqeta platform’s decision as to whether the digital wallet token should be provisioned.
- **0000** – The token should be provisioned.
- **token.activation.verification.required** – Provisioning is pending; further action is required for completion.
For all other values, check the value of the `fulfillment_status` field to definitively ascertain the provisioning outcome.
**NOTE:** The value `invalid.cid` indicates an invalid CVV2 number.
**Allowable Values:**
0000, `cardaccount.verified`, `card.suspicious`, `token.activation.verification.required`, `token.activation-request.decline`, `card.not.active`, `invalid.cid`, `card.expired`, `card.suspended`, `cardholder.not.active` |
| data\[].**last\_modified\_time**
datetime
Conditionally returned | Date and time when the digital wallet token object was last modified, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].**metadata**
object
Conditionally returned | Contains additional information about the digital wallet token.
**Allowable Values:**
`cardproduct_preferred_notification_language`, `issuer_product_config_id` |
| data\[].metadata.**cardproduct\_preferred\_notification\_language**
string
Conditionally returned | Language specified in the `config.transaction_controls.notification_language` field of the card product:
- **ces** – Czech
- **deu** – German
- **eng** – English
- **fra** – French
- **ell** – Greek
- **ita** – Italian
- **nld** – Dutch
- **pol** – Polish
- **por** – Portuguese
- **ron** – Romanian
- **spa** – Spanish
- **swe** – Swedish
By default, notifications are sent in English.
The ISO maintains the full list of ISO 3166 two- and three-digit numeric country codes.
**Allowable Values:**
`ces`, `deu`, `eng`, `fra`, `ell`, `ita`, `nld`, `pol`, `por`, `ron`, `spa`, `swe` |
| data\[].metadata.**issuer\_product\_config\_id**
string
Conditionally returned | Unique identifier of the product configuration on the Marqeta platform.
**Allowable Values:**
255 char max |
| data\[].**state**
string
Conditionally returned | State of the digital wallet token.
For state descriptions, see Transitioning Token States.
**Allowable Values:**
`REQUESTED`, `REQUEST_DECLINED`, `ACTIVE`, `SUSPENDED`, `TERMINATED` |
| data\[].**state\_reason**
string
Conditionally returned | Reason why the digital wallet token transitioned to its current state.
**Allowable Values:**
255 char max |
| data\[].**token**
string
Conditionally returned | Unique identifier of the digital wallet token.
**Allowable Values:**
Existing digital wallet token. |
| data\[].**token\_service\_provider**
object
Conditionally returned | Contains information held and provided by the token service provider (card network).
**Allowable Values:**
`correlation_id`, `pan_reference_id`, `token_assurance_level`, `token_eligibility_decision`, `token_expiration`, `token_pan`, `token_reference_id`, `token_requestor_id`, `token_requestor_name`, `token_score`, `token_type` |
| data\[].token\_service\_provider.**correlation\_id**
string
Conditionally returned | For Mastercard only. Unique value representing a tokenization request.
**Allowable Values:**
Existing correlation identifier |
| data\[].token\_service\_provider.**pan\_reference\_id**
string
Conditionally returned | Unique identifier of the digital wallet token primary account number (PAN) within the card network.
**Allowable Values:**
Existing PAN Reference ID |
| data\[].token\_service\_provider.**token\_assurance\_level**
string
Conditionally returned | For Mastercard only. Represents the confidence level in the digital wallet token.
**Allowable Values:**
0-99 |
| data\[].token\_service\_provider.**token\_eligibility\_decision**
string
Conditionally returned | Digital wallet’s decision as to whether the digital wallet token should be provisioned.
**Allowable Values:**
`DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN` |
| data\[].token\_service\_provider.**token\_expiration**
string
Conditionally returned | Expiration date of the digital wallet token.
**Allowable Values:**
Format: MMyy |
| data\[].token\_service\_provider.**token\_pan**
string
Conditionally returned | Primary account number (PAN) of the digital wallet token.
**Allowable Values:**
16 char max |
| data\[].token\_service\_provider.**token\_reference\_id**
string
Conditionally returned | Unique identifier of the digital wallet token within the card network.
**Allowable Values:**
Existing Token Reference ID |
| data\[].token\_service\_provider.**token\_requestor\_id**
string
Conditionally returned | Unique numerical identifier of the token requestor within the card network. These ID numbers map to `token_requestor_name` field values as follows:
**Mastercard**
- 50110030273 – `APPLE_PAY`
- 50120834693 – `ANDROID_PAY`
- 50139059239 – `SAMSUNG_PAY`
**Visa**
- 40010030273 – `APPLE_PAY`
- 40010075001 – `ANDROID_PAY`
- 40010043095 – `SAMSUNG_PAY`
- 40010075196 – `MICROSOFT_PAY`
- 40010075338 – `VISA_CHECKOUT`
- 40010075449 – `FACEBOOK`
- 40010075839 – `NETFLIX`
- 40010077056 – `FITBIT_PAY`
- 40010069887 – `GARMIN_PAY`
**Allowable Values:**
11 char max
**Example Values:**
- **Mastercard** – 50110030273, 50120834693, 50139059239
- **Visa** – 40010030273, 40010075001, 40010075338, 40010075449, 40010075839, 40010043095 |
| data\[].token\_service\_provider.**token\_requestor\_name**
string
Conditionally returned | 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` |
| data\[].token\_service\_provider.**token\_score**
string
Conditionally returned | Token score assigned by the digital wallet.
**Allowable Values:**
25 char max |
| data\[].token\_service\_provider.**token\_type**
string
Conditionally returned | Type of the digital wallet token.
**Allowable Values:**
`MERCHANT_CARD_ON_FILE`, `DEVICE_SECURE_ELEMENT`, `DEVICE_CLOUD_BASED`, `ECOMMERCE_DIGITAL_WALLET` |
| data\[].**transaction\_device**
object
Conditionally returned | Contains information about the device used in the transaction to enhance the risk decisioning process. Use this data to improve fraud prevention and dispute resolution.
**Allowable Values:**
`binding_id`, `ip_address`, `location`, `phone_number` |
| data\[].transaction\_device.**binding\_id**
string
Conditionally returned | Unique identifier of the data component bound to the credential.
**Allowable Values:**
48 char max |
| data\[].transaction\_device.**ip\_address**
string
Conditionally returned | IP address of the device. The presence of the IP address helps determine if the transaction was initiated from an unusual network, helping establish a pattern of safe device usage that further confirms the authenticity of the consumer who initiated the transaction.
**Allowable Values:**
IP address format, 39 char max |
| data\[].transaction\_device.**location**
string
Conditionally returned | Geographic coordinates of the device. Contains the latitude and longitude of the device used when the cardholder was authenticated during checkout. This field helps to determine if the transaction was initiated from an unexpected location.
**Allowable Values:**
Latitude and longitude in `DDD.DD/DDD.DD` format. |
| data\[].transaction\_device.**phone\_number**
string
Conditionally returned | Telephone number of the device. Contains the phone number that was used to authenticate the consumer during checkout, or the consumer’s preferred phone number. The presence of the phone number helps establish the consumer’s authenticity when matching the phone number provided during checkout to a list of known phone numbers for the consumer.
**Allowable Values:**
15 char max |
| data\[].**user**
object
Conditionally returned | Contains information about a cardholder.
**Allowable Values:**
`account_holder_group_token`, `active`, `address1`, `address2`, `authentication`, `birth_date`, `birth_place`, `business_token`, `city`, `company`, `corporate_card_holder`, `country`, `created_time`, `email`, `first_name`, `gender`, `honorific`, `id_card_expiration_date`, `id_card_number`, `identifications`, `ip_address`, `last_modified_time`, `last_name`, `metadata`, `middle_name`, `nationality`, `notes`, `parent_token`, `passport_expiration_date`, `passport_number`, `password`, `phone`, `postal_code`, `ssn`, `state`, `status`, `title`, `token`, `uses_parent_account`, `zip` |
| data\[].user.**account\_holder\_group\_token**
string
Conditionally returned | Associates the specified account holder group with the cardholder.
**Allowable Values:**
36 char max |
| data\[].user.**active**
boolean
Conditionally returned | Specifies if the cardholder is in the `ACTIVE` state on the Marqeta platform.
**Allowable Values:**
`true`, `false` |
| data\[].user.**address1**
string
Conditionally returned | Cardholder’s address.
**Allowable Values:**
255 char max |
| data\[].user.**address2**
string
Conditionally returned | Additional address information for the cardholder.
**Allowable Values:**
255 char max |
| data\[].user.**authentication**
object
Conditionally returned | Contains the cardholder’s email address and password information.
**Allowable Values:**
`email_verified`, `email_verified_time`, `last_password_update_channel`, `last_password_update_time` |
| data\[].user.authentication.**email\_verified**
boolean
Conditionally returned | Specifies whether the email address has been verified.
**Allowable Values:**
`true`, `false` |
| data\[].user.authentication.**email\_verified\_time**
datetime
Conditionally returned | Date and time when the email address was verified.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].user.authentication.**last\_password\_update\_channel**
string
Conditionally returned | Specifies the channel through which the password was last changed.
**Allowable Values:**
`USER_CHANGE`, `USER_RESET` |
| data\[].user.authentication.**last\_password\_update\_time**
datetime
Conditionally returned | Date and time when the password was last changed.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].user.**birth\_date**
string
Conditionally returned | Cardholder’s date of birth.
**Allowable Values:**
Format: yyyy-MM-dd |
| data\[].user.**birth\_place**
string
Conditionally returned | Country where the cardholder was born.
**Allowable Values:**
255 char max
ISO 3166 two-character country codes. For example, the country code for the United States is `US`.
The ISO maintains the full list of ISO-3166 country codes. |
| data\[].user.**business\_token**
string
Conditionally returned | Unique identifier of the business resource.
**Allowable Values:**
Existing business resource token |
| data\[].user.**city**
string
Conditionally returned | City where the cardholder resides.
**Allowable Values:**
40 char max |
| data\[].user.**company**
string
Conditionally returned | Company name.
**Allowable Values:**
255 char max |
| data\[].user.**corporate\_card\_holder**
boolean
Conditionally returned | Specifies if the cardholder holds a corporate card.
**Allowable Values:**
`true`, `false` |
| data\[].user.**country**
string
Conditionally returned | Country where the cardholder resides.
**Allowable Values:**
40 char max |
| data\[].user.**created\_time**
datetime
Returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].user.**email**
string
Conditionally returned | Valid email address of the cardholder.
**Allowable Values:**
1–255 chars |
| data\[].user.**first\_name**
string
Conditionally returned | Cardholder’s first name.
**Allowable Values:**
40 char max |
| data\[].user.**gender**
string
Conditionally returned | Gender of the cardholder.
**Allowable Values:**
`F`, `M` |
| data\[].user.**honorific**
string
Conditionally returned | Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on.
**Allowable Values:**
10 char max |
| data\[].user.**id\_card\_expiration\_date**
string
Conditionally returned | Expiration date of the cardholder’s identification.
**Allowable Values:**
Format: yyyy-MM-dd |
| data\[].user.**id\_card\_number**
string
Conditionally returned | Cardholder’s identification card number.
**Allowable Values:**
255 char max |
| data\[].user.**identifications**
array of objects
Conditionally returned | One or more objects containing identifications associated with the cardholder.
**Allowable Values:**
Valid array of one or more `identifications` objects |
| data\[].user.identifications\[].**expiration\_date**
string
Conditionally returned | Expiration date of the identification, if applicable.
**Allowable Values:**
Format: yyyy-MM-dd |
| data\[].user.identifications\[].**type**
string
Conditionally returned | Type of identification.
**Allowable Values:**
`SSN`, `TIN`, `SIN`, `NIN`, `PASSPORT_NUMBER`, `DRIVERS_LICENSE`, `BUSINESS_NUMBER`, `BUSINESS_TAX_ID`, `TAXPAYER_REFERENCE` |
| data\[].user.identifications\[].**value**
string
Conditionally returned | Number associated with the identification.
**Allowable Values:**
255 char max |
| data\[].user.**ip\_address**
string
Conditionally returned | Cardholder’s IP address.
**Allowable Values:**
39 char max |
| data\[].user.**last\_modified\_time**
datetime
Returned | Date and time when the resource was last updated, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| data\[].user.**last\_name**
string
Conditionally returned | Cardholder’s last name.
**Allowable Values:**
40 char max |
| data\[].user.**metadata**
object
Conditionally returned | Associates any additional metadata you provide with the cardholder.
**Allowable Values:**
You can define the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"` |
| data\[].user.**middle\_name**
string
Conditionally returned | Cardholder’s middle name.
**Allowable Values:**
40 char max |
| data\[].user.**nationality**
string
Conditionally returned | Cardholder’s nationality.
**Allowable Values:**
255 char max |
| data\[].user.**notes**
string
Conditionally returned | Any additional information pertaining to the cardholder.
**Allowable Values:**
255 char max |
| data\[].user.**parent\_token**
string
Conditionally returned | Unique identifier of the parent user or business resource.
**Allowable Values:**
1–36 chars |
| data\[].user.**passport\_expiration\_date**
string
Conditionally returned | Expiration date of the cardholder’s passport.
**Allowable Values:**
Format: yyyy-MM-dd |
| data\[].user.**passport\_number**
string
Conditionally returned | Cardholder’s passport number.
**Allowable Values:**
40 char max |
| data\[].user.**password**
string
Conditionally returned | Password to the cardholder’s user account on the Marqeta platform.
**Allowable Values:**
1–255 chars |
| data\[].user.**phone**
string
Conditionally returned | Cardholder’s telephone number.
**Allowable Values:**
255 char max |
| data\[].user.**postal\_code**
string
Conditionally returned | Postal code of the cardholder’s address.
**Allowable Values:**
10 char max |
| data\[].user.**ssn**
string
Conditionally returned | Cardholder’s Social Security Number (SSN).
**Allowable Values:**
Nine digits only, no delimiters. |
| data\[].user.**state**
string
Conditionally returned | State or province where the cardholder resides.
**Allowable Values:**
2 char max |
| data\[].user.**status**
string
Conditionally returned | Specifies the status of the cardholder on the Marqeta platform.
**Allowable Values:**
`UNVERIFIED`, `LIMITED`, `ACTIVE`, `SUSPENDED`, `CLOSED` |
| data\[].user.**title**
string
Conditionally returned | Professional title of the cardholder, such as Chief Comptroller.
**Allowable Values:**
255 char max |
| data\[].user.**token**
string
Conditionally returned | Unique identifier of the cardholder.
**Allowable Values:**
1–36 chars |
| data\[].user.**uses\_parent\_account**
boolean
Conditionally returned | Indicates whether the child shares balances with the parent (`true`), or the child’s balances are independent of the parent (`false`).
**Allowable Values:**
`true`, `false` |
| data\[].user.**zip**
string
Conditionally returned | United States ZIP code of the cardholder’s address.
**Allowable Values:**
10 char max |
| data\[].**wallet\_provider\_profile**
object
Conditionally returned | Contains information held and provided by the digital wallet provider.
**Allowable Values:**
`account`, `device_score`, `pan_source`, `reason_code`, `recommendation_reasons`, `risk_assessment` |
| data\[].wallet\_provider\_profile.**account**
object
Conditionally returned | Contains information related to the cardholder and provided by the digital wallet provider.
**Allowable Values:**
`email_address`, `id`, `score` |
| data\[].wallet\_provider\_profile.account.**email\_address**
string
Conditionally returned | Digital wallet provider’s email address for the cardholder.
**Allowable Values:**
255 char max |
| data\[].wallet\_provider\_profile.account.**id**
string
Conditionally returned | Digital wallet provider’s identity number for the cardholder.
**Allowable Values:**
20 char max |
| data\[].wallet\_provider\_profile.account.**score**
string
Conditionally returned | Score from the digital wallet provider.
**Allowable Values:**
50 char max |
| data\[].wallet\_provider\_profile.**device\_score**
string
Conditionally returned | Score from the device.
**Allowable Values:**
50 char max |
| data\[].wallet\_provider\_profile.**pan\_source**
string
Conditionally returned | Source from which the digital wallet provider obtained the card primary account number (PAN).
**Allowable Values:**
`KEY_ENTERED`, `ON_FILE`, `MOBILE_BANKING_APP` |
| data\[].wallet\_provider\_profile.**reason\_code**
string
Conditionally returned | Reason for the wallet provider’s provisioning decision.
- **01** – Cardholder’s wallet account is too new relative to launch.
- **02** – Cardholder’s wallet account is too new relative to provisioning request.
- **03** – Cardholder’s wallet account/card pair is newer than date threshold.
- **04** – Changes made to account data within the account threshold.
- **05** – Suspicious transactions linked to this account.
- **06** – Account has not had activity in the last year.
- **07** – Suspended cards in the secure element.
- **08** – Device was put in lost mode in the last seven days for longer than the duration threshold.
- **09** – The number of provisioning attempts on this device in 24 hours exceeds threshold.
- **0A** – There have been more than the threshold number of different cards attempted at provisioning to this phone in 24 hours.
- **0B** – The card provisioning attempt contains a distinct name in excess of the threshold.
- **0C** – The device score is less than 3.
- **0D** – The account score is less than 4.
- **0E** – Device provisioning location outside of the cardholder’s wallet account home country.
- **0G** – Suspect fraud.
**Allowable Values:**
01, 02, 03, 04, 05, 06, 07, 08, 09, 0A, 0B, 0C, 0D, 0E, 0G |
| data\[].wallet\_provider\_profile.**recommendation\_reasons**
array of strings
Conditionally returned | Array of recommendation reasons from the digital wallet provider.
**Allowable Values:**
Valid array of one or more recommendation reasons |
| data\[].wallet\_provider\_profile.**risk\_assessment**
object
Conditionally returned | Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token.
**Allowable Values:**
`score`, `version` |
| data\[].wallet\_provider\_profile.risk\_assessment.**score**
string
Conditionally returned | Wallet provider’s decision as to whether the digital wallet token should be provisioned.
**Allowable Values:**
`DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN` |
| data\[].wallet\_provider\_profile.risk\_assessment.**version**
string
Conditionally returned | Wallet provider’s risk assessment version.
**Allowable Values:**
Version information, as provided by the wallet provider |
| end\_index
integer
Conditionally 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` |
| start\_index
integer
Conditionally 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 |
Sample response body
```json JSON expandable lines wrap theme={null}
{
"count": 1,
"start_index": 0,
"end_index": 0,
"is_more": true,
"data": [
{
"token": "my_token_0000",
"card_token": "my_card_token_1989",
"state": "ACTIVE",
"state_reason": "Card activated by cardholder",
"fulfillment_status": "PROVISIONED",
"issuer_eligibility_decision": "cardaccount.verified",
"created_time": "2025-10-03T18:55:45Z",
"last_modified_time": "2025-01-26T22:36:10Z",
"token_service_provider": {
"token_reference_id": "my_token_reference_id_1600",
"pan_reference_id": "my_pan_reference_id_0073",
"token_requestor_id": "my_token_requestor_id_0373",
"token_requestor_name": "Token Requestor Name",
"token_type": "DEVICE_SECURE_ELEMENT",
"token_score": "02",
"token_eligibility_decision": "DECISION_GREEN"
},
"device": {
"type": "MOBILE_PHONE",
"language_code": "eng",
"device_id": "my_device_id_9575",
"phone_number": "12345678900",
"name": "Phone Name",
"location": "+37.81/-122.26",
"ip_address": "x.x.x.x"
},
"wallet_provider_profile": {
"account": {
"score": "05"
},
"risk_assessment": {
"score": "DECISION_YELLOW",
"version": "0001.00"
},
"device_score": "03",
"pan_source": "KEY_ENTERED"
},
"address_verification": {
"name": "Address Verification Name",
"street_address": "223 Elm Street",
"postal_code": "94703"
}
}
]
}
```
Retrieve digital wallet token PAN
**Action:** `GET`\
**Endpoint:** `/digitalwallettokens/{token}/showtokenpan`
{/* */}
Use this 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}`.)
**Warning**\
Sending a request to this endpoint requires PCI DSS compliance. You must comply with PCI DSS data security requirements if you want to store, transmit, or process sensitive card data such as the cardholder’s primary account number (PAN), personal identification number (PIN), and card expiration date.
URL path parameters
| Fields | Description |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| token
string
Required | Unique identifier of the digital wallet token (DWT).
**Allowable Values:**
Existing DWT token |
Response body
| Fields | Description |
| ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| address\_verification
object
Conditionally returned | Contains address verification information.
**Allowable Values:**
`name`, `postal_code`, `street_address`, `zip` |
| address\_verification.**name**
string
Conditionally returned | Name of the cardholder.
**Allowable Values:**
40 char max |
| address\_verification.**postal\_code**
string
Conditionally returned | Postal code.
**Allowable Values:**
10 char max |
| address\_verification.**street\_address**
string
Conditionally returned | Street address provided by the cardholder.
**Allowable Values:**
40 char max |
| address\_verification.**zip**
string
Conditionally returned | United States ZIP code.
**Allowable Values:**
10 char max |
| card\_token
string
Conditionally returned | Unique identifier of the card.
**Allowable Values:**
Existing card token |
| created\_time
datetime
Conditionally returned | Date and time when the digital wallet token object was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| device
object
Conditionally returned | Contains information related to the device being provisioned.
**Allowable Values:**
`device_id`, `ip_address`, `language_code`, `location`, `name`, `phone_number`, `token`, `type` |
| device.**device\_id**
string
Conditionally returned | Identity number of the device.
**Allowable Values:**
24 char max |
| device.**ip\_address**
string
Conditionally returned | Device’s IP address.
**Allowable Values:**
IP address format, 50 char max |
| device.**language\_code**
string
Conditionally returned | Language the device is configured to use.
**Allowable Values:**
50 char max |
| device.**location**
string
Conditionally returned | Geographic coordinates of the device.
**Allowable Values:**
Latitude and longitude in `DDD.DD/DDD.DD` format.
**NOTE:** Both the longitude and latitude are prefixed with either a `+` or `-` symbol, for example: `+42.29/-71.07`. |
| device.**name**
string
Conditionally returned | Name of the device.
**Allowable Values:**
50 char max |
| device.**phone\_number**
string
Conditionally returned | Device’s telephone number.
**Allowable Values:**
50 char max |
| device.**token**
string
Conditionally returned | Unique identifier of the device object.
**Allowable Values:**
36 char max |
| device.**type**
string
Conditionally returned | Type of device being provisioned.
**Allowable Values:**
`MOBILE_PHONE`, `WATCH`, `TABLET`, `MOBILE_PHONE_OR_TABLET`, `VEHICLE`, `APPLIANCE`, `LAPTOP`, `GAMING_DEVICE`, `WEARABLE_DEVICE`, `UNKNOWN` |
| fulfillment\_status
string
Conditionally returned | Digital wallet token’s provisioning status.
For fulfillment status descriptions, see Create digital wallet token transition.
**Allowable Values:**
`DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN`, `REJECTED`, `PROVISIONED` |
| issuer\_eligibility\_decision
string
Conditionally returned | The Marqeta platform’s decision as to whether the digital wallet token should be provisioned.
- **0000** – The token should be provisioned.
- **token.activation.verification.required** – Provisioning is pending; further action is required for completion.
For all other values, check the value of the `fulfillment_status` field to definitively ascertain the provisioning outcome.
**NOTE:** The value `invalid.cid` indicates an invalid CVV2 number.
**Allowable Values:**
0000, `cardaccount.verified`, `card.suspicious`, `token.activation.verification.required`, `token.activation-request.decline`, `card.not.active`, `invalid.cid`, `card.expired`, `card.suspended`, `cardholder.not.active` |
| last\_modified\_time
datetime
Conditionally returned | Date and time when the digital wallet token object was last modified, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| metadata
object
Conditionally returned | Contains additional information about the digital wallet token.
**Allowable Values:**
`cardproduct_preferred_notification_language`, `issuer_product_config_id` |
| metadata.**cardproduct\_preferred\_notification\_language**
string
Conditionally returned | Language specified in the `config.transaction_controls.notification_language` field of the card product:
- **ces** – Czech
- **deu** – German
- **eng** – English
- **fra** – French
- **ell** – Greek
- **ita** – Italian
- **nld** – Dutch
- **pol** – Polish
- **por** – Portuguese
- **ron** – Romanian
- **spa** – Spanish
- **swe** – Swedish
By default, notifications are sent in English.
The ISO maintains the full list of ISO 3166 two- and three-digit numeric country codes.
**Allowable Values:**
`ces`, `deu`, `eng`, `fra`, `ell`, `ita`, `nld`, `pol`, `por`, `ron`, `spa`, `swe` |
| metadata.**issuer\_product\_config\_id**
string
Conditionally returned | Unique identifier of the product configuration on the Marqeta platform.
**Allowable Values:**
255 char max |
| state
string
Conditionally returned | State of the digital wallet token.
For state descriptions, see Transitioning Token States.
**Allowable Values:**
`REQUESTED`, `REQUEST_DECLINED`, `ACTIVE`, `SUSPENDED`, `TERMINATED` |
| state\_reason
string
Conditionally returned | Reason why the digital wallet token transitioned to its current state.
**Allowable Values:**
255 char max |
| token
string
Conditionally returned | Unique identifier of the digital wallet token.
**Allowable Values:**
Existing digital wallet token. |
| token\_service\_provider
object
Conditionally returned | Contains information held and provided by the token service provider (card network).
**Allowable Values:**
`correlation_id`, `pan_reference_id`, `token_assurance_level`, `token_eligibility_decision`, `token_expiration`, `token_pan`, `token_reference_id`, `token_requestor_id`, `token_requestor_name`, `token_score`, `token_type` |
| token\_service\_provider.**correlation\_id**
string
Conditionally returned | For Mastercard only. Unique value representing a tokenization request.
**Allowable Values:**
Existing correlation identifier |
| token\_service\_provider.**pan\_reference\_id**
string
Conditionally returned | Unique identifier of the digital wallet token primary account number (PAN) within the card network.
**Allowable Values:**
Existing PAN Reference ID |
| token\_service\_provider.**token\_assurance\_level**
string
Conditionally returned | For Mastercard only. Represents the confidence level in the digital wallet token.
**Allowable Values:**
0-99 |
| token\_service\_provider.**token\_eligibility\_decision**
string
Conditionally returned | Digital wallet’s decision as to whether the digital wallet token should be provisioned.
**Allowable Values:**
`DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN` |
| token\_service\_provider.**token\_expiration**
string
Conditionally returned | Expiration date of the digital wallet token.
**Allowable Values:**
Format: MMyy |
| token\_service\_provider.**token\_pan**
string
Conditionally returned | Primary account number (PAN) of the digital wallet token.
**Allowable Values:**
16 char max |
| token\_service\_provider.**token\_reference\_id**
string
Conditionally returned | Unique identifier of the digital wallet token within the card network.
**Allowable Values:**
Existing Token Reference ID |
| token\_service\_provider.**token\_requestor\_id**
string
Conditionally returned | Unique numerical identifier of the token requestor within the card network. These ID numbers map to `token_requestor_name` field values as follows:
**Mastercard**
- 50110030273 – `APPLE_PAY`
- 50120834693 – `ANDROID_PAY`
- 50139059239 – `SAMSUNG_PAY`
**Visa**
- 40010030273 – `APPLE_PAY`
- 40010075001 – `ANDROID_PAY`
- 40010043095 – `SAMSUNG_PAY`
- 40010075196 – `MICROSOFT_PAY`
- 40010075338 – `VISA_CHECKOUT`
- 40010075449 – `FACEBOOK`
- 40010075839 – `NETFLIX`
- 40010077056 – `FITBIT_PAY`
- 40010069887 – `GARMIN_PAY`
**Allowable Values:**
11 char max
**Example Values:**
- **Mastercard** – 50110030273, 50120834693, 50139059239
- **Visa** – 40010030273, 40010075001, 40010075338, 40010075449, 40010075839, 40010043095 |
| token\_service\_provider.**token\_requestor\_name**
string
Conditionally returned | 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` |
| token\_service\_provider.**token\_score**
string
Conditionally returned | Token score assigned by the digital wallet.
**Allowable Values:**
25 char max |
| token\_service\_provider.**token\_type**
string
Conditionally returned | Type of the digital wallet token.
**Allowable Values:**
`MERCHANT_CARD_ON_FILE`, `DEVICE_SECURE_ELEMENT`, `DEVICE_CLOUD_BASED`, `ECOMMERCE_DIGITAL_WALLET` |
| transaction\_device
object
Conditionally returned | Contains information about the device used in the transaction to enhance the risk decisioning process. Use this data to improve fraud prevention and dispute resolution.
**Allowable Values:**
`binding_id`, `ip_address`, `location`, `phone_number` |
| transaction\_device.**binding\_id**
string
Conditionally returned | Unique identifier of the data component bound to the credential.
**Allowable Values:**
48 char max |
| transaction\_device.**ip\_address**
string
Conditionally returned | IP address of the device. The presence of the IP address helps determine if the transaction was initiated from an unusual network, helping establish a pattern of safe device usage that further confirms the authenticity of the consumer who initiated the transaction.
**Allowable Values:**
IP address format, 39 char max |
| transaction\_device.**location**
string
Conditionally returned | Geographic coordinates of the device. Contains the latitude and longitude of the device used when the cardholder was authenticated during checkout. This field helps to determine if the transaction was initiated from an unexpected location.
**Allowable Values:**
Latitude and longitude in `DDD.DD/DDD.DD` format. |
| transaction\_device.**phone\_number**
string
Conditionally returned | Telephone number of the device. Contains the phone number that was used to authenticate the consumer during checkout, or the consumer’s preferred phone number. The presence of the phone number helps establish the consumer’s authenticity when matching the phone number provided during checkout to a list of known phone numbers for the consumer.
**Allowable Values:**
15 char max |
| user
object
Conditionally returned | Contains information about a cardholder.
**Allowable Values:**
`account_holder_group_token`, `active`, `address1`, `address2`, `authentication`, `birth_date`, `birth_place`, `business_token`, `city`, `company`, `corporate_card_holder`, `country`, `created_time`, `email`, `first_name`, `gender`, `honorific`, `id_card_expiration_date`, `id_card_number`, `identifications`, `ip_address`, `last_modified_time`, `last_name`, `metadata`, `middle_name`, `nationality`, `notes`, `parent_token`, `passport_expiration_date`, `passport_number`, `password`, `phone`, `postal_code`, `ssn`, `state`, `status`, `title`, `token`, `uses_parent_account`, `zip` |
| user.**account\_holder\_group\_token**
string
Conditionally returned | Associates the specified account holder group with the cardholder.
**Allowable Values:**
36 char max |
| user.**active**
boolean
Conditionally returned | Specifies if the cardholder is in the `ACTIVE` state on the Marqeta platform.
**Allowable Values:**
`true`, `false` |
| user.**address1**
string
Conditionally returned | Cardholder’s address.
**Allowable Values:**
255 char max |
| user.**address2**
string
Conditionally returned | Additional address information for the cardholder.
**Allowable Values:**
255 char max |
| user.**authentication**
object
Conditionally returned | Contains the cardholder’s email address and password information.
**Allowable Values:**
`email_verified`, `email_verified_time`, `last_password_update_channel`, `last_password_update_time` |
| user.authentication.**email\_verified**
boolean
Conditionally returned | Specifies whether the email address has been verified.
**Allowable Values:**
`true`, `false` |
| user.authentication.**email\_verified\_time**
datetime
Conditionally returned | Date and time when the email address was verified.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| user.authentication.**last\_password\_update\_channel**
string
Conditionally returned | Specifies the channel through which the password was last changed.
**Allowable Values:**
`USER_CHANGE`, `USER_RESET` |
| user.authentication.**last\_password\_update\_time**
datetime
Conditionally returned | Date and time when the password was last changed.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| user.**birth\_date**
string
Conditionally returned | Cardholder’s date of birth.
**Allowable Values:**
Format: yyyy-MM-dd |
| user.**birth\_place**
string
Conditionally returned | Country where the cardholder was born.
**Allowable Values:**
255 char max
ISO 3166 two-character country codes. For example, the country code for the United States is `US`.
The ISO maintains the full list of ISO-3166 country codes. |
| user.**business\_token**
string
Conditionally returned | Unique identifier of the business resource.
**Allowable Values:**
Existing business resource token |
| user.**city**
string
Conditionally returned | City where the cardholder resides.
**Allowable Values:**
40 char max |
| user.**company**
string
Conditionally returned | Company name.
**Allowable Values:**
255 char max |
| user.**corporate\_card\_holder**
boolean
Conditionally returned | Specifies if the cardholder holds a corporate card.
**Allowable Values:**
`true`, `false` |
| user.**country**
string
Conditionally returned | Country where the cardholder resides.
**Allowable Values:**
40 char max |
| user.**created\_time**
datetime
Returned | Date and time when the resource was created, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| user.**email**
string
Conditionally returned | Valid email address of the cardholder.
**Allowable Values:**
1–255 chars |
| user.**first\_name**
string
Conditionally returned | Cardholder’s first name.
**Allowable Values:**
40 char max |
| user.**gender**
string
Conditionally returned | Gender of the cardholder.
**Allowable Values:**
`F`, `M` |
| user.**honorific**
string
Conditionally returned | Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on.
**Allowable Values:**
10 char max |
| user.**id\_card\_expiration\_date**
string
Conditionally returned | Expiration date of the cardholder’s identification.
**Allowable Values:**
Format: yyyy-MM-dd |
| user.**id\_card\_number**
string
Conditionally returned | Cardholder’s identification card number.
**Allowable Values:**
255 char max |
| user.**identifications**
array of objects
Conditionally returned | One or more objects containing identifications associated with the cardholder.
**Allowable Values:**
Valid array of one or more `identifications` objects |
| user.identifications\[].**expiration\_date**
string
Conditionally returned | Expiration date of the identification, if applicable.
**Allowable Values:**
Format: yyyy-MM-dd |
| user.identifications\[].**type**
string
Conditionally returned | Type of identification.
**Allowable Values:**
`SSN`, `TIN`, `SIN`, `NIN`, `PASSPORT_NUMBER`, `DRIVERS_LICENSE`, `BUSINESS_NUMBER`, `BUSINESS_TAX_ID`, `TAXPAYER_REFERENCE` |
| user.identifications\[].**value**
string
Conditionally returned | Number associated with the identification.
**Allowable Values:**
255 char max |
| user.**ip\_address**
string
Conditionally returned | Cardholder’s IP address.
**Allowable Values:**
39 char max |
| user.**last\_modified\_time**
datetime
Returned | Date and time when the resource was last updated, in UTC.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ssZ |
| user.**last\_name**
string
Conditionally returned | Cardholder’s last name.
**Allowable Values:**
40 char max |
| user.**metadata**
object
Conditionally returned | Associates any additional metadata you provide with the cardholder.
**Allowable Values:**
You can define the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"` |
| user.**middle\_name**
string
Conditionally returned | Cardholder’s middle name.
**Allowable Values:**
40 char max |
| user.**nationality**
string
Conditionally returned | Cardholder’s nationality.
**Allowable Values:**
255 char max |
| user.**notes**
string
Conditionally returned | Any additional information pertaining to the cardholder.
**Allowable Values:**
255 char max |
| user.**parent\_token**
string
Conditionally returned | Unique identifier of the parent user or business resource.
**Allowable Values:**
1–36 chars |
| user.**passport\_expiration\_date**
string
Conditionally returned | Expiration date of the cardholder’s passport.
**Allowable Values:**
Format: yyyy-MM-dd |
| user.**passport\_number**
string
Conditionally returned | Cardholder’s passport number.
**Allowable Values:**
40 char max |
| user.**password**
string
Conditionally returned | Password to the cardholder’s user account on the Marqeta platform.
**Allowable Values:**
1–255 chars |
| user.**phone**
string
Conditionally returned | Cardholder’s telephone number.
**Allowable Values:**
255 char max |
| user.**postal\_code**
string
Conditionally returned | Postal code of the cardholder’s address.
**Allowable Values:**
10 char max |
| user.**ssn**
string
Conditionally returned | Cardholder’s Social Security Number (SSN).
**Allowable Values:**
Nine digits only, no delimiters. |
| user.**state**
string
Conditionally returned | State or province where the cardholder resides.
**Allowable Values:**
2 char max |
| user.**status**
string
Conditionally returned | Specifies the status of the cardholder on the Marqeta platform.
**Allowable Values:**
`UNVERIFIED`, `LIMITED`, `ACTIVE`, `SUSPENDED`, `CLOSED` |
| user.**title**
string
Conditionally returned | Professional title of the cardholder, such as Chief Comptroller.
**Allowable Values:**
255 char max |
| user.**token**
string
Conditionally returned | Unique identifier of the cardholder.
**Allowable Values:**
1–36 chars |
| user.**uses\_parent\_account**
boolean
Conditionally returned | Indicates whether the child shares balances with the parent (`true`), or the child’s balances are independent of the parent (`false`).
**Allowable Values:**
`true`, `false` |
| user.**zip**
string
Conditionally returned | United States ZIP code of the cardholder’s address.
**Allowable Values:**
10 char max |
| wallet\_provider\_profile
object
Conditionally returned | Contains information held and provided by the digital wallet provider.
**Allowable Values:**
`account`, `device_score`, `pan_source`, `reason_code`, `recommendation_reasons`, `risk_assessment` |
| wallet\_provider\_profile.**account**
object
Conditionally returned | Contains information related to the cardholder and provided by the digital wallet provider.
**Allowable Values:**
`email_address`, `id`, `score` |
| wallet\_provider\_profile.account.**email\_address**
string
Conditionally returned | Digital wallet provider’s email address for the cardholder.
**Allowable Values:**
255 char max |
| wallet\_provider\_profile.account.**id**
string
Conditionally returned | Digital wallet provider’s identity number for the cardholder.
**Allowable Values:**
20 char max |
| wallet\_provider\_profile.account.**score**
string
Conditionally returned | Score from the digital wallet provider.
**Allowable Values:**
50 char max |
| wallet\_provider\_profile.**device\_score**
string
Conditionally returned | Score from the device.
**Allowable Values:**
50 char max |
| wallet\_provider\_profile.**pan\_source**
string
Conditionally returned | Source from which the digital wallet provider obtained the card primary account number (PAN).
**Allowable Values:**
`KEY_ENTERED`, `ON_FILE`, `MOBILE_BANKING_APP` |
| wallet\_provider\_profile.**reason\_code**
string
Conditionally returned | Reason for the wallet provider’s provisioning decision.
- **01** – Cardholder’s wallet account is too new relative to launch.
- **02** – Cardholder’s wallet account is too new relative to provisioning request.
- **03** – Cardholder’s wallet account/card pair is newer than date threshold.
- **04** – Changes made to account data within the account threshold.
- **05** – Suspicious transactions linked to this account.
- **06** – Account has not had activity in the last year.
- **07** – Suspended cards in the secure element.
- **08** – Device was put in lost mode in the last seven days for longer than the duration threshold.
- **09** – The number of provisioning attempts on this device in 24 hours exceeds threshold.
- **0A** – There have been more than the threshold number of different cards attempted at provisioning to this phone in 24 hours.
- **0B** – The card provisioning attempt contains a distinct name in excess of the threshold.
- **0C** – The device score is less than 3.
- **0D** – The account score is less than 4.
- **0E** – Device provisioning location outside of the cardholder’s wallet account home country.
- **0G** – Suspect fraud.
**Allowable Values:**
01, 02, 03, 04, 05, 06, 07, 08, 09, 0A, 0B, 0C, 0D, 0E, 0G |
| wallet\_provider\_profile.**recommendation\_reasons**
array of strings
Conditionally returned | Array of recommendation reasons from the digital wallet provider.
**Allowable Values:**
Valid array of one or more recommendation reasons |
| wallet\_provider\_profile.**risk\_assessment**
object
Conditionally returned | Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token.
**Allowable Values:**
`score`, `version` |
| wallet\_provider\_profile.risk\_assessment.**score**
string
Conditionally returned | Wallet provider’s decision as to whether the digital wallet token should be provisioned.
**Allowable Values:**
`DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN` |
| wallet\_provider\_profile.risk\_assessment.**version**
string
Conditionally returned | Wallet provider’s risk assessment version.
**Allowable Values:**
Version information, as provided by the wallet provider |
Sample response body
```json JSON expandable lines wrap theme={null}
{
"token": "my_token_0000",
"card_token": "my_card_token_1989",
"state": "ACTIVE",
"state_reason": "Card activated by cardholder",
"fulfillment_status": "PROVISIONED",
"issuer_eligibility_decision": "cardaccount.verified",
"created_time": "2025-10-03T18:55:45Z",
"last_modified_time": "2025-01-26T22:36:10Z",
"token_service_provider": {
"token_reference_id": "my_token_reference_id_1600",
"pan_reference_id": "my_pan_reference_id_0073",
"token_requestor_id": "my_token_requestor_id_0373",
"token_requestor_name": "Token Requestor Name",
"token_type": "DEVICE_SECURE_ELEMENT",
"token_pan": "my_token_pan_6792",
"token_score": "02",
"token_eligibility_decision": "DECISION_GREEN"
},
"device": {
"type": "MOBILE_PHONE",
"language_code": "eng",
"device_id": "my_device_id_9575",
"phone_number": "12345678900",
"name": "Phone Name",
"location": "+37.81/-122.26",
"ip_address": "x.x.x.x"
},
"wallet_provider_profile": {
"account": {
"score": "05"
},
"risk_assessment": {
"score": "DECISION_YELLOW",
"version": "0001.00"
},
"device_score": "03",
"pan_source": "KEY_ENTERED"
},
"address_verification": {
"name": "Address Verification Name",
"street_address": "223 Elm Street",
"postal_code": "94703"
}
}
```
Create request for Apple Wallet web push provisioning
**Action:** `POST`\
**Endpoint:** `/digitalwallets/wpp/applePayJWT`
{/* */}
Use this endpoint to add a card to Apple Wallet via a web application.
Request body
| Fields | Description |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| card\_token
string
Required | Unique identifier of the card resource.
**Allowable Values:**
Existing card token |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
Response body
| Fields | Description |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| jws
object
Returned | Object containing JSON Web Signature (JWS) data.
**Allowable Values:**
Existing JWS object |
| jws.**header**
object
Returned | Contains header data for the JWS object.
**Allowable Values:**
Existing `kid` string |
| jws.header.**kid**
string
Returned | Unique identifier of the JSON Web Signature (JWS) public key of the key pair used to generate the signature.
**Allowable Values:**
Any value |
| jws.**protected**
string
Returned | Contains header parameters that are integrity-protected by the JSON Web Signature (JWS).
**Allowable Values:**
Any value |
| jws.**payload**
string
Returned | JSON Web Signature (JWS) message payload.
**Allowable Values:**
Any value |
| jws.**signature**
string
Returned | The JSON Web Signature (JWS).
**Allowable Values:**
Any value |
| state
string
Returned | Unique state associated with the digital wallet token. The Marqeta platform returns a universally unique identifier (UUID) in this field.
**Allowable Values:**
255 char |
Create request for Google Wallet web push provisioning
**Action:** `POST`\
**Endpoint:** `/digitalwallets/wpp/googlePayPushProvisioningNotification`
{/* */}
Use this endpoint to add a card to Google Wallet via a web application.
This endpoint does not return a payload in response to a request. Instead, a successful call will return a response code only.
| Fields | Description |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max
For example: '123d837e-958a-4e9f-bc97-4843ec948123' |
Request body
| Fields | Description |
| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| card\_setting
integer
Required | Indicates if the Funding Primary Account Number (FPAN) will be attempted.
- **1** - FPAN save will be attempted.
- **0** - FPAN save will not be attempted.
**Allowable Values:**
`0`, `1` |
| card\_token
string
Required | Unique identifier of the card resource.
**Allowable Values:**
Any value |
| client\_session\_id
string
Required | String provided by Google Wallet that identifies the client session.
**Allowable Values:**
Any value |
| integrator\_id
string
Required | Google-assigned string that uniquely identifies both the integrator that is initiating the session and the issuer of the card.
**Allowable Values:**
Any value |
| public\_device\_id
string
Required | String provided by Google Wallet that identifies the Android device that will receive the digital wallet token.
**Allowable Values:**
Any value |
| public\_wallet\_id
string
Required | String provided by Google Wallet that identifies the device-scoped wallet that receives the digital wallet token.
**Allowable Values:**
Any value |
| server\_session\_id
string
Required | String provided by Google Wallet that identifies the backend session.
**Allowable Values:**
Any value |
| token\_setting
integer
Required | Indicates if tokenization will be attempted.
- **1** - Tokenization will be attempted.
- **0** - Tokenization will not be attempted.
**Allowable Values:**
`0`, `1` |
Check eligibility for Click to Pay for Mastercard
**Action:** `GET`\
**Endpoint:** `/digitalwallets/clicktopay/mastercard/checkeligibility`
{/* */}
Use this endpoint to check if a provided BIN prefix is eligible for Click to Pay for Mastercard.
For more information about this ecommerce checkout solution, see [Click to Pay](/developer-guides/digital-wallets-and-tokenization/#_click_to_pay).
URL query parameters
| Fields | Description |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| bin\_prefix
string
Required | Prefix of the bank identification number.
**Allowable Values:**
A six- to nine-digit number
**NOTE:** It is preferable to use eight- or nine-digit BIN prefixes in production environments. Contact your Marqeta representative for the appropriate value to use. |
| include\_asset
boolean
Optional | Returns a list of image assets for the Click to Pay logo if set to `true`.
**Allowable Values:**
`true`, `false` |
| Fields | Description |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
Response body
| Fields | Description |
| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| is\_eligible
boolean
Conditionally returned | Indicates whether the `bin_prefix` is eligible for Click to Pay.
- `true`: The `bin_prefix` is eligible for Click to Pay.
- `false`: The `bin_prefix` is not eligible for Click to Pay.
**Allowable Values:**
`true`, `false` |
| image\_assets
array of objects
Conditionally returned | List of image assets for the Click to Pay logo if `include_asset` is set to `true` in the request.
**Allowable Values:**
A valid array of `image_asset` objects |
| image\_assets\[].**type**
string
Conditionally returned | Type of media. Specified as Multipurpose Internet Mail Extension (MIME).
Supported media types include:
- application/pdf
- image/png
- image/svg+xml
- text/plain
- text/html
**Allowable Values:**
32 char max |
| image\_assets\[].**data**
string
Conditionally returned | Media data content.
**Allowable Values:**
Base64-encoded media data |
| image\_assets\[].**height**
string
Conditionally returned | Height of non-SVG image asset. Specified in pixels.
**Allowable Values:**
6 char max |
| image\_assets\[].**width**
string
Conditionally returned | Width of non-SVG image asset. Specified in pixels.
**Allowable Values:**
6 char max |
Sample response body
```json JSON expandable lines wrap theme={null}
{
"is_eligible": true,
"image_assets": [
{
"media_content": {
"type": "image/png",
"data": "iVBORw0KGgoAAAANSUhEUgAAAMAAAADACAYAAABS3GwHAAAAAXNSR0IArs4c6... (truncated for readability)",
"height": "192px",
"width": "192px"
}
},
{
"media_content": {
"type": "image/svg+xml",
"data": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyB3... (truncated for readability)",
"height": "192px",
"width": "192px"
}
}
]
}
```
Enroll a card to Click to Pay for Mastercard
**Action:** `POST`\
**Endpoint:** `/digitalwallets/clicktopay/mastercard/enroll`
{/* */}
Use this endpoint to enroll a card in Click to Pay for Mastercard.
For more information about this ecommerce checkout solution, see [Click to Pay](/developer-guides/digital-wallets-and-tokenization/#_click_to_pay).
| Fields | Description |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
Request body
| Fields | Description |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| card\_token
string
Required | Unique identifier of the card resource.
**Allowable Values:**
1–36 chars
Existing card token |
| user\_token
string
Required | Unique identifier of the cardholder.
**Allowable Values:**
1–36 chars |
| user\_details
array of objects
Required | User’s email address and mobile phone number with country code.
**Allowable Values:**
A valid array of `user_details` objects |
| user\_details\[].**email\_address**
string
Required | User’s email address.
**Allowable Values:**
255 char max |
| user\_details\[].**mobile\_number**
object
Required | User’s mobile phone number and country code.
**Allowable Values:**
`country_code`, `phone_number` |
| user\_details\[].mobile\_number.**country\_code**
string
Required | User’s mobile phone number country code only.
**Allowable Values:**
255 char max |
| user\_details\[].mobile\_number.**phone\_number**
string
Required | User’s mobile phone number without country code.
**Allowable Values:**
255 char max |
| locale\_country
string
Required | The user-provided country code. The ISO 3166 country code is a two-letter country code that represents a country. For example, the numeric code for the United States is `US`.
The ISO maintains the ISO-3166 country codes.
**Allowable Values:**
2 chars |
| locale\_language
string
Required | The user-provided language choice. The ISO 639-2 language code is a two-letter country code that represents a language.
The ISO maintains the ISO 639-2 language codes.
**Allowable Values:**
2 chars |
| callback\_url
string
Optional | The URL to which the Click to Pay request status is sent via webhooks.
**Allowable Values:**
A valid URL |
| callback\_authentication\_type
string
Optional | The type of authentication required for the callback URL.
- `OAUTH_BEARER_TOKEN`: OAuth bearer token for the callback URL.
- `BASIC_AUTH`: Basic auth username and password for the callback URL.
**Allowable Values:**
`OAUTH_BEARER_TOKEN`, `BASIC_AUTH` |
| oauth\_bearer\_token
string
Optional | OAuth bearer token to access your callback URL if the `callback_authentication_type` is `OAUTH_BEARER_TOKEN`.
**Allowable Values:**
A bearer token that can be used to authenticate the callback API on the receiving end |
| callback\_secret\_for\_signature
string
Optional | Randomly chosen string used for implementing HMAC-SHA1.
HMAC-SHA1 provides an added layer of security by authenticating the message and validating message integrity. Using this functionality requires that your callback endpoint verify the message signature. For information about implementing this functionality, see Signature Verification.
**Allowable Values:**
20–50 chars
- Must contain at least one numeral
- Must contain at least one lowercase letter
- Must contain at least one uppercase letter
- Must contain at least one of these symbols:
`@``#``$``%``!``^``&``*``(``)`
`\\``_``+``~``-``=``[``]``\{``}`
`,``;``:``'``"``.``/``<``>``?`\` |
| basic\_auth\_username
string
Optional | Basic auth username to access your callback URL if authentication type is basic. If authentication type is basic, both username and password are required.
**Allowable Values:**
1–50 chars |
| basic\_auth\_password
string
Optional | Basic auth password to access your callback URL if authentication type is basic. If authentication type is basic, both username and password are required.
**Allowable Values:**
20–50 chars
- Must contain at least one numeral
- Must contain at least one lowercase letter
- Must contain at least one uppercase letter
- Must contain at least one of these symbols:
`@``#``$``%``!``^``&``*``(``)`
`\\``_``+``~``-``=``[``]``\{``}`
`,``;``:``'``"``.``/``<``>``?`\` |
Sample request body
```json JSON lines wrap theme={null}
{
"card_token": "my_card_token_1234",
"user_token": "my_user_token_1234",
"user_details": [
{
"email_address": "test@test.com",
"mobile_number": {
"country_code": "44",
"phone_number": "1234567890"
}
}
],
"locale_country": "US",
"locale_language": "en"
}
```
Response body
| Fields | Description |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| token
string
Conditionally returned | Unique identifier of the Click to Pay request.
**Allowable Values:**
1–36 chars |
Sample response body
```json JSON lines wrap theme={null}
{
"token": "my_token_0000"
}
```
Retrieve Click to Pay for Mastercard enrollment status
**Action:** `GET`\
**Endpoint:** `/digitalwallets/clicktopay/mastercard/status/{token}`
{/* */}
Use this endpoint to return the status of a specific Click to Pay for Mastercard request.
For more information about this ecommerce checkout solution, see [Click to Pay](/developer-guides/digital-wallets-and-tokenization/#_click_to_pay).
URL path parameters
| Fields | Description |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| token
string
Required | Unique identifier of the Click to Pay request.
**Allowable Values:**
Existing Click to Pay request token |
| Fields | Description |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
Response body
| Fields | Description |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| token
string
Conditionally returned | Unique identifier of the Click to Pay request, used to track the status of the request.
**Allowable Values:**
36 char max |
| status
string
Conditionally returned | The status of the Click to Pay request.
- `SUCCESS`: The Click to Pay request was successful.
- `FAILED`: The Click to Pay request failed.
- `RECEIVED`: The Click to Pay request was received.
**Allowable Values:**
`SUCCESS`, `FAILED`, `RECEIVED` |
| token\_reference\_id
string
Conditionally returned | Unique identifier of the digital wallet token within the card network.
**Allowable Values:**
255 char max |
Sample response body
```json JSON lines wrap theme={null}
{
"token": "my_token_0000",
"status": "SUCCESS",
"token_reference_id": "my_token_reference_id_1600"
}
```
Enroll a cardholder to Click to Pay for Visa
**Action:** `POST`\
**Endpoint:** `/digitalwallets/clicktopay/visa/enroll`
{/* */}
Use this endpoint to enroll a new cardholder in Click to Pay for Visa.
For more information about this ecommerce checkout solution, see [Click to Pay](/developer-guides/digital-wallets-and-tokenization/#_click_to_pay).
| Fields | Description |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
| external-consumer-id-owner-bid
string
Required | Visa Business Identifier (BID) of the entity to which an External Consumer ID belongs.
**Allowable Values:**
1-8 chars |
Request body
| Fields | Description |
| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| card
object
Required | Card information for Visa Click to Pay.
**Allowable Values:**
`cardToken`, `nameOnCard` |
| card.**cardToken**
string
Required | Unique identifier of the card.
**Allowable Values:**
1–36 chars |
| card.**nameOnCard**
string
Required | Name of the cardholder that appears on the card.
**Allowable Values:**
1–120 chars |
| card.**billingAddress**
object
Required | Billing address for Visa Click to Pay.
**Allowable Values:**
`address1`, `city`, `state`, `country`, `postalCode` |
| card.billingAddress.**address1**
string
Optional | First line of the billing address.
**Allowable Values:**
64 chars max |
| card.billingAddress.**address2**
string
Optional | Optional second line of the billing address.
**Allowable Values:**
64 chars max |
| card.billingAddress.**city**
string
Optional | City of the billing address.
**Allowable Values:**
32 chars max |
| card.billingAddress.**state**
string
Optional | State of the billing address.
**Allowable Values:**
3 chars max |
| card.billingAddress.**country**
string
Required | Country of the billing address.
**Allowable Values:**
3 chars |
| card.billingAddress.**postalCode**
string
Optional | Postal code of the billing address.
**Allowable Values:**
9 chars max |
| user
object
Required | User’s email address, mobile phone number without country code, first name, last name, locale, and country.
**Allowable Values:**
`userToken`, `email`, `phone`, `firstName`, `lastName`, `locale`, `country` |
| user.**userToken**
string
Required | Unique identifier of the cardholder.
**Allowable Values:**
1–36 chars |
| user.**email**
string
Required | User’s email address.
**Allowable Values:**
255 char max |
| user.**phone**
string
Required | User’s mobile phone number according to ITU-T E.164 (2010) number structure.
**NOTE:** In the E.164 format, the "+" sign is not included.
**Allowable Values:**
1–16 chars |
| user.**firstName**
string
Required | User’s first name.
**Allowable Values:**
1–35 chars |
| user.**lastName**
string
Required | User’s last name.
**Allowable Values:**
1–35 chars |
| user.**locale**
string
Required | The user-provided language choice. The ISO 639-2 language code is a two-letter country code that represents a language.
The ISO maintains the ISO 639-2 language codes.
**Allowable Values:**
2–5 chars |
| user.**country**
string
Required | ISO 3166-1 alpha-3 country code.
**Allowable Values:**
3 chars |
Sample request body
```json JSON expandable lines wrap theme={null}
{
"user": {
"userToken": "1234567890",
"firstName": "John",
"lastName": "Smith",
"email": "example@email.com",
"phone": "111-111-1111",
"locale": "en_US",
"country": "USA"
},
"card": {
"cardToken": "2345678910",
"nameOnCard": "John Smith",
"billingAddress": {
"address1": "123 Elm Street",
"address2": "APT 1",
"city": "Oakland",
"state": "CA",
"country": "USA",
"postalCode": "94607"
}
}
}
```
Response body
| Fields | Description |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| requestTraceId
string
Returned | Unique identifier of the Visa Click to Pay request.
**Allowable Values:**
1–36 chars |
Sample response body
```json JSON lines wrap theme={null}
{
"requestTraceId": "2b6f0cc904d137be2e1730235f5664094b83"
}
```
Enroll a card to Click to Pay for Visa
**Action:** `POST`\
**Endpoint:** `/digitalwallets/clicktopay/visa/enrollcards`
{/* */}
Use this endpoint to enroll a new card for an existing cardholder in Click to Pay for Visa.
For more information about this ecommerce checkout solution, see [Click to Pay](/developer-guides/digital-wallets-and-tokenization/#_click_to_pay).
| Fields | Description |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
| external-consumer-id-owner-bid
string
Required | Visa Business Identifier (BID) of the entity to which an External Consumer ID belongs.
**Allowable Values:**
1-8 chars |
Request body
| Fields | Description |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| card
object
Required | Card information for Visa Click to Pay.
**Allowable Values:**
`cardToken`, `nameOnCard` |
| card.**cardToken**
string
Required | Unique identifier of the card.
**Allowable Values:**
1–36 chars |
| card.**nameOnCard**
string
Required | Name of the cardholder that appears on the card.
**Allowable Values:**
1–120 chars |
| card.**billingAddress**
object
Required | Billing address for Visa Click to Pay.
**Allowable Values:**
`address1`, `city`, `state`, `country`, `postalCode` |
| userToken
string
Required | Unique identifier of the cardholder.
**Allowable Values:**
1–36 chars |
Sample request body
```json JSON lines wrap theme={null}
{
"userToken": "1234567890",
"card": {
"cardToken": "2345678901",
"nameOnCard": "John Smith",
"billingAddress": {
"address1": "123 Elm Street",
"address2": "APT 1",
"city": "Oakland",
"state": "CA",
"country": "USA",
"postalCode": "94607"
}
}
}
```
Response body
| Fields | Description |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| requestTraceId
string
Returned | Unique identifier of the Visa Click to Pay request.
**Allowable Values:**
1–36 chars |
Sample response body
```json JSON lines wrap theme={null}
{
"requestTraceId": "2b6f0cc904d137be2e1730235f5664094b83"
}
```
Retrieve user data for Click to Pay for Visa
**Action:** `GET`\
**Endpoint:** `/digitalwallets/clicktopay/visa/getdata/{user_token}`
{/* */}
Use this endpoint to get user data for Click to Pay for Visa.
For more information about this ecommerce checkout solution, see [Click to Pay](/developer-guides/digital-wallets-and-tokenization/#_click_to_pay).
URL path parameters
| Fields | Description |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| user\_token
string
Required | Unique identifier of the cardholder.
**Allowable Values:**
Existing Visa Click To Pay User Token |
| Fields | Description |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max
For example: '123d837e-958a-4e9f-bc97-4843ec948123' |
| external-consumer-id-owner-bid
string
Required | Visa Business Identifier (BID) of the entity to which an External Consumer ID belongs.
**Allowable Values:**
1-8 chars |
Response body
| Fields | Description |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| data
array of objects
Returned | Array of objects containing information of a Visa Click to Pay cardholder
**Allowable Values:**
Valid array of data objects |
| data\[].**intent**
object
Returned | Intent of the Visa Click to Pay operation.
**Allowable Values:**
`type`, `value` |
| data\[].**consumerInformation**
object
Returned | Object containing cardholder details for Visa Click to Pay operation.
**Allowable Values:**
`externalConsumerID`, `firstName`, `middleName`, `lastName`, `phones`, `emails`, `locale`, `countryCode`, `state` |
| data\[].**paymentInstruments**
array of objects
Returned | Array of objects containing details of payment instruments for Visa Click to Pay.
**Allowable Values:**
`type`, `accountNumber`, `nameOnCard`, `expirationDate`, `tokenDetails`, `paymentAccountReference`, `billingAddress`, `status` |
Sample response body
```json JSON expandable lines wrap theme={null}
{
"data": [
{
"intent": {
"type": "PRODUCT_CODE",
"value": "CLICK_TO_PAY"
},
"paymentInstruments": [
{
"type": "CARD",
"status": "ACTIVE",
"cardType": "Visa Platinum",
"issuerName": "Bank A",
"nameOnCard": "John Doe",
"tokenDetails": {
"tokenReferenceID": "hflasdhflsdkfhoin3y038yfwn",
"tokenRequestorID": "1234567890"
},
"accountNumber": "4111111145551140",
"billingAddress": {
"city": "San Francisco",
"state": "CA",
"country": "USA",
"postalCode": "94105",
"addressLine1": "1000 Market Street",
"addressLine2": "Building 56",
"addressLine3": "Suite 101"
},
"expirationDate": "2030-01",
"panReferenceID": "alikbndesfiluwbn1342fs",
"paymentAccountReference": "paymentAccountReferenceValues"
}
],
"consumerInformation": {
"emails": [
"alex123@hotmail.com"
],
"locale": "en_US",
"phones": [
"16504005555"
],
"status": "ACTIVE",
"consent": {
"version": "1.0",
"presenter": "Bank A",
"timeOfConsent": "2020-05-05T12:12:12.000Z"
},
"lastName": "Miller",
"firstName": "Alex",
"middleName": "Robert",
"countryCode": "USA",
"externalConsumerID": "63421837-d597-4f0f-89e4-930c1a7b9e85",
"nationalIdentifiers": [
{
"type": "PASSPORT",
"value": "A123456"
}
]
}
}
]
}
```
Update cardholder information for Click to Pay for Visa
**Action:** `PUT`\
**Endpoint:** `/digitalwallets/clicktopay/visa/users`
{/* */}
Use this endpoint to update cardholder information for Click to Pay for Visa.
For more information about this ecommerce checkout solution, see [Click to Pay](/developer-guides/digital-wallets-and-tokenization/#_click_to_pay).
| Fields | Description |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max
For example: '123d837e-958a-4e9f-bc97-4843ec948123' |
| external-consumer-id-owner-bid
string
Required | Visa Business Identifier (BID) of the entity to which an External Consumer ID belongs.
**Allowable Values:**
1-8 chars |
Request body
| Fields | Description |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| user
object
Required | User’s email address, mobile phone number without country code, first name, last name, locale, and country.
**Allowable Values:**
`userToken`, `email`, `phone`, `firstName`, `lastName`, `locale`, `country` |
| user.**userToken**
string
Required | Unique identifier of the cardholder.
**Allowable Values:**
1–36 chars |
| user.**email**
string
Required | User’s email address.
**Allowable Values:**
255 char max |
| user.**phone**
string
Required | User’s mobile phone number according to ITU-T E.164 (2010) number structure.
**NOTE:** In the E.164 format, the "+" sign is not included.
**Allowable Values:**
1–16 chars |
| user.**firstName**
string
Required | User’s first name.
**Allowable Values:**
1–35 chars |
| user.**lastName**
string
Required | User’s last name.
**Allowable Values:**
1–35 chars |
| user.**locale**
string
Required | The user-provided language choice. The ISO 639-2 language code is a two-letter country code that represents a language.
The ISO maintains the ISO 639-2 language codes.
**Allowable Values:**
2–5 chars |
| user.**country**
string
Required | ISO 3166-1 alpha-3 country code.
**Allowable Values:**
3 chars |
Sample request body
```json JSON lines wrap theme={null}
{
"user": {
"userToken": "1234567890",
"firstName": "John",
"lastName": "Smith",
"email": "example@email.com",
"phone": "111-111-1111",
"locale": "en_US",
"country": "USA"
}
}
```
Response body
| Fields | Description |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| requestTraceId
string
Returned | Unique identifier of the Visa Click to Pay request.
**Allowable Values:**
1–36 chars |
Sample response body
```json JSON lines wrap theme={null}
{
"requestTraceId": "2b6f0cc904d137be2e1730235f5664094b83"
}
```
Delete cardholder information for Click to Pay for Visa
**Action:** `DELETE`\
**Endpoint:** `/digitalwallets/clicktopay/visa/users`
{/* */}
Use this endpoint to delete cardholder information for Click to Pay for Visa.
For more information about this ecommerce checkout solution, see [Click to Pay](/developer-guides/digital-wallets-and-tokenization/#_click_to_pay).
| Fields | Description |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max
For example: '123d837e-958a-4e9f-bc97-4843ec948123' |
| external-consumer-id-owner-bid
string
Required | Visa Business Identifier (BID) of the entity to which an External Consumer ID belongs.
**Allowable Values:**
1-8 chars |
Request body
| Fields | Description |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------- |
| userToken
string
Required | Unique identifier of the cardholder.
**Allowable Values:**
1–36 chars |
Sample request body
```json JSON lines wrap theme={null}
{
"userToken": "1234567890"
}
```
Response body
| Fields | Description |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| requestTraceId
string
Returned | Unique identifier of the Visa Click to Pay request.
**Allowable Values:**
1–36 chars |
Sample response body
```json JSON lines wrap theme={null}
{
"requestTraceId": "2b6f0cc904d137be2e1730235f5664094b83"
}
```
Update card information for Click to Pay for Visa
**Action:** `PUT`\
**Endpoint:** `/digitalwallets/clicktopay/visa/cards`
{/* */}
Use this endpoint to update card information for Click to Pay for Visa.
For more information about this ecommerce checkout solution, see [Click to Pay](/developer-guides/digital-wallets-and-tokenization/#_click_to_pay).
| Fields | Description |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max
For example: '123d837e-958a-4e9f-bc97-4843ec948123' |
| external-consumer-id-owner-bid
string
Required | Visa Business Identifier (BID) of the entity to which an External Consumer ID belongs.
**Allowable Values:**
1-8 chars |
Request body
| Fields | Description |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| card
object
Required | Card information for Visa Click to Pay.
**Allowable Values:**
`cardToken`, `nameOnCard` |
| card.**cardToken**
string
Required | Unique identifier of the card.
**Allowable Values:**
1–36 chars |
| card.**nameOnCard**
string
Required | Name of the cardholder that appears on the card.
**Allowable Values:**
1–120 chars |
| card.**billingAddress**
object
Required | Billing address for Visa Click to Pay.
**Allowable Values:**
`address1`, `city`, `state`, `country`, `postalCode` |
| userToken
string
Required | Unique identifier of the cardholder.
**Allowable Values:**
1–36 chars |
Sample request body
```json JSON lines wrap theme={null}
{
"userToken": "1234567890",
"card": {
"cardToken": "2345678901",
"nameOnCard": "John Smith",
"billingAddress": {
"address1": "123 Elm Street",
"address2": "APT 1",
"city": "Oakland",
"state": "CA",
"country": "USA",
"postalCode": "94607"
}
}
}
```
Response body
| Fields | Description |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| requestTraceId
string
Returned | Unique identifier of the Visa Click to Pay request.
**Allowable Values:**
1–36 chars |
Sample response body
```json JSON lines wrap theme={null}
{
"requestTraceId": "2b6f0cc904d137be2e1730235f5664094b83"
}
```
Delete card information for Click to Pay for Visa
**Action:** `DELETE`\
**Endpoint:** `/digitalwallets/clicktopay/visa/cards/{card_token}`
{/* */}
Use this endpoint to delete card information for Click to Pay for Visa.
For more information about this ecommerce checkout solution, see [Click to Pay](/developer-guides/digital-wallets-and-tokenization/#_click_to_pay).
URL path parameters
| Fields | Description |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| card\_token
string
Required | Unique identifier of the cardholder.
**Allowable Values:**
1–36 chars |
| Fields | Description |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max
For example: '123d837e-958a-4e9f-bc97-4843ec948123' |
| external-consumer-id-owner-bid
string
Required | Visa Business Identifier (BID) of the entity to which an External Consumer ID belongs.
**Allowable Values:**
1-8 chars |
Response body
| Fields | Description |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| requestTraceId
string
Returned | Unique identifier of the Visa Click to Pay request.
**Allowable Values:**
1–36 chars |
Sample response body
```json JSON lines wrap theme={null}
{
"requestTraceId": "2b6f0cc904d137be2e1730235f5664094b83"
}
```
Retrieve Click to Pay for Visa request status
**Action:** `GET`\
**Endpoint:** `/digitalwallets/clicktopay/visa/status/{requestTraceId}`
{/* */}
Use this endpoint to return the status of a Click to Pay for Visa request.
For more information about this ecommerce checkout solution, see [Click to Pay](/developer-guides/digital-wallets-and-tokenization/#_click_to_pay).
URL path parameters
| Fields | Description |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| requestTraceId
string
Required | Unique identifier of the Visa Click to Pay request.
**Allowable Values:**
1–36 chars |
| Fields | Description |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max
For example: '123d837e-958a-4e9f-bc97-4843ec948123' |
| external-consumer-id-owner-bid
string
Required | Visa Business Identifier (BID) of the entity to which an External Consumer ID belongs.
**Allowable Values:**
1-8 chars |
Response body
| Fields | Description |
| ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| status
string
Returned | Status of the operation.
**Allowable Values:**
`IN_PROGRESS`, `COMPLETED` |
| consumerInformation
object
Conditionally returned | Consumer information.
**Allowable Values:**
Existing `consumerInformation` object |
| consumerInformation.**externalConsumerID**
string
Conditionally returned | External consumer ID.
**Allowable Values:**
1–100 chars |
| consumerInformation.**externalConsumerIDOwnerBID**
string
Conditionally returned | Visa Business Identifier (BID) of the entity to which an External Consumer ID belongs.
**Allowable Values:**
1–8 chars |
| details
array of undefineds
Conditionally returned | Additional status details of the operation.
**Allowable Values:**
Array of `details` object |
| details\[].**status**
string
Returned | Status of the operation.
**Allowable Values:**
`SUCCESS`, `FAILED` |
| details\[].**intent**
object
Returned | Intent of the Visa Click to Pay operation.
**Allowable Values:**
`type`, `value` |
| details\[].**errorDetails**
array of objects
Returned | Details of error occurred while executing the operation.
**Allowable Values:**
`field`, `reason`, `message` |
Sample response body
```json JSON expandable lines wrap theme={null}
{
"status": "IN_PROGRESS",
"details": [
{
"intent": {
"type": "PRODUCT_CODE",
"value": "CLICK_TO_PAY"
},
"status": "SUCCESS",
"errorDetails": [
{
"field": "string",
"reason": "string",
"message": "string"
}
]
}
],
"consumerInformation": {
"externalConsumerID": "63421837-d597-4f0f-89e4-930c1a7b9e85",
"externalConsumerIDOwnerBID": "10098765"
}
}
```
Create a Visa Alias
**Action:** `POST`\
**Endpoint:** `/digitalwallets/aliasdirectory/visa/aliases`
{/* */}
Use this endpoint to create a Visa Alias.
| Fields | Description |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max
For example: '123d837e-958a-4e9f-bc97-4843ec948123' |
| participant-id
string
Required | Visa Business Identifier (BID) that is assigned to the program.
**Allowable Values:**
Existing participant ID
For example, "123456789001" |
Request body
| Fields | Description |
| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| aliasType
string
Required | Type of Visa Alias in the Alias Directory Service (ADS) profile. Visa supports phone and email as Visa Alias types that can be used in place of sensitive payment credentials details.
**Allowable Values:**
`EMAIL`, `PHONE`, `DIRECTORY_ALIASID`, `PAYNAME` |
| userToken
string
Required | Unique identifier of the user.
**Allowable Values:**
1–128 chars |
| aliasValue
string
Required | Visa Alias value, which can be an email, a phone number, ID of an alias directory, or a payname.
If a phone number is used for the Visa Alias, it must follow ITU-T E.164 (2010) number structure. **NOTE:** In the E.164 format, the "+" sign is not included.
**Allowable Values:**
1–128 chars |
| consent
object
Required | Visa Alias Directory Service (ADS) consent information.
**Allowable Values:**
`presenter`, `validFromDateTime`, `version`, `expiryDateTime`, `intermediaries` |
| paymentCredentials
array of objects
Required | Visa Alias payment credentials.
**Allowable Values:**
`cardToken`, `billingAddress`, `nameOnCard`, `cardType`, `issuerName`, `currencyCode`, `preferredFor` |
| paymentCredentials.**cardToken**
string
Required | Unique identifier of the card.
**Allowable Values:**
Existing card token |
| paymentCredentials.**billingAddress**
object
Required | Billing address associated with the payment credential.
**Allowable Values:**
`country`, `addressLine1`, `addressLine2`, `buildingNumber`, `city`, `minorSubdivision`, `postalCode`, `state`, `streetName` |
| paymentCredentials.billingAddress.**country**
string
Required | Country of the billing address associated with the payment credential, expressed as an ISO 3166 code. For example, the numeric code for the United States is `840` and the alpha-3 code is `USA`.
The ISO maintains the full list of ISO 3166 country codes.
**Allowable Values:**
3 char max |
| paymentCredentials.billingAddress.**addressLine1**
string
Optional | Address line 1 of the billing address associated with the payment credential.
**Allowable Values:**
99 char max |
| paymentCredentials.billingAddress.**addressLine2**
string
Optional | Address line 2 of the billing address associated with the payment credential.
**Allowable Values:**
99 char max |
| paymentCredentials.billingAddress.**buildingNumber**
string
Optional | Building number of the billing address associated with the payment credential.
**Allowable Values:**
1–60 chars |
| paymentCredentials.billingAddress.**city**
string
Optional | City of the billing address associated with the payment credential.
**Allowable Values:**
1–35 chars |
| paymentCredentials.billingAddress.**minorSubdivision**
string
Optional | Minor subdivision of the billing address associated with the payment credential.
**Allowable Values:**
1–50 chars |
| paymentCredentials.billingAddress.**postalCode**
string
Optional | Postal code of the billing address associated with the payment credential.
**Allowable Values:**
1–16 chars |
| paymentCredentials.billingAddress.**state**
string
Optional | State of the billing address associated with the payment credential.
**Allowable Values:**
1–16 chars |
| paymentCredentials.billingAddress.**streetName**
string
Optional | Street name of the billing address associated with the payment credential.
**Allowable Values:**
1–60 chars |
| paymentCredentials.**nameOnCard**
string
Required | Name on the card for the payment credential.
**Allowable Values:**
1-120 chars |
| paymentCredentials.**cardType**
string
Required | Type of card for the payment credential.
**Allowable Values:**
1-70 chars |
| paymentCredentials.**issuerName**
string
Required | Card issuer’s name for the payment credential.
**Allowable Values:**
1-150 chars |
| paymentCredentials.**currencyCode**
string
Optional | Three-digit ISO 4217 currency code for the payment credential.
**Allowable Values:**
Valid three-digit ISO 4217 currency code (Alpha-3) |
| paymentCredentials.**preferredFor**
array of strings
Optional | Indicates if a payment credential is a preferred Receiving, Sending, or Paying account.
**Allowable Values:**
`RECEIVE`, `SEND`, `PAYING` |
| profile
object
Required | Alias Directory Service (ADS) profile information.
**Allowable Values:**
`firstName`, `lastName`, `contactInfo`, `dateOfBirth`, `firstNameLocal`, `lastNameLocal`, `middleName`, `middleNameLocal`, `preferredName` |
| profile.**firstName**
string
Required | First name in the Alias Directory Service (ADS) profile.
**Allowable Values:**
1–35 chars |
| profile.**lastName**
string
Required | Last name in the Alias Directory Service (ADS) profile. Participants in the CEMEA and EU regions must only use the initial of the consumer’s last name followed by a period to create or modify a Visa Alias record.
**Allowable Values:**
1–35 chars |
| profile.**contactInfo**
object
Required | Contact information in the Alias Directory Service (ADS) profile.
**Allowable Values:**
`type`, `value` |
| profile.contactInfo.**type**
string
Required | Type of contact information in the Alias Directory Service (ADS) profile.
**Allowable Values:**
`EMAIL`, `PHONE`, `DIRECTORY_ALIASID` |
| profile.contactInfo.**value**
string
Required | Contact information value, which is the email address or phone number.
**Allowable Values:**
1-320 chars |
| profile.**dateOfBirth**
date
Optional | Date of birth in the Alias Directory Service (ADS) profile.
**Allowable Values:**
10 chars |
| profile.**firstNameLocal**
string
Optional | First name in the Alias Directory Service (ADS) profile, expressed in the user’s local language.
**Allowable Values:**
1–35 chars |
| profile.**lastNameLocal**
string
Optional | Last name in the Alias Directory Service (ADS) profile, expressed in the user’s local language.
**Allowable Values:**
1–35 chars |
| profile.**middleName**
string
Optional | Middle name in the Alias Directory Service (ADS) profile.
**Allowable Values:**
1–35 chars |
| profile.**middleNameLocal**
string
Optional | Middle name in the Alias Directory Service (ADS) profile, expressed in the user’s local language.
**Allowable Values:**
1–35 chars |
| profile.**preferredName**
string
Optional | Preferred name in the Alias Directory Service (ADS) profile, as provided by the user.
**Allowable Values:**
1–35 chars |
| identification
object
Optional | Identification of the user associated with the Visa Alias.
**Allowable Values:**
`type`, `value`, `verificationDetails` |
Sample request body
```json JSON expandable lines wrap theme={null}
{
"aliasType": "PHONE",
"userToken": "21267931-7975-4b61-be7a-86915883b2b4",
"aliasValue": "1231231234",
"consent": {
"presenter": "Bank A",
"validFromDateTime": "2024-12-01T10:00:00Z",
"intermediaries": [
"Client A"
],
"version": "1.0",
"expiryDateTime": "2027-06-20T10:00:00Z"
},
"paymentCredentials": [
{
"cardToken": "4111111145551142",
"billingAddress": {
"country": "USA",
"streetName": "12",
"city": "San Francisco",
"postalCode": "94105",
"addressLine1": "1000 Market Street",
"buildingNumber": "56",
"addressLine2": "Suite 101",
"state": "CA",
"minorSubdivisionCode": "CA"
},
"nameOnCard": "John Doe",
"cardType": "Visa Platinum",
"issuerName": "Bank A",
"currencyCode": "USD"
}
],
"profile": {
"firstName": "Alex",
"middleName": "Robert",
"lastName": "Miller",
"firstNameLocal": "Roberto",
"middleNameLocal": "Alexander",
"lastNameLocal": "Miller",
"preferredName": "Miller's Shop",
"dateOfBirth": "1980-02-01",
"contactInfo": [
{
"type": "PHONE",
"value": "1231234321"
}
]
},
"identification": {
"type": "PASSPORT",
"value": "A123456",
"verificationDetails": {
"verifiedPhone": false,
"authMethodReference": "EXTERNAL, SMS OTP, Email OTP",
"authDateTime": "2025-01-01T22:52:46.000Z",
"verifiedEmail": true,
"creationDateTime": "2025-01-01T22:52:46.000Z"
}
}
}
```
Response body
| Fields | Description |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id
string
Returned | UUID generated by Alias Directory, which identifies the Visa Alias.
**Allowable Values:**
36 char max |
| externalId
string
Conditionally returned | External ID of the Visa Alias.
**Allowable Values:**
1–100 chars |
| paymentCredentials
array of objects
Conditionally returned | List of payment credentials associated with the Visa Alias.
This array is returned if the Visa Alias exists and one or more payment credentials are linked to it.
**Allowable Values:**
A valid array of payment credentials |
Sample response body
```json JSON lines wrap theme={null}
{
"id": "1f4f5e10-bde6-46a7-b2aa-576550054981",
"externalId": "21267931-7975-4b61-a-8691588sdfsdfa",
"paymentCredentials": [
{
"type": "CARD",
"id": "19e538ea-edfb-4780-915e-2f6e02959e03",
"externalId": "1111111111111111"
}
]
}
```
Retrieve Visa Alias by Visa Alias ID
**Action:** `GET`\
**Endpoint:** `/digitalwallets/aliasdirectory/visa/aliases/{aliasId}`
{/* */}
Use this endpoint to retrieve a Visa Alias by its Visa Alias ID.
URL path parameters
| Fields | Description |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| aliasId
string
Required | Unique identifier of the Visa Alias.
**Allowable Values:**
Existing Visa Alias ID |
| Fields | Description |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
| participant-id
string
Required | Visa Business Identifier (BID) that is assigned to the program.
**Allowable Values:**
Existing participant ID
For example, "123456789001" |
Response body
| Fields | Description |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| aliasValue
string
Conditionally returned | Visa Alias value, which can be an email, a phone number, ID of an alias directory, or a payname.
If a phone number is used for the Visa Alias, it must follow ITU-T E.164 (2010) number structure. **NOTE:** In the E.164 format, the "+" sign is not included.
**Allowable Values:**
1–128 chars |
| profile
object
Conditionally returned | Alias Directory Service (ADS) profile information.
**Allowable Values:**
- `firstName`
- `lastName`
- `contactInfo`
- `dateOfBirth`
- `firstNameLocal`
- `lastNameLocal`
- `middleName`
- `middleNameLocal`
- `preferredName` |
| profile.**firstName**
string
Returned | First name in the Alias Directory Service (ADS) profile.
**Allowable Values:**
1–35 chars |
| profile.**lastName**
string
Returned | Last name in the Alias Directory Service (ADS) profile. Participants in the CEMEA and EU regions must only use the initial of the consumer’s last name followed by a period to create or modify a Visa Alias record.
**Allowable Values:**
1–35 chars |
| profile.**contactInfo**
array of objects
Conditionally returned | Contact information in the Alias Directory Service (ADS) profile.
This array is returned if the Visa Alias' contact information details exist.
**Allowable Values:**
A valid array of contact information details |
| profile.**dateOfBirth**
date
Conditionally returned | Date of birth in the Alias Directory Service (ADS) profile.
This field is returned if it exists in the resource.
**Allowable Values:**
10 chars |
| profile.**firstNameLocal**
string
Conditionally returned | First name in the Alias Directory Service (ADS) profile, expressed in the user’s local language.
This field is returned if it exists in the resource.
**Allowable Values:**
1–35 chars |
| profile.**lastNameLocal**
string
Conditionally returned | Last name in the Alias Directory Service (ADS) profile, expressed in the user’s local language.
This field is returned if it exists in the resource.
**Allowable Values:**
1–35 chars |
| profile.**middleName**
string
Conditionally returned | Middle name in the Alias Directory Service (ADS) profile.
This field is returned if it exists in the resource.
**Allowable Values:**
1–35 chars |
| profile.**middleNameLocal**
string
Conditionally returned | Middle name in the Alias Directory Service (ADS) profile, expressed in the user’s local language.
This field is returned if it exists in the resource.
**Allowable Values:**
1–35 chars |
| profile.**preferredName**
string
Conditionally returned | Preferred name in the Alias Directory Service (ADS) profile, as provided by the user.
This field is returned if it exists in the resource.
**Allowable Values:**
1–35 chars |
| aliasType
string
Conditionally returned | Type of Visa Alias in the Alias Directory Service (ADS) profile. Visa supports phone and email as Visa Alias types that can be used in place of sensitive payment credentials.
This field is returned if it exists in the resource.
**Allowable Values:**
`EMAIL`, `PHONE`, `DIRECTORY_ALIASID`, `PAYNAME` |
| consent
object
Conditionally returned | Visa Alias Directory Service (ADS) consent information.
**Allowable Values:**
`presenter`, `validFromDateTime`, `version`, `expiryDateTime`, `intermediaries` |
| consent.**presenter**
string
Returned | Presenter of the Visa Alias Directory Service (ADS) consent.
**Allowable Values:**
1–120 chars |
| consent.**validFromDateTime**
datetime
Returned | Date and time when the validity of the Visa ADS consent begins.
**Allowable Values:**
20 chars
Format: YYYY-MM-DDThh:mm:ssZ |
| consent.**version**
string
Returned | Version of the Visa ADS consent.
**Allowable Values:**
1–9 chars |
| consent.**expiryDateTime**
datetime
Conditionally returned | Date and time when the validity of the Visa ADS consent ends.
This field is returned if it exists in the resource.
**Allowable Values:**
20 chars
Format: YYYY-MM-DDThh:mm:ssZ |
| consent.**intermediaries**
array of strings
Conditionally returned | Intermediaries of the Visa ADS consent.
**Allowable Values:**
1–120 chars |
| createdOn
datetime
Conditionally returned | Date and time when the Visa Alias was created.
**Allowable Values:**
24 chars
Format: YYYY-MM-DDThh:mm:ss.000Z |
| identification
object
Conditionally returned | Identification of the user associated with the Visa Alias.
**Allowable Values:**
`type`, `value`, `verificationDetails` |
| identification.**type**
string
Returned | Type of identification provided by the user associated with the Visa Alias.
**Allowable Values:**
`DNI`, `CE`, `PASSPORT`, `PTP`, `FFPP`, `FFAA`, `CCD`, `COI`, `PN`, `CIE`, `CPF`, `DL`, `DPI`, `NIDN` |
| identification.**value**
string
Returned | Value of the identification provided by the user associated with the Visa Alias, which is used to validate the user. Passport number, for example.
**Allowable Values:**
1–35 chars |
| identification.**verificationDetails**
object
Conditionally returned | Verification details associated with the Visa Alias.
This field is returned if it exists in the resource.
**Allowable Values:**
`authDateTime`, `authMethodReference`, `creationDateTime`, `verifiedEmail`, `verifiedPhone` |
| lastModifiedOn
datetime
Conditionally returned | Date and time when the Visa Alias was last modified.
**Allowable Values:**
24 chars
Format: YYYY-MM-DDThh:mm:ss.000Z |
| status
string
Conditionally returned | Status of the Visa Alias.
**Allowable Values:**
`ACTIVE`, `DISABLED`, `BLOCKED`, `EXPIRED` |
Sample response body
```json JSON expandable lines wrap theme={null}
{
"aliasValue": "1231231234",
"profile": {
"lastName": "Miller",
"firstName": "Alex",
"middleName": "Robert",
"contactInfo": [
{
"type": "PHONE",
"value": "1231234321"
}
],
"dateOfBirth": "1980-02-01",
"lastNameLocal": "Miller",
"preferredName": "Miller's Shop",
"firstNameLocal": "Alexander",
"middleNameLocal": "Roberto"
},
"aliasType": "PHONE",
"consent": {
"version": "1.0",
"presenter": "Bank A",
"expiryDateTime": "2025-06-20T10:00:00Z",
"intermediaries": [
"Client A"
],
"validFromDateTime": "2024-12-01T10:00:00Z"
},
"identification": {
"type": "PASSPORT",
"value": "A123456",
"verificationDetails": {
"authDateTime": "2025-01-01T22:52:46Z",
"verifiedEmail": true,
"verifiedPhone": false,
"creationDateTime": "2025-01-01T22:52:46Z",
"authMethodReference": "EXTERNAL, SMS OTP, Email OTP"
}
},
"createdOn": "2025-01-01T22:52:46.000Z",
"lastModifiedOn": "2025-01-01T22:52:46.000Z",
"status": "ACTIVE"
}
```
Update Visa Alias by Visa Alias ID
**Action:** `PUT`\
**Endpoint:** `/digitalwallets/aliasdirectory/visa/aliases/{aliasId}`
{/* */}
Use this endpoint to update a Visa Alias by its Visa Alias ID.
URL path parameters
| Fields | Description |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| aliasId
string
Required | Unique identifier of the Visa Alias.
**Allowable Values:**
Existing Visa Alias ID |
| Fields | Description |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
| participant-id
string
Required | Visa Business Identifier (BID) that is assigned to the program.
**Allowable Values:**
Existing participant ID
For example, "123456789001" |
Request body
| Fields | Description |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| consent
object
Required | Visa Alias Directory Service (ADS) consent information.
**Allowable Values:**
`presenter`, `validFromDateTime`, `version`, `expiryDateTime`, `intermediaries` |
| profile
object
Required | Alias Directory Service (ADS) profile information.
**Allowable Values:**
- `firstName`
- `lastName`
- `contactInfo`
- `dateOfBirth`
- `firstNameLocal`
- `lastNameLocal`
- `middleName`
- `middleNameLocal`
- `preferredName` |
| identification
object
Optional | Identification of the user associated with the Visa Alias.
**Allowable Values:**
`type`, `value`, `verificationDetails` |
Sample request body
```json JSON expandable lines wrap theme={null}
{
"aliasValue": "1231231234",
"aliasType": "PHONE",
"profile": {
"firstName": "Alex",
"middleName": "Robert",
"lastName": "Miller",
"firstNameLocal": "Alexander",
"middleNameLocal": "Roberto",
"lastNameLocal": "Miller",
"preferredName": "Miller's Shop",
"dateOfBirth": "1980-02-01",
"contactInfo": [
{
"type": "PHONE",
"value": "1231234321"
}
]
},
"consent": {
"version": "1.0",
"presenter": "Bank A",
"validFromDateTime": "2024-12-01T10:00:00Z",
"expiryDateTime": "2025-06-20T10:00:00Z",
"intermediaries": [
"Client A"
]
},
"identification": {
"type": "PASSPORT",
"value": "A123456",
"verificationDetails": {
"authDateTime": "2025-01-01T22:52:46Z",
"verifiedEmail": true,
"verifiedPhone": false,
"creationDateTime": "2025-01-01T22:52:46Z",
"authMethodReference": "EXTERNAL, SMS OTP, Email OTP"
}
},
"createdOn": "2025-01-01T22:52:46Z",
"lastModifiedOn": "2025-01-01T22:52:46Z",
"status": "ACTIVE"
}
```
Delete Visa Alias by Visa Alias ID
**Action:** `DELETE`\
**Endpoint:** `/digitalwallets/aliasdirectory/visa/aliases/{aliasId}`
{/* */}
Use this endpoint to delete a Visa Alias by Visa Alias ID.
URL path parameters
| Fields | Description |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| aliasId
string
Required | Unique identifier of the Visa Alias.
**Allowable Values:**
Existing Visa Alias ID |
| Fields | Description |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
| participant-id
string
Required | Visa Business Identifier (BID) that is assigned to the program.
**Allowable Values:**
Existing participant ID
For example, "123456789001" |
Retrieve alias internal ID
**Action:** `POST`\
**Endpoint:** `/digitalwallets/aliasdirectory/visa/aliases/aliasId`
{/* */}
Use this endpoint to retrieve the internal ID associated with a Visa Alias.
| Fields | Description |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
| participant-id
string
Required | Visa Business Identifier (BID) that is assigned to the program.
**Allowable Values:**
Existing participant ID
For example, "123456789001" |
Request body
| Fields | Description |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| aliasValue
string
Optional | Visa Alias value, which can be an email, a phone number, ID of an alias directory, or a payname.
If a phone number is used for the Visa Alias, it must follow ITU-T E.164 (2010) number structure. **NOTE:** In the E.164 format, the "+" sign is not included.
**Allowable Values:**
1–128 chars |
Sample request body
```json JSON lines wrap theme={null}
{
"aliasValue": "my_alias_value_1234"
}
```
Response body
| Fields | Description |
| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| id
string
Conditionally returned | UUID generated by Alias Directory, which identifies the Visa Alias.
**Allowable Values:**
1–128 chars |
Sample response body
```json JSON lines wrap theme={null}
{
"id": "my_alias_id_1234"
}
```
Update alias status
**Action:** `PUT`\
**Endpoint:** `/digitalwallets/aliasdirectory/visa/aliases/{aliasId}/status`
{/* */}
Use this endpoint to update the status of a Visa Alias.
URL path parameters
| Fields | Description |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| aliasId
string
Required | Unique identifier of the Visa Alias.
**Allowable Values:**
Existing Visa Alias ID |
| Fields | Description |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
| participant-id
string
Required | Visa Business Identifier (BID) that is assigned to the program.
**Allowable Values:**
Existing participant ID
For example, "123456789001" |
Request body
| Fields | Description |
| -------------------------------------------- | -------------------------------------------------------------------------------------- |
| status
string
Optional | Status of the Visa Alias.
**Allowable Values:**
ACTIVE, DISABLED |
Sample request body
```json JSON lines wrap theme={null}
{
"status": "ACTIVE"
}
```
Create Visa Alias payment credential
**Action:** `POST`\
**Endpoint:** `/digitalwallets/aliasdirectory/visa/aliases/{aliasId}/cards`
{/* */}
Use this endpoint to create a payment credential associated with a Visa Alias.
URL path parameters
| Fields | Description |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| aliasId
string
Required | Unique identifier of the Visa Alias.
**Allowable Values:**
Existing Visa Alias ID |
| Fields | Description |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
| participant-id
string
Required | Visa Business Identifier (BID) that is assigned to the program.
**Allowable Values:**
Existing participant ID
For example, "123456789001" |
Request body
| Fields | Description |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cardToken
string
Required | Unique identifier of the card token.
**Allowable Values:**
1–36 chars
Existing card token |
| billingAddress
object
Required | Billing address for the payment credential.
**Allowable Values:**
`country`, `addressLine1`, `addressLine2`, `buildingNumber`, `city`, `minorSubdivision`, `postalCode`, `state`, `streetName` |
| nameOnCard
string
Required | Name on the card for the payment credential.
**Allowable Values:**
1–120 chars |
| cardType
string
Required | Type of card for the payment credential.
**Allowable Values:**
1–70 chars |
| issuerName
string
Required | Card issuer’s name for the payment credential.
**Allowable Values:**
1–150 chars |
| currencyCode
string
Optional | Three-digit ISO 4217 currency code for the payment credential.
**Allowable Values:**
3 chars
Valid three-digit ISO 4217 currency code (Alpha-3) |
| preferredFor
array of strings
Optional | Indicates if a payment credential is a preferred Receiving, Sending, or Paying account.
**Allowable Values:**
`RECEIVE`, `SEND`, `PAYING` |
Sample request body
```json JSON expandable lines wrap theme={null}
{
"cardToken": "4111111145551142",
"billingAddress": {
"country": "USA",
"streetName": "12",
"city": "San Francisco",
"postalCode": "94105",
"addressLine1": "1000 Market Street",
"buildingNumber": "56",
"addressLine2": "Suite 101",
"state": "CA",
"minorSubdivisionCode": "CA"
},
"nameOnCard": "John Doe",
"cardType": "Visa Platinum",
"issuerName": "Bank A",
"currencyCode": "USD",
"preferredFor": [
"RECEIVE",
"SEND"
]
}
```
Response body
| Fields | Description |
| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| id
string
Returned | UUID generated by Alias Directory, a utility used to identify the payment credential.
**Allowable Values:**
36 char max |
| type
string
Returned | Indicates the type of payment credential.
**Allowable Values:**
`CARD`, `BANK` |
| externalId
string
Conditionally returned | External ID of the payment credential, which corresponds to Marqeta’s card token.
**Allowable Values:**
1–100 chars |
Sample response body
```json JSON lines wrap theme={null}
{
"id": "a44c9553-e687-4f3c-b7e7-a4245d9f238e",
"type": "CARD",
"externalId": "63421837-d597-4f0f-89e4-930c1a7b9e85"
}
```
Retrieve a Visa Alias payment credentials
**Action:** `GET`\
**Endpoint:** `/digitalwallets/aliasdirectory/visa/aliases/{aliasId}/cards`
{/* */}
Use this endpoint to retrieve a list of payment credentials associated with a Visa Alias.
URL path parameters
| Fields | Description |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| aliasId
string
Required | Unique identifier of the Visa Alias.
**Allowable Values:**
Existing Visa Alias ID |
| Fields | Description |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
| participant-id
string
Required | Visa Business Identifier (BID) that is assigned to the program.
**Allowable Values:**
Existing participant ID
For example, "123456789001" |
Response body
| Fields | Description |
| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GetPaymentCredentialsResponse
array of objects
Conditionally returned | Response containing the payment credentials associated with a Visa Alias.
This array is returned if the Visa Alias exists and one or more payment credentials are linked to it.
**Allowable Values:**
A valid array of payment credentials |
| GetPaymentCredentialsResponse\[].**accountNumber**
string
Returned | Account number of the payment credential.
**Allowable Values:**
12–19 chars |
| GetPaymentCredentialsResponse\[].**billingAddress**
object
Returned | Billing address for the payment credential.
**Allowable Values:**
`country`, `addressLine1`, `addressLine2`, `buildingNumber`, `city`, `minorSubdivision`, `postalCode`, `state`, `streetName` |
| GetPaymentCredentialsResponse\[].billingAddress.**country**
string
Returned | Country of the billing address associated with the payment credential, expressed as an ISO 3166 code. For example, the numeric code for the United States is `840` and the alpha-3 code is `USA`.
The ISO maintains the full list of ISO 3166 country codes.
**Allowable Values:**
3 chars |
| GetPaymentCredentialsResponse\[].billingAddress.**addressLine1**
string
Conditionally returned | Address line 1 of the billing address associated with the payment credential.
**Allowable Values:**
99 char max |
| GetPaymentCredentialsResponse\[].billingAddress.**addressLine2**
string
Conditionally returned | Address line 2 of the billing address associated with the payment credential.
**Allowable Values:**
99 char max |
| GetPaymentCredentialsResponse\[].billingAddress.**buildingNumber**
string
Conditionally returned | Building number of the billing address associated with the payment credential.
**Allowable Values:**
1–60 chars |
| GetPaymentCredentialsResponse\[].billingAddress.**city**
string
Conditionally returned | City of the billing address associated with the payment credential.
**Allowable Values:**
1–35 chars |
| GetPaymentCredentialsResponse\[].billingAddress.**minorSubdivision**
string
Conditionally returned | Minor subdivision of the billing address associated with the payment credential.
**Allowable Values:**
1–50 chars |
| GetPaymentCredentialsResponse\[].billingAddress.**postalCode**
string
Conditionally returned | Postal code of the billing address associated with the payment credential.
**Allowable Values:**
1–16 chars |
| GetPaymentCredentialsResponse\[].billingAddress.**state**
string
Conditionally returned | State of the billing address associated with the payment credential.
**Allowable Values:**
1–16 chars |
| GetPaymentCredentialsResponse\[].billingAddress.**streetName**
string
Conditionally returned | Street name of the billing address associated with the payment credential.
**Allowable Values:**
1–60 chars |
| GetPaymentCredentialsResponse\[].**type**
string
Returned | Type of payment credential associated with the Visa Alias.
**Allowable Values:**
`CARD` |
| GetPaymentCredentialsResponse\[].**accountNumberType**
string
Conditionally returned | Type of account number associated with the payment credential.
**Allowable Values:**
`PAN`, `NIUBIZ`, `TOKEN` |
| GetPaymentCredentialsResponse\[].**cardType**
string
Conditionally returned | Type of card associated with the payment credential.
**Allowable Values:**
1–70 chars |
| GetPaymentCredentialsResponse\[].**createdOn**
datetime
Conditionally returned | Date and time when the payment credential was created.
**Allowable Values:**
24 chars
Format: YYYY-MM-DDTHH:MM:SS.000Z |
| GetPaymentCredentialsResponse\[].**currencyCode**
string
Conditionally returned | Three-digit ISO 4217 currency code for the payment credential.
**Allowable Values:**
3 chars
Valid three-digit ISO 4217 currency code (Alpha-3) |
| GetPaymentCredentialsResponse\[].**expirationDate**
string
Conditionally returned | Expiration date of the card.
**Allowable Values:**
7 chars
Format: YYYY-MM |
| GetPaymentCredentialsResponse\[].**externalId**
string
Conditionally returned | External ID of the payment credential, which corresponds to Marqeta’s card token.
**Allowable Values:**
1–100 chars |
| GetPaymentCredentialsResponse\[].**id**
string
Conditionally returned | Unique identifier of the payment credential generated by Alias Directory.
**Allowable Values:**
1–36 chars |
| GetPaymentCredentialsResponse\[].**issuerName**
string
Conditionally returned | Name of the issuer of the payment credential.
**Allowable Values:**
1–150 chars |
| GetPaymentCredentialsResponse\[].**lastFourDigits**
string
Conditionally returned | Last four digits of the card number.
**Allowable Values:**
4 chars |
| GetPaymentCredentialsResponse\[].**lastUpdatedOn**
datetime
Conditionally returned | Date and time when the payment credential was last updated.
**Allowable Values:**
24 chars
Format: YYYY-MM-DDTHH:MM:SS.000Z |
| GetPaymentCredentialsResponse\[].**nameOnCard**
string
Conditionally returned | Name on the card associated with the payment credential.
**Allowable Values:**
1–120 chars |
| GetPaymentCredentialsResponse\[].**preferredFor**
array of objects
Conditionally returned | Indicates if a payment credential is a preferred Receiving, Sending, or Paying account.
This array is returned if you passed the `preferredFor` field when creating a Visa Alias or when adding a new payment credential to an existing Visa Alias.
**Allowable Values:**
A valid array of `preferredFor` objects |
| GetPaymentCredentialsResponse\[].preferredFor\[].**type**
string
Returned | Type of operation associated with the payment credential.
**Allowable Values:**
`RECEIVE`, `SEND`, `PAY` |
| GetPaymentCredentialsResponse\[].preferredFor\[].**date**
date
Conditionally returned | Date of the Receiving, Sending, or Paying operation.
**Allowable Values:**
10 chars
Format: YYYY-MM-DD |
| GetPaymentCredentialsResponse\[].**status**
string
Conditionally returned | Status of the payment credential associated with the Visa Alias.
**Allowable Values:**
`ACTIVE`, `BLOCKED`, `DISABLED`, `EXPIRED` |
Sample response body
```json JSON expandable lines wrap theme={null}
{
"accountNumber": 4111111145551142,
"billingAddress": {
"city": "San Francisco",
"state": "CA",
"country": "USA",
"postalCode": 94105,
"streetName": 12,
"addressLine1": "1000 Market Street",
"addressLine2": "Suite 101",
"buildingNumber": 56,
"minorSubdivisionCode": "CA"
},
"type": "CARD",
"accountNumberType": "TOKEN",
"cardType": "Visa Platinum",
"createdOn": "2025-06-21T13:00:00Z",
"currencyCode": "USD",
"expirationDate": "2026-01",
"externalId": "63421837-d597-4f0f-89e4-930c1a7b9e85",
"id": "a44c9553-e687-4f3c-b7e7-a4245d9f238e",
"issuerName": "Bank A",
"lastFourDigits": 1142,
"lastUpdatedOn": "2025-06-22T15:12:00Z",
"nameOnCard": "Alex Miller",
"preferredFor": [
{
"date": "2025-01-01",
"type": "RECEIVE"
}
],
"status": "ACTIVE"
}
```
Retrieve payment credential
**Action:** `GET`\
**Endpoint:** `/digitalwallets/aliasdirectory/visa/cards/{paymentCredentialId}`
{/* */}
Use this endpoint to retrieve an existing payment credential.
URL path parameters
| Fields | Description |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| paymentCredentialId
string
Required | Unique identifier of an existing payment credential.
**Allowable Values:**
Existing payment credential ID |
| Fields | Description |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
| participant-id
string
Required | Visa Business Identifier (BID) that is assigned to the program.
**Allowable Values:**
Existing participant ID
For example, "123456789001" |
Response body
| Fields | Description |
| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GetPaymentCredentialsResponse
array of objects
Conditionally returned | Response containing the payment credentials associated with a Visa Alias.
This array is returned if the Visa Alias exists and one or more payment credentials are linked to it.
**Allowable Values:**
A valid array of payment credentials |
| GetPaymentCredentialsResponse\[].**accountNumber**
string
Returned | Account number of the payment credential.
**Allowable Values:**
12–19 chars |
| GetPaymentCredentialsResponse\[].**billingAddress**
object
Returned | Billing address for the payment credential.
**Allowable Values:**
`country`, `addressLine1`, `addressLine2`, `buildingNumber`, `city`, `minorSubdivision`, `postalCode`, `state`, `streetName` |
| GetPaymentCredentialsResponse\[].billingAddress.**country**
string
Returned | Country of the billing address associated with the payment credential, expressed as an ISO 3166 code. For example, the numeric code for the United States is `840` and the alpha-3 code is `USA`.
The ISO maintains the full list of ISO 3166 country codes.
**Allowable Values:**
3 chars |
| GetPaymentCredentialsResponse\[].billingAddress.**addressLine1**
string
Conditionally returned | Address line 1 of the billing address associated with the payment credential.
**Allowable Values:**
99 char max |
| GetPaymentCredentialsResponse\[].billingAddress.**addressLine2**
string
Conditionally returned | Address line 2 of the billing address associated with the payment credential.
**Allowable Values:**
99 char max |
| GetPaymentCredentialsResponse\[].billingAddress.**buildingNumber**
string
Conditionally returned | Building number of the billing address associated with the payment credential.
**Allowable Values:**
1–60 chars |
| GetPaymentCredentialsResponse\[].billingAddress.**city**
string
Conditionally returned | City of the billing address associated with the payment credential.
**Allowable Values:**
1–35 chars |
| GetPaymentCredentialsResponse\[].billingAddress.**minorSubdivision**
string
Conditionally returned | Minor subdivision of the billing address associated with the payment credential.
**Allowable Values:**
1–50 chars |
| GetPaymentCredentialsResponse\[].billingAddress.**postalCode**
string
Conditionally returned | Postal code of the billing address associated with the payment credential.
**Allowable Values:**
1–16 chars |
| GetPaymentCredentialsResponse\[].billingAddress.**state**
string
Conditionally returned | State of the billing address associated with the payment credential.
**Allowable Values:**
1–16 chars |
| GetPaymentCredentialsResponse\[].billingAddress.**streetName**
string
Conditionally returned | Street name of the billing address associated with the payment credential.
**Allowable Values:**
1–60 chars |
| GetPaymentCredentialsResponse\[].**type**
string
Returned | Type of payment credential associated with the Visa Alias.
**Allowable Values:**
`CARD` |
| GetPaymentCredentialsResponse\[].**accountNumberType**
string
Conditionally returned | Type of account number associated with the payment credential.
**Allowable Values:**
`PAN`, `NIUBIZ`, `TOKEN` |
| GetPaymentCredentialsResponse\[].**cardType**
string
Conditionally returned | Type of card associated with the payment credential.
**Allowable Values:**
1–70 chars |
| GetPaymentCredentialsResponse\[].**createdOn**
datetime
Conditionally returned | Date and time when the payment credential was created.
**Allowable Values:**
24 chars
Format: YYYY-MM-DDTHH:MM:SS.000Z |
| GetPaymentCredentialsResponse\[].**currencyCode**
string
Conditionally returned | Three-digit ISO 4217 currency code for the payment credential.
**Allowable Values:**
3 chars
Valid three-digit ISO 4217 currency code (Alpha-3) |
| GetPaymentCredentialsResponse\[].**expirationDate**
string
Conditionally returned | Expiration date of the card.
**Allowable Values:**
7 chars
Format: YYYY-MM |
| GetPaymentCredentialsResponse\[].**externalId**
string
Conditionally returned | External ID of the payment credential, which corresponds to Marqeta’s card token.
**Allowable Values:**
1–100 chars |
| GetPaymentCredentialsResponse\[].**id**
string
Conditionally returned | Unique identifier of the payment credential generated by Alias Directory.
**Allowable Values:**
1–36 chars |
| GetPaymentCredentialsResponse\[].**issuerName**
string
Conditionally returned | Name of the issuer of the payment credential.
**Allowable Values:**
1–150 chars |
| GetPaymentCredentialsResponse\[].**lastFourDigits**
string
Conditionally returned | Last four digits of the card number.
**Allowable Values:**
4 chars |
| GetPaymentCredentialsResponse\[].**lastUpdatedOn**
datetime
Conditionally returned | Date and time when the payment credential was last updated.
**Allowable Values:**
24 chars
Format: YYYY-MM-DDTHH:MM:SS.000Z |
| GetPaymentCredentialsResponse\[].**nameOnCard**
string
Conditionally returned | Name on the card associated with the payment credential.
**Allowable Values:**
1–120 chars |
| GetPaymentCredentialsResponse\[].**preferredFor**
array of objects
Conditionally returned | Indicates if a payment credential is a preferred Receiving, Sending, or Paying account.
This array is returned if you passed the `preferredFor` field when creating a Visa Alias or when adding a new payment credential to an existing Visa Alias.
**Allowable Values:**
A valid array of `preferredFor` objects |
| GetPaymentCredentialsResponse\[].preferredFor\[].**type**
string
Returned | Type of operation associated with the payment credential.
**Allowable Values:**
`RECEIVE`, `SEND`, `PAY` |
| GetPaymentCredentialsResponse\[].preferredFor\[].**date**
date
Conditionally returned | Date of the Receiving, Sending, or Paying operation.
**Allowable Values:**
10 chars
Format: YYYY-MM-DD |
| GetPaymentCredentialsResponse\[].**status**
string
Conditionally returned | Status of the payment credential associated with the Visa Alias.
**Allowable Values:**
`ACTIVE`, `BLOCKED`, `DISABLED`, `EXPIRED` |
Sample response body
```json JSON expandable lines wrap theme={null}
{
"accountNumber": "4111111145551142",
"billingAddress": {
"city": "San Francisco",
"state": "CA",
"country": "USA",
"postalCode": "94105",
"streetName": 12,
"addressLine1": "1000 Market Street",
"addressLine2": "Suite 101",
"buildingNumber": 56,
"minorSubdivisionCode": "CA"
},
"type": "CARD",
"accountNumberType": "TOKEN",
"cardType": "Visa Platinum",
"createdOn": "2025-06-21T13:00:00.645Z",
"currencyCode": "USD",
"expirationDate": "2026-01",
"externalId": "63421837-d597-4f0f-89e4-930c1a7b9e85",
"id": "a44c9553-e687-4f3c-b7e7-a4245d9f238e",
"issuerName": "Bank A",
"lastFourDigits": 1142,
"lastUpdatedOn": "2025-06-22T15:12:00.322Z",
"nameOnCard": "Alex Miller",
"preferredFor": [
{
"date": "2025-01-01",
"type": "RECEIVE"
}
],
"status": "ACTIVE"
}
```
Update payment credential
**Action:** `PUT`\
**Endpoint:** `/digitalwallets/aliasdirectory/visa/cards/{paymentCredentialId}`
{/* */}
Use this endpoint to update an existing payment credential.
URL path parameters
| Fields | Description |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| paymentCredentialId
string
Required | Unique identifier of an existing payment credential.
**Allowable Values:**
Existing payment credential ID |
| Fields | Description |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
| participant-id
string
Required | Visa Business Identifier (BID) that is assigned to the program.
**Allowable Values:**
Existing participant ID
For example, "123456789001" |
Request body
| Fields | Description |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cardToken
string
Required | Unique identifier of the card token.
**Allowable Values:**
1–36 chars
Existing card token |
| billingAddress
object
Required | Billing address for the payment credential.
**Allowable Values:**
`country`, `addressLine1`, `addressLine2`, `buildingNumber`, `city`, `minorSubdivision`, `postalCode`, `state`, `streetName` |
| nameOnCard
string
Required | Name on the card for the payment credential.
**Allowable Values:**
1–120 chars |
| cardType
string
Required | Type of card for the payment credential.
**Allowable Values:**
1–70 chars |
| issuerName
string
Required | Card issuer’s name for the payment credential.
**Allowable Values:**
1–150 chars |
| currencyCode
string
Optional | Three-digit ISO 4217 currency code for the payment credential.
**Allowable Values:**
3 chars
Valid three-digit ISO 4217 currency code (Alpha-3) |
| preferredFor
array of strings
Optional | Indicates if a payment credential is a preferred Receiving, Sending, or Paying account.
**Allowable Values:**
`RECEIVE`, `SEND`, `PAYING` |
Sample request body
```json JSON expandable lines wrap theme={null}
{
"cardToken": "4111111145551142",
"billingAddress": {
"country": "USA",
"streetName": "12",
"city": "San Francisco",
"postalCode": "94105",
"addressLine1": "1000 Market Street",
"buildingNumber": "56",
"addressLine2": "Suite 101",
"state": "CA",
"minorSubdivisionCode": "CA"
},
"nameOnCard": "John Doe",
"cardType": "Visa Platinum",
"issuerName": "Bank A",
"currencyCode": "USD",
"preferredFor": [
"RECEIVE",
"SEND"
]
}
```
Delete an existing payment credential
**Action:** `DELETE`\
**Endpoint:** `/digitalwallets/aliasdirectory/visa/cards/{paymentCredentialId}`
{/* */}
Use this endpoint to delete an existing payment credential.
URL path parameters
| Fields | Description |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| paymentCredentialId
string
Required | Unique identifier of an existing payment credential.
**Allowable Values:**
Existing payment credential ID |
| Fields | Description |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
| participant-id
string
Required | Visa Business Identifier (BID) that is assigned to the program.
**Allowable Values:**
Existing participant ID
For example, "123456789001" |
Create an additional Visa Alias
**Action:** `POST`\
**Endpoint:** `/digitalwallets/aliasdirectory/visa/aliases/{aliasId}/additionalAlias`
{/* */}
Use this endpoint to create additional Visa Aliases associated with an existing main Visa Alias.
URL path parameters
| Fields | Description |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| aliasId
string
Required | Unique identifier of the Visa Alias.
**Allowable Values:**
Existing Visa Alias ID |
| Fields | Description |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
| participant-id
string
Required | Visa Business Identifier (BID) that is assigned to the program.
**Allowable Values:**
Existing participant ID
For example, "123456789001" |
Request body
| Fields | Description |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| type
string
Required | Type of the additional Visa Alias.
**Allowable Values:**
`EMAIL`, `PHONE` |
| value
string
Required | Unique identifier that represents the customer in the payment ecosystem.
**Allowable Values:**
1–128 chars |
Sample request body
```json JSON lines wrap theme={null}
{
"type": "EMAIL",
"value": "1231231234"
}
```
Response body
| Fields | Description |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| id
string
Returned | UUID generated by Alias Directory, which identifies the Visa Alias.
**Allowable Values:**
1–36 chars |
Sample response body
```json JSON lines wrap theme={null}
{
"id": "my_alias_id_1234"
}
```
Delete an additional Visa Alias
**Action:** `DELETE`\
**Endpoint:** `/digitalwallets/aliasdirectory/visa/additionalAliases/{additionalAliasId}`
{/* */}
Use this endpoint to delete an additional Visa Alias by its Visa Alias ID.
URL path parameters
| Fields | Description |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| additionalAliasId
string
Required | Unique identifier of the additional Visa Aliases.
**Allowable Values:**
Existing additional Visa Alias ID |
| Fields | Description |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
| participant-id
string
Required | Visa Business Identifier (BID) that is assigned to the program.
**Allowable Values:**
Existing participant ID
For example, "123456789001" |
Retrieve Visa Alias by external ID
**Action:** `POST`\
**Endpoint:** `/digitalwallets/aliasdirectory/visa/aliases/getByExternalId`
{/* */}
Use this endpoint to retrieve a Visa Alias by its external ID.
| Fields | Description |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
| participant-id
string
Required | Visa Business Identifier (BID) that is assigned to the program.
**Allowable Values:**
Existing participant ID
For example, "123456789001" |
Request body
| Fields | Description |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| externalId
string
Required | External ID of the Visa Alias.
**Allowable Values:**
1–100 chars |
| type
string
Required | Type of Visa Alias in the Alias Directory Service (ADS) profile. Visa supports phone and email as Visa Alias types that can be used in place of sensitive payment credentials.
**Allowable Values:**
`ALIAS`, `PAYMENT_CREDENTIAL` |
Sample request body
```json JSON lines wrap theme={null}
{
"externalId": "21267931-7975-4b61-be7a-86915883b2b4",
"type": "ALIAS"
}
```
Response body
| Fields | Description |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| associatedIds
array of objects
Returned | List of associated Visa Alias IDs.
**Allowable Values:**
`associatedIds` |
| associatedIds\[].**id**
string
Conditionally returned | ID of the payment credential associated with the Visa Alias.
**Allowable Values:**
1–64 chars |
| associatedIds\[].**type**
string
Conditionally returned | Type of payment credential associated with the Visa Alias.
**Allowable Values:**
`ALIAS`, `PAYMENT_CREDENTIAL` |
| id
string
Conditionally returned | UUID generated by Alias Directory, which identifies the Visa Alias.
**Allowable Values:**
1–36 chars |
Sample response body
```json JSON lines wrap theme={null}
{
"associatedIds": [
{
"id": "a44c9553-e687-4f3c-b7e7-a4245d9f238e",
"type": "PAYMENT_CREDENTIAL"
}
],
"id": "e336c8c8-2945-4be3-af3e-951ec2d01219"
}
```
Create a report request
**Action:** `POST`\
**Endpoint:** `/digitalwallets/aliasdirectory/visa/reports`
{/* */}
Use this endpoint to create a new report request.
| Fields | Description |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
| participant-id
string
Required | Visa Business Identifier (BID) that is assigned to the program.
**Allowable Values:**
Existing participant ID
For example, "123456789001" |
Request body
| Fields | Description |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters
object
Required | Filters for the report.
**Allowable Values:**
`aliasStatuses`, `aliasType`, `billingEventTypes`, `endDate`, `startDate` |
| format
string
Required | The format of the report
**Allowable Values:**
1–36 chars |
| reportType
string
Required | Indicates the type of report.
**Allowable Values:**
`DIRECTORY_STATUS`, `PLATFORM_REQUESTS`, `RESOLUTION_RECONCILIATION`, `DIRECTORY_ACTIVITY`, `PAYMENT_CREDENTIAL_DETAILS` |
Sample request body
```json JSON lines wrap theme={null}
{
"format": "JSON",
"filters": {
"endDate": "2025-01-01T22:52:46Z",
"aliasType": "PHONE",
"startDate": "2025-01-01T22:52:46Z",
"aliasStatuses": [
"ACTIVE"
],
"billingEventTypes": [
"createAlias"
]
},
"reportType": "PLATFORM_REQUESTS"
}
```
Response body
| Fields | Description |
| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| reportId
string
Conditionally returned | Unique identifier of the report.
**Allowable Values:**
36 char max |
Sample response body
```json JSON lines wrap theme={null}
{
"reportId": "my_report_id_1234"
}
```
Retrieve report status by report ID
**Action:** `GET`\
**Endpoint:** `/digitalwallets/aliasdirectory/visa/reports/{reportId}`
{/* */}
Use this endpoint to retrieve the status of a report by its report ID.
URL path parameters
| Fields | Description |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| reportId
string
Required | Unique identifier of the report.
**Allowable Values:**
Existing report ID |
| Fields | Description |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
| participant-id
string
Required | Visa Business Identifier (BID) that is assigned to the program.
**Allowable Values:**
Existing participant ID
For example, "123456789001" |
Response body
| Fields | Description |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| creationDateTime
datetime
Conditionally returned | The timestamp when the report was created in ISO UTC format YYYY-MM-DDThh:mm:ss.000Z
**Allowable Values:**
`YYYY-MM-DDThh:mm:ss.000Z` |
| dataClassification
string
Conditionally returned | Data classification of the report.
**Allowable Values:**
1–36 chars |
| expirationDateTime
datetime
Conditionally returned | The timestamp after which the report won’t be available for download in ISO UTC format YYYY-MM-DDThh:mm:ss.000Z
**Allowable Values:**
`YYYY-MM-DDThh:mm:ss.000Z` |
| fileIds
array of strings
Conditionally returned | UUIDs of the files generated by the report.
**Allowable Values:** |
| format
string
Conditionally returned | Format of the report.
**Allowable Values:**
1–36 chars |
| id
string
Conditionally returned | UUID generated by Alias Directory, which identifies the report.
**Allowable Values:**
1–36 chars |
| reportType
string
Conditionally returned | Indicates the type of report.
**Allowable Values:**
`PLATFORM_REQUESTS`, `DIRECTORY_STATUS`, `PAYMENT_CREDENTIAL_DETAILS` |
| status
string
Conditionally returned | Indicates the status of the report.
**Allowable Values:**
`CREATED`, `IN_PROGRESS`, `COMPLETED` |
Sample response body
```json JSON lines wrap theme={null}
{
"id": "a77ef5c5-c972-467b-9a11-ac550183b495",
"format": "JSON",
"status": "COMPLETED",
"fileIds": [
"000001-a96032e1-0ad9-4937-9320-a2a28b139ea5, 000002-a96032e1-0ad9-4937-9320-a2a28b139ea5"
],
"reportType": "PLATFORM_REQUESTS",
"creationDateTime": "2025-01-01T22:52:46Z",
"dataClassification": "VERY_IMPORTANT",
"expirationDateTime": "2025-01-01T22:52:46Z"
}
```
Retrieve file by file ID and report ID
**Action:** `GET`\
**Endpoint:** `/digitalwallets/aliasdirectory/visa/reports/{reportId}/file/{fileId}`
{/* */}
Use this endpoint to retrieve a file by its file ID and report ID.
URL path parameters
| Fields | Description |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| reportId
string
Required | Unique identifier of the report.
**Allowable Values:**
Existing report ID |
| fileId
string
Required | Unique identifier of the file.
**Allowable Values:**
Existing file ID |
| Fields | Description |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
| participant-id
string
Required | Visa Business Identifier (BID) that is assigned to the program.
**Allowable Values:**
Existing participant ID
For example, "123456789001" |
Response body
| Fields | Description |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| programId
string
Conditionally returned | ID associated with the program.
**Allowable Values:**
255 char max |
| statusCode
integer
Conditionally returned | Status code of the operation.
**Allowable Values:**
Any integer |
| operationType
string
Conditionally returned | Indicates the type of operation.
**Allowable Values:**
255 char max |
| operationsCount
integer
Conditionally returned | Number of operations in the report.
**Allowable Values:**
Any integer |
| originatorActorId
string
Conditionally returned | Indicates the Originator Actor ID.
**Allowable Values:**
255 char max |
Sample response body
```json JSON lines wrap theme={null}
[
{
"programId": "baf85624-3cf6-4c52-b91f-b8f3493e7330",
"statusCode": 200,
"operationType": "resolveAlias",
"operationsCount": 18,
"originatorActorId": "012af73f-44d8-4c9c-bbee-628b07faae1c"
}
]
```
Check for Visa Alias
**Action:** `POST`\
**Endpoint:** `/digitalwallets/aliasdirectory/visa/aliases/inquiry`
{/* */}
Use this endpoint to check for available Visa Aliases for alias resolution. One or more Visa Aliases may be available.
| Fields | Description |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| participant-id
string
Required | Visa Business Identifier (BID) that is assigned to the program.
**Allowable Values:**
Existing participant ID
For example, "123456789001" |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
Request body
| Fields | Description |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| aliases
array of strings
Required | List of Visa Aliases to check for availability.
**Allowable Values:**
1–128 chars |
| filters
array of objects
Optional | List of filters to apply in the request to check Visa Alias availability.
**Allowable Values:**
1-3 items |
| transactionDetails
object
Optional | Details of the transaction associated with the Alias.
**Allowable Values:**
`currencyCode` |
| userDetails
object
Optional | Details of the user requesting the Visa Alias information. The information must not contain personal identifiable information (PII).
**Allowable Values:**
`userName` |
Sample request body
```json JSON expandable lines wrap theme={null}
{
"aliases": [
"123456"
],
"filters": [
{
"field": "DIRECTORY_NAME",
"value": [
"DIRECTORY_A",
"DIRECTORY_B",
"DIRECTORY_C"
]
}
],
"transactionDetails": {
"currencyCode": "USD"
},
"userDetails": {
"userName": "johndoe313"
}
}
```
Response body
| Fields | Description |
| ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| summary
object
Required | Summary of available Visa Aliases
**Allowable Values:**
`aliasesFound`, `aliasesNotFound`, `aliasesRepeated`, `aliasesTotal` |
| summary.**aliasesFound**
integer
Required | Number of available Visa Aliases found.
**Allowable Values:**
0-900 |
| summary.**aliasesNotFound**
integer
Required | Number of Visa Aliases not found.
**Allowable Values:**
0-900 |
| summary.**aliasesRepeated**
integer
Required | Number of duplicate Visa Aliases.
**Allowable Values:**
0-900 |
| summary.**aliasesTotal**
integer
Required | Total number of available Visa Aliases.
**Allowable Values:**
0-900 |
| details
array of objects
Optional | Information associated with available Visa Aliases.
**Allowable Values:**
`aliasType`, `aliasValue`, `directories`, `directoriesNames` |
| details.**aliasType**
string
Required | Type of Visa Alias in the Alias Directory Service (ADS) profile. Visa supports phone and email as Visa Alias types that can be used in place of sensitive payment credentials details.
**Allowable Values:**
`EMAIL`, `PHONE`, `DIRECTORY_ALIASID`, `PAYNAME` |
| details.**aliasValue**
string
Required | Visa Alias value, which can be an email, a phone number, ID of an alias directory, or a payname.
If a phone number is used for the Visa Alias, it must follow ITU-T E.164 (2010) number structure. **NOTE:** In the E.164 format, the "+" sign is not included.
**Allowable Values:**
1-128 char |
| details.**directories**
array of objects
Required | List of directories associated with the Visa Alias.
**Allowable Values:**
`directoryName`, `entities` |
| details.directories.**directoryName**
string
Required | The directory name for the Visa Alias.
**Allowable Values:**
25 char |
| details.directories.**entities**
array of objects
Required | List of entities associated with the directory.
**Allowable Values:**
`id`, `preferredFor` |
| details.directories.entities.**preferredFor**
array of objects
Conditionally returned | List of preferred payment methods for the entity.
**Allowable Values:**
0-10 items |
| details.directories.entities.preferredFor.**type**
string
Returned | Type of operation associated with the payment credential.
**Allowable Values:**
`RECEIVE`, `SEND`, `PAY` |
| details.directories.entities.preferredFor.**date**
date
Conditionally returned | Date of the Receiving, Sending, or Paying operation.
**Allowable Values:**
10 chars |
| details.**directoriesNames**
array
Required | List of directory names associated with the Visa Alias.
**Allowable Values:**
Array of 0-10 directory names |
Sample response body
```json JSON expandable lines wrap theme={null}
[
{
"summary": {
"aliasesFound": 1,
"aliasesTotal": 1,
"aliasesNotFound": 0,
"aliasesRepeated": 0
},
"details": [
{
"aliasType": "PHONE",
"aliasValue": "123456",
"directories": [
{
"entities": [
{
"id": "1101"
},
{
"id": "1102",
"preferredFor": [
{
"date": "1980-02-01",
"type": "RECEIVE"
}
]
}
],
"directoryName": "DIRECTORY_A"
},
{
"directoryName": "DIRECTORY_B"
}
],
"directoriesName": [
"DIRECTORY_A",
"DIRECTORY_B"
]
}
]
}
]
```
Resolve a Visa Alias
**Action:** `POST`\
**Endpoint:** `/digitalwallets/aliasdirectory/visa/aliases/resolve`
{/* */}
Retrieve information about a Visa Alias and all the associated payment credentials.
| Fields | Description |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| participant-id
string
Required | Visa Business Identifier (BID) that is assigned to the program.
**Allowable Values:**
Existing participant ID
For example, "123456789001" |
| req-sys-id
string
Required | Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta.
**Allowable Values:**
36 char max |
Request body
| Fields | Description |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| aliasType
string
Required | Type of Visa Alias in the Alias Directory Service (ADS) profile. Visa supports phone and email as Visa Alias types that can be used in place of sensitive payment credentials details.
**Allowable Values:**
`EMAIL`, `PHONE`, `DIRECTORY_ALIASID`, `PAYNAME` |
| aliasValue
string
Required | Visa Alias value, which can be an email, a phone number, ID of an alias directory, or a payname.
If a phone number is used for the Visa Alias, it must follow ITU-T E.164 (2010) number structure. **NOTE:** In the E.164 format, the "+" sign is not included.
**Allowable Values:**
1–128 chars |
| filters
array of objects
Optional | List of filters to apply in the request for Visa Alias resolution.
**Allowable Values:** |
| transactionDetails
object
Optional | Details of the transaction associated with the Alias.
**Allowable Values:**
`currencyCode` |
| userDetails
object
Optional | Details of the user requesting the Visa Alias information. The information must not contain personal identifiable information (PII).
**Allowable Values:**
`userName` |
Sample request body
```json JSON lines wrap theme={null}
{
"aliasType": "PHONE",
"aliasValue": "1231231234",
"transactionDetails": {
"currencyCode": "USD"
},
"filters": [
{
"field": "DIRECTORY_NAME",
"value": [
"DIRECTORY_A",
"DIRECTORY_B",
"DIRECTORY_C"
]
}
],
"userDetails": {
"userName": "username1234"
}
}
```
Response body
| Fields | Description |
| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| directoryName
string
Required | The directory name of the Visa Alias.
**Allowable Values:**
1-128 chars |
| identification
object
Optional | Identification of the user associated with the Visa Alias.
**Allowable Values:**
`type`, `value`, `verificationDetails` |
| identification.**type**
string
Returned | Type of identification provided by the user associated with the Visa Alias.
**Allowable Values:**
`DNI`, `CE`, `PASSPORT`, `PTP`, `FFPP`, `FFAA`, `CCD`, `COI`, `PN`, `CIE`, `CPF`, `DL`, `DPI`, `NIDN` |
| identification.**value**
string
Returned | Value of the identification provided by the user associated with the Visa Alias, which is used to validate the user. Passport number, for example.
**Allowable Values:**
1–35 chars |
| identification.**verificationDetails**
object
Conditionally returned | Verification details associated with the Visa Alias.
This field is returned if it exists in the resource.
**Allowable Values:**
`authDateTime`, `authMethodReference`, `creationDateTime`, `verifiedEmail`, `verifiedPhone` |
| identification.verificationDetails.**authDateTime**
datetime
Conditionally returned | Time when the user provided the credentials for verification in ISO UTC format.
**Allowable Values:**
Format: YYYY-MM-DDThh:mm:ss.000Z |
| identification.verificationDetails.**authMethodReference**
string
Conditionally returned | Authentication method used when the user provided the credentials for verification.
**Allowable Values:**
256 char |
| identification.verificationDetails.**creationDateTime**
datetime
Conditionally returned | Time when the user was created or enrolled in ISO UTC format.
**Allowable Values:**
Format: YYYY-MM-DDThh:mm:ss.000Z |
| identification.verificationDetails.**verifiedEmail**
boolean
Conditionally returned | True if an email was verified during the verification process. This email does not need to match the Alias or contact info if an email was used.
**Allowable Values:**
`true` , `false` |
| identification.verificationDetails.**verifiedPhone**
boolean
Conditionally returned | True if a phone number was verified during the verification process. This phone number does not need to match the Alias or contact info if a phone number was used.
**Allowable Values:**
`true` , `false` |
| paymentCredentials
array
Required | List of payment credentials associated with the Visa Alias.
**Allowable Values:**
1-10 items |
| paymentCredentials.**accountNumber**
string
Returned | Account number of the payment credential.
**Allowable Values:**
12–19 chars |
| paymentCredentials.**billingAddress**
object
Returned | Billing address for the payment credential.
**Allowable Values:**
`country`, `addressLine1`, `addressLine2`, `buildingNumber`, `city`, `minorSubdivision`, `postalCode`, `state`, `streetName` |
| paymentCredentials.billingAddress.**country**
string
Returned | Country of the billing address associated with the payment credential, expressed as an ISO 3166 code. For example, the numeric code for the United States is `840` and the alpha-3 code is `USA`.
The ISO maintains the full list of ISO 3166 country codes.
**Allowable Values:**
3 chars |
| paymentCredentials.billingAddress.**addressLine1**
string
Conditionally returned | Address line 1 of the billing address associated with the payment credential.
**Allowable Values:**
99 char max |
| paymentCredentials.billingAddress.**addressLine2**
string
Conditionally returned | Address line 2 of the billing address associated with the payment credential.
**Allowable Values:**
99 char max |
| paymentCredentials.billingAddress.**buildingNumber**
string
Conditionally returned | Building number of the billing address associated with the payment credential.
**Allowable Values:**
1–60 chars |
| paymentCredentials.billingAddress.**city**
string
Conditionally returned | City of the billing address associated with the payment credential.
**Allowable Values:**
1–35 chars |
| paymentCredentials.billingAddress.**minorSubdivision**
string
Conditionally returned | Minor subdivision of the billing address associated with the payment credential.
**Allowable Values:**
1–50 chars |
| paymentCredentials.billingAddress.**postalCode**
string
Conditionally returned | Postal code of the billing address associated with the payment credential.
**Allowable Values:**
1–16 chars |
| paymentCredentials.billingAddress.**state**
string
Conditionally returned | State of the billing address associated with the payment credential.
**Allowable Values:**
1–16 chars |
| paymentCredentials.billingAddress.**streetName**
string
Conditionally returned | Street name of the billing address associated with the payment credential.
**Allowable Values:**
1–60 chars |
| paymentCredentials.**type**
string
Returned | Type of payment credential associated with the Visa Alias.
**Allowable Values:**
`CARD` |
| paymentCredentials.**accountNumberType**
string
Conditionally returned | Type of account number associated with the payment credential.
**Allowable Values:**
`PAN`, `NIUBIZ`, `TOKEN` |
| paymentCredentials.**cardType**
string
Conditionally returned | Type of card associated with the payment credential.
**Allowable Values:**
1–70 chars |
| paymentCredentials.**createdOn**
datetime
Conditionally returned | Date and time when the payment credential was created.
**Allowable Values:**
24 chars
Format: YYYY-MM-DDTHH:MM:SS.000Z |
| paymentCredentials.**currencyCode**
string
Conditionally returned | Three-digit ISO 4217 currency code for the payment credential.
**Allowable Values:**
3 chars
Valid three-digit ISO 4217 currency code (Alpha-3) |
| paymentCredentials.**expirationDate**
string
Conditionally returned | Expiration date of the card.
**Allowable Values:**
7 chars
Format: YYYY-MM |
| paymentCredentials.**externalId**
string
Conditionally returned | External ID of the payment credential, which corresponds to Marqeta’s card token.
**Allowable Values:**
1–100 chars |
| paymentCredentials.**id**
string
Conditionally returned | Unique identifier of the payment credential generated by Alias Directory.
**Allowable Values:**
1–36 chars |
| paymentCredentials.**issuerName**
string
Conditionally returned | Name of the issuer of the payment credential.
**Allowable Values:**
1–150 chars |
| paymentCredentials.**lastFourDigits**
string
Conditionally returned | Last four digits of the card number.
**Allowable Values:**
4 chars |
| paymentCredentials.**lastUpdatedOn**
datetime
Conditionally returned | Date and time when the payment credential was last updated.
**Allowable Values:**
24 chars
Format: YYYY-MM-DDTHH:MM:SS.000Z |
| paymentCredentials.**nameOnCard**
string
Conditionally returned | Name on the card associated with the payment credential.
**Allowable Values:**
1–120 chars |
| paymentCredentials.**preferredFor**
array of objects
Conditionally returned | Indicates if a payment credential is a preferred Receiving, Sending, or Paying account.
This array is returned if you passed the `preferredFor` field when creating a Visa Alias or when adding a new payment credential to an existing Visa Alias.
**Allowable Values:**
A valid array of `preferredFor` objects |
| paymentCredentials.preferredFor\[].**type**
string
Returned | Type of operation associated with the payment credential.
**Allowable Values:**
`RECEIVE`, `SEND`, `PAY` |
| paymentCredentials.preferredFor\[].**date**
date
Conditionally returned | Date of the Receiving, Sending, or Paying operation.
**Allowable Values:**
10 chars
Format: YYYY-MM-DD |
| paymentCredentials.**status**
string
Conditionally returned | Status of the payment credential associated with the Visa Alias.
**Allowable Values:**
`ACTIVE`, `BLOCKED`, `DISABLED`, `EXPIRED` |
| profile
object
Required | Alias Directory Service (ADS) profile information.
**Allowable Values:**
`firstName`, `lastName`, `contactInfo`, `dateOfBirth`, `firstNameLocal`, `lastNameLocal`, `middleName`, `middleNameLocal`, `preferredName` |
| profile.**lastName**
string
Required | Last name in the Alias Directory Service (ADS) profile. Participants in the CEMEA and EU regions must only use the initial of the consumer’s last name followed by a period to create or modify a Visa Alias record.
**Allowable Values:**
1–35 chars |
| profile.**firstName**
string
Required | First name in the Alias Directory Service (ADS) profile.
**Allowable Values:**
1–35 chars |
| profile.**middleName**
string
Optional | Middle name in the Alias Directory Service (ADS) profile.
**Allowable Values:**
1–35 chars |
| profile.**contactInfo**
object
Required | Contact information in the Alias Directory Service (ADS) profile.
**Allowable Values:**
`type`, `value` |
| profile.contactInfo.**type**
string
Required | Type of contact information in the Alias Directory Service (ADS) profile.
**Allowable Values:**
`EMAIL`, `PHONE`, `DIRECTORY_ALIASID` |
| profile.contactInfo.**value**
string
Required | Contact information value, which is the email address or phone number.
**Allowable Values:**
1-320 chars |
| profile.**dateOfBirth**
date
Optional | Date of birth in the Alias Directory Service (ADS) profile.
**Allowable Values:**
10 chars |
| profile.**lastNameLocal**
string
Optional | Last name in the Alias Directory Service (ADS) profile, expressed in the user’s local language.
**Allowable Values:**
1–35 chars |
| profile.**preferredName**
string
Optional | Preferred name in the Alias Directory Service (ADS) profile, as provided by the user.
**Allowable Values:**
1–35 chars |
| profile.**firstNameLocal**
string
Optional | First name in the Alias Directory Service (ADS) profile, expressed in the user’s local language.
**Allowable Values:**
1–35 chars |
| profile.**middleNameLocal**
string
Optional | Middle name in the Alias Directory Service (ADS) profile, expressed in the user’s local language.
**Allowable Values:**
1–35 chars |
Sample response body
```json JSON expandable lines wrap theme={null}
[
{
"directoryName": "DIRECTORY_A",
"paymentCredentials": [
{
"type": "CARD",
"cardType": "Visa Platinum",
"issuerName": "Bank A",
"nameOnCard": "Alex Miller",
"currencyCode": "USD",
"accountNumber": "4111111145551142",
"billingAddress": {
"city": "San Francisco",
"state": "CA",
"country": "USA",
"postalCode": "94105",
"streetName": "12",
"addressLine1": "1000 Market Street",
"addressLine2": "Suite 101",
"buildingNumber": "56",
"minorSubdivisionCode": "CA"
},
"expirationDate": "2026-01",
"lastFourDigits": "1142",
"accountNumberType": "TOKEN",
"modifiedOn": "2021-01-01T22:52:46.000Z",
"preferredFor": [
{
"date": "2021-01-01",
"type": "RECEIVE"
}
]
}
],
"profile": {
"lastName": "Miller",
"firstName": "Alex",
"middleName": "Robert",
"contactInfo": [
{
"type": "PHONE",
"value": "1231234321"
}
],
"dateOfBirth": "1980-02-01",
"lastNameLocal": "Miller",
"preferredName": "Miller's Shop",
"firstNameLocal": "Alexander",
"middleNameLocal": "Roberto"
},
"identification": {
"type": "PASSPORT",
"value": "A123456",
"verificationDetails": {
"authDateTime": "2021-01-01T22:52:46Z",
"verifiedEmail": true,
"verifiedPhone": false,
"creationDateTime": "2021-01-01T22:52:46Z",
"authMethodReference": "EXTERNAL, SMS OTP, Email OTP"
}
}
}
]
```
## Related topics
- [Digital Wallets Overview](/docs/developer-guides/digital-wallets-landing-page.md)
- [Digital Wallets and Tokenization](/docs/developer-guides/digital-wallets-and-tokenization.md)
- [Provisioning Digital Wallet Tokens](/docs/developer-guides/provisioning-digital-wallet-tokens.md)
- [Managing the Digital Wallet Token Lifecycle](/docs/developer-guides/managing-the-digital-wallet-token-lifecycle.md)
- [2022 Release Notes](/docs/developer-guides/release-notes-2022.md)