> ## Documentation Index
>
> Fetch the complete documentation index at: [/docs/llms.txt](/content/docs/llms.txt)
>
> Use this file to discover all available pages before exploring further.
[Skip to main content](/content/docs/core-api/digital-wallets-management#content-area/index.html)
The Marqeta platform facilitates the use of digital wallets for storing tokenized cards and making payments.
The API provides endpoints that enable mobile applications to provision tokens into a digital wallet.
It also provides endpoints for retrieving digital wallet tokens and for managing their lifecycle through state transitions.For an overview of digital wallet tokens, see [Digital Wallets and Tokenization](/content/docs/developer-guides/digital-wallets-and-tokenization/index.html).
## [](/content/docs/core-api/digital-wallets-management\#post_digitalwalletprovisionrequests_applepay/index.html) 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 Payment Card Industry (PCI) compliance overhead.
### [](/content/docs/core-api/digital-wallets-management\#_request_body/index.html) 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 |
### [](/content/docs/core-api/digital-wallets-management\#_sample_request_body/index.html) Sample request body
JSON
```
{
"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"
}
```
See all 11 lines
### [](/content/docs/core-api/digital-wallets-management\#_response_body/index.html) 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 |
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body/index.html) Sample response body
JSON
```
{
"created_time": "2026-03-22T21:22:19Z",
"last_modified_time": "2026-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..."
}
```
See all 8 lines
## [](/content/docs/core-api/digital-wallets-management\#post_tokenization_authentication_decision/index.html) 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 Digital Enablement Service (MDES) in real time.
Marqeta then returns the MDES response back to the customer synchronously.
This enables issuers to notify MDES of the cardholder’s authentication outcome following tokenization, ensuring that the token requestor receives timely and accurate decisioning.
### [](/content/docs/core-api/digital-wallets-management\#_request_body_2/index.html) 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 |
### [](/content/docs/core-api/digital-wallets-management\#_response_body_2/index.html) 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 |
## [](/content/docs/core-api/digital-wallets-management\#post_upp_androidpay/index.html) Create a digital wallet token provisioning request for Google Wallet as part of UPP
**Action:**`POST` **Endpoint:**`/digitalwalletprovisionrequests/v2/androidpay`Use this endpoint to retrieve the card data needed to provision a digital wallet token into Google Wallet as part of Unified Push Provisioning (UPP).The returned card data is encrypted using the digital wallet provider’s encryption key, thereby reducing your Payment Card Industry (PCI) compliance overhead.
### [](/content/docs/core-api/digital-wallets-management\#_request_body_3/index.html) 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 |
| server\_session\_id
string
Optional | Unique identifier of the session, used to generate a card object that is the Google Opaque Payment Card (OPC), for adding cards to cardholders’ Google accounts. Must be a UUID in the format which includes 32 hexadecimal digits with 4 hyphens. For example, `123e4567-e89b-12d3-a456-426614174000`. Required only if Google OPC is needed.
**Allowable Values:**
1–50 chars |
| token\_requestor\_id
string
Optional | Identifier of the token requestor. Required when tokenizing a Visa card to a Fitbit device; omitting this field in that scenario will cause the request to fail.
**Allowable Values:**
1–15 chars |
### [](/content/docs/core-api/digital-wallets-management\#_sample_request_body_3/index.html) Sample request body
JSON
```
{
"card_token": "test-card-token",
"device_type": "MOBILE_PHONE",
"wallet_account_id": "google_wallet_user_abc123xyz",
"device_id": "device_987654321",
"provisioning_app_version": "2.1.0",
"token_requestor_id": "40010075001",
"server_session_id": "sdfadfafsfa"
}
```
See all 9 lines
### [](/content/docs/core-api/digital-wallets-management\#_response_body_3/index.html) 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. `CA`, for example.
For the complete list, see [Valid state, provincial, territorial, and federal abbreviations](/content/core-api/kyc-verification#_valid_state_provincial_territorial_and_federal_abbreviations/index.html).
**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 3166 alpha-2 country code](https://www.iso.org/iso-3166-country-codes.html). `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 |
| google\_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:**
Encrypted string |
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_3/index.html) Sample response body
JSON
```
{
"created_time": "2025-11-06T22:43:20Z",
"last_modified_time": "2025-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"
}
},
"google_opaque_payment_card": "my_google_opaque_payment_card_sfawe..."
}
```
See all 23 lines
## [](/content/docs/core-api/digital-wallets-management\#post_digitalwalletprovisionrequests_androidpay/index.html) 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 Payment Card Industry (PCI) compliance overhead.
### [](/content/docs/core-api/digital-wallets-management\#_request_body_4/index.html) Request body
### [](/content/docs/core-api/digital-wallets-management\#_sample_request_body_4/index.html) Sample request body
JSON
```
{
"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"
}
```
See all 7 lines
### [](/content/docs/core-api/digital-wallets-management\#_response_body_4/index.html) Response body
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_4/index.html) Sample response body
JSON
See all 22 lines
## [](/content/docs/core-api/digital-wallets-management\#post_digitalwalletprovisionrequests_samsungpay/index.html) Create digital wallet token provisioning request for Samsung Wallet
**Action:**`POST` **Endpoint:**`/digitalwalletprovisionrequests/samsungpay`
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 Payment Card Industry (PCI) compliance overhead.
### [](/content/docs/core-api/digital-wallets-management\#_request_body_5/index.html) 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 |
### [](/content/docs/core-api/digital-wallets-management\#_response_body_5/index.html) Response body
## [](/content/docs/core-api/digital-wallets-management\#post_digitalwalletprovisionrequests_x_pay/index.html) Create digital wallet token provisioning request for XPay
**Action:**`POST` **Endpoint:**`/digitalwalletprovisionrequests/xpay`
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 Payment Card Industry (PCI) compliance overhead.
### [](/content/docs/core-api/digital-wallets-management\#_request_body_6/index.html) 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 |
### [](/content/docs/core-api/digital-wallets-management\#_response_body_6/index.html) Response body
## [](/content/docs/core-api/digital-wallets-management\#post_digitalwallettokentransitions/index.html) Create digital wallet token transition
**Action:**`POST` **Endpoint:**`/digitalwallettokentransitions`Use this endpoint to transition a digital wallet token from one state to another.
### [](/content/docs/core-api/digital-wallets-management\#_request_body_7/index.html) 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 |
### [](/content/docs/core-api/digital-wallets-management\#_sample_request_body_7/index.html) Sample request body
JSON
```
{
"token": "my_transition_04",
"digital_wallet_token": {
"token": "my_digital_wallet_token_0987"
},
"state": "ACTIVE",
"reason": "Passed additional identity verification",
"reason_code": "18"
}
```
See all 9 lines
### [](/content/docs/core-api/digital-wallets-management\#_response_body_7/index.html) 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 |
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_7/index.html) Sample response body
JSON
```
{
"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": "2026-02-23T18:57:45Z"
}
```
See all 13 lines
### [](/content/docs/core-api/digital-wallets-management\#_error_responses_digitalwallettokentransitions/index.html) Error responses
| HTTP Status | Description |
| --- | --- |
| 400 | Bad request. |
| 409 | Token already associated with a different payload. |
| 422 | Unprocessable entity. Use `error_code` to determine the cause:
\- `422003` — The token network returned an unresolvable error. The token state was **not** changed. Retry later; if the error persists, contact Marqeta support.
\- `422004` — Marqeta detected a state mismatch between Marqeta and the network. The `error_message` field reports both states (for example, `Marqeta state: . TSP state: .`). Reconcile the digital wallet token’s state with the network before retrying. |
#### [](/content/docs/core-api/digital-wallets-management\#_sample_error_response_body_digitalwallettokentransitions/index.html) Sample error response body
JSON
```
{
"error_message": "Unsuccessful response from token services gateway",
"error_code": "422003"
}
```
## [](/content/docs/core-api/digital-wallets-management\#get_digitalwallettokentransitions_token/index.html) 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](/content/docs/core-api/field-filtering/index.html).
### [](/content/docs/core-api/digital-wallets-management\#_url_path_parameters/index.html) URL path parameters
| Fields | Description |
| --- | --- |
| token
string
Required | Unique identifier of the digital wallet token (DWT) transition.
**Allowable Values:**
Existing DWT transition token |
### [](/content/docs/core-api/digital-wallets-management\#_url_query_parameters/index.html) 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 |
### [](/content/docs/core-api/digital-wallets-management\#_response_body_8/index.html) Response body
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_8/index.html) Sample response body
JSON
See all 13 lines
## [](/content/docs/core-api/digital-wallets-management\#get_digitalwallettokentransitions_digitalwallettoken_token/index.html) 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](/content/docs/core-api/field-filtering/index.html), [pagination](/content/docs/core-api/sorting-and-pagination/index.html), and [sorting](/content/docs/core-api/sorting-and-pagination/index.html).
### [](/content/docs/core-api/digital-wallets-management\#_url_path_parameters_2/index.html) URL path parameters
| Fields | Description |
| --- | --- |
| token
string
Required | Unique identifier of the digital wallet token (DWT).
**Allowable Values:**
Existing DWT token |
### [](/content/docs/core-api/digital-wallets-management\#_url_query_parameters_2/index.html) 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:**
`-createdTime` |
### [](/content/docs/core-api/digital-wallets-management\#_response_body_9/index.html) 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\[\]. **created\_timestamp**
string
Conditionally returned | Date and time when the transition was created, in UTC, expressed to the millisecond. Use this field to order transitions that share the same whole-second `created_time`.
Transitions created before this field was introduced might not include a `created_timestamp`. Fall back to `created_time` for those transitions.
**Allowable Values:**
datetime
**Format:**
yyyy-MM-ddThh:mm:ss.SSSZ |
| 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 |
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_9/index.html) Sample response body
JSON
```
{
"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": "2026-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": "2026-02-23T18:44:21Z"\
}\
]
}
```
See all 34 lines
## [](/content/docs/core-api/digital-wallets-management\#get_digitalwallettokens/index.html) List digital wallet tokens
**Action:**`GET` **Endpoint:**`/digitalwallettokens`Use this endpoint to retrieve a list of digital wallet tokens.
### [](/content/docs/core-api/digital-wallets-management\#_url_query_parameters_3/index.html) 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 OR yyyy-MM-dd’T’HH:mm:ssZ |
| end\_date
string
Optional | Expiration date of the digital wallet token.
**Allowable Values:**
Format: yyyy-MM-dd OR yyyy-MM-dd’T’HH:mm:ssZ |
| 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` |
### [](/content/docs/core-api/digital-wallets-management\#_response_body_10/index.html) 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](/content/core-api/digital-wallets-management#post_digitalwallettokentransitions/index.html).
**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
\- **grc** – Greek
\- **ita** – Italian
\- **nld** – Dutch
\- **pol** – Polish
\- **por** – Portuguese
\- **rou** – 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](https://www.iso.org/iso-3166-country-codes.html).
**Allowable Values:**
`ces`, `deu`, `eng`, `fra`, `grc`, `ita`, `nld`, `pol`, `por`, `rou`, `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](/content/developer-guides/managing-the-digital-wallet-token-lifecycle#_transitioning_token_states/index.html).
**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_provisioning_insight_data`, `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\_provisioning\_insight\_data**
string
Conditionally returned | For Mastercard only. Contains the Token Provisioning Insight risk score and reason code for the digital wallet token. Always `null` for other card networks.
**Allowable Values:**
3 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](https://www.iso.org/iso-3166-country-codes.html). |
| 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 |
## [](/content/docs/core-api/digital-wallets-management\#get_digitalwallettokens_token/index.html) Retrieve digital wallet token
**Action:**`GET` **Endpoint:**`/digitalwallettokens/{token}`Use this endpoint to retrieve a specific digital wallet token.
### [](/content/docs/core-api/digital-wallets-management\#_url_path_parameters_3/index.html) URL path parameters
### [](/content/docs/core-api/digital-wallets-management\#_response_body_11/index.html) 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](/content/core-api/digital-wallets-management#post_digitalwallettokentransitions/index.html).
**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
\- **grc** – Greek
\- **ita** – Italian
\- **nld** – Dutch
\- **pol** – Polish
\- **por** – Portuguese
\- **rou** – 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](https://www.iso.org/iso-3166-country-codes.html).
**Allowable Values:**
`ces`, `deu`, `eng`, `fra`, `grc`, `ita`, `nld`, `pol`, `por`, `rou`, `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](/content/developer-guides/managing-the-digital-wallet-token-lifecycle#_transitioning_token_states/index.html).
**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_provisioning_insight_data`, `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\_provisioning\_insight\_data**
string
Conditionally returned | For Mastercard only. Contains the Token Provisioning Insight risk score and reason code for the digital wallet token. Always `null` for other card networks.
**Allowable Values:**
3 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](https://www.iso.org/iso-3166-country-codes.html). |
| 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 |
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_11/index.html) Sample response body
JSON
```
{
"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": "2026-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"
}
}
```
See all 44 lines
## [](/content/docs/core-api/digital-wallets-management\#get_digitalwallettokens_card_cardtoken/index.html) 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](/content/docs/core-api/sorting-and-pagination/index.html).
### [](/content/docs/core-api/digital-wallets-management\#_url_path_parameters_4/index.html) 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 |
### [](/content/docs/core-api/digital-wallets-management\#_url_query_parameters_4/index.html) 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` |
### [](/content/docs/core-api/digital-wallets-management\#_response_body_12/index.html) Response body
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_12/index.html) Sample response body
JSON
```
{
"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": "2026-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"\
}\
}\
]
}
```
See all 52 lines
## [](/content/docs/core-api/digital-wallets-management\#get_digitalwallettokens_token_showtokenpan/index.html) 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}`.
Sending a request to this endpoint requires Payment Card Industry (PCI) Data Security Standard (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 PAN, personal identification number (PIN), and card expiration date.
### [](/content/docs/core-api/digital-wallets-management\#_url_path_parameters_5/index.html) URL path parameters
### [](/content/docs/core-api/digital-wallets-management\#_response_body_13/index.html) Response body
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_13/index.html) Sample response body
JSON
See all 45 lines
## [](/content/docs/core-api/digital-wallets-management\#generate_apple_pay_wppjwt/index.html) 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.
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter/index.html) Header parameter
| 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 |
### [](/content/docs/core-api/digital-wallets-management\#_request_body_8/index.html) 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 |
### [](/content/docs/core-api/digital-wallets-management\#_response_body_14/index.html) 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 |
## [](/content/docs/core-api/digital-wallets-management\#send_opc_data_to_google_pay/index.html) 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.
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_2/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_request_body_9/index.html) 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` |
## [](/content/docs/core-api/digital-wallets-management\#get_opc_data_for_card/index.html) Create a request for Google Wallet web push provisioning (UPP)
**Action:**`POST` **Endpoint:**`/digitalwallets/wpp/v2/googlePayPushProvisioningNotification`Use this endpoint to add a card to Google Wallet via a web application using the Unified Push Provisioning (UPP) flow.
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_3/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_request_body_10/index.html) Request body
| Fields | Description |
| --- | --- |
| card\_setting
integer
Required | Determines if Google Opaque Payment Card (OPC) Object will be returned. Google OPC is used to save funding primary account number (FPAN) to a Google account.
\- **1** \- Return Google OPC in the response.
\- **0** \- Do not return Google OPC in the response.
**Allowable Values:**
`0`, `1` |
| card\_token
string
Required | Unique identifier of the card resource to use for the provisioning request.
**Allowable Values:**
1–36 characters |
| device\_id
string
Optional | Unique identifier of the user’s Android device, as provided by Google Wallet. Required if the value of the `token_setting` field is `1`.
**Allowable Values:**
1–24 characters |
| wallet\_id
string
Optional | Identifier of the device-scoped Google Wallet that will receive the digital wallet token, as provided by Google Wallet. Required if the value of the `token_setting` field is `1`.
**Allowable Values:**
1–50 characters |
| server\_session\_id
string
Optional | Unique identifier of the backend session, as provided by Google Wallet. Required for Google OPC generation.
**Allowable Values:**
1–50 characters |
| token\_setting
integer
Required | Indicates if tokenization will be attempted by card programs
\- **1** \- Tokenization will be attempted.
\- **0** \- Tokenization will not be attempted.
**Allowable Values:**
`0`, `1` |
### [](/content/docs/core-api/digital-wallets-management\#_sample_request_body_10/index.html) Sample request body
JSON
```
{
"card_token": "e9419ecb-f317-4fe7-a6c1-e33989b3576f",
"device_id": "device-hardware-id",
"wallet_id": "google-wallet-id",
"server_session_id": "abc123",
"token_setting": 1,
"card_setting": 1
}
```
See all 8 lines
### [](/content/docs/core-api/digital-wallets-management\#_response_body_15/index.html) Response body
| Fields | Description |
| --- | --- |
| display\_name
string
Conditionally returned | Name of the card as displayed in the digital wallet.
**Allowable Values:**
255 char max |
| last\_digits
string
Conditionally returned | Last four digits of the primary account number of the physical or virtual card.
**Allowable Values:**
4 characters |
| user
object
Conditionally returned | Contains the cardholder’s name and address details returned for the provisioning request.
**Allowable Values:**
`name`, `address_lines`, `locality_name`, `administrative_area_name`, `postal_code_number`, `country_code`, `phone` |
| user. **name**
string
Conditionally returned | Name of the cardholder.
**Allowable Values:**
255 char max |
| user. **address\_lines**
array of strings
Conditionally returned | Street address lines of the cardholder.
**Allowable Values:**
255 char max |
| user. **locality\_name**
string
Conditionally returned | City of the cardholder.
**Allowable Values:**
255 char max |
| user. **administrative\_area\_name**
string
Conditionally returned | State or province of the cardholder.
**Allowable Values:**
255 char max |
| user. **postal\_code\_number**
string
Conditionally returned | Postal code of the cardholder.
**Allowable Values:**
255 char max |
| user. **country\_code**
string
Conditionally returned | Country of the cardholder.
**Allowable Values:**
Valid [ISO 3166-1 alpha-2](https://www.iso.org/iso-3166-country-codes.html) country code, such as `US`, `CA`, or `GB`. |
| user. **phone**
string
Conditionally returned | Phone number of the cardholder.
**Allowable Values:**
255 char max |
| token\_credentials
object
Conditionally returned | Contains the Token Service Provider (TSP) data used to provision the digital wallet token into Google Wallet.
This object is returned if the value of the `token_setting` field in the request is `1`.
**Allowable Values:**
`card_network`, `token_service_provider`, `opaque_payment_card` |
| token\_credentials. **card\_network**
string
Returned | Card network associated with this token.
**Allowable Values:**
`PAYMENT_NETWORK_MASTERCARD`, `PAYMENT_NETWORK_VISA` |
| token\_credentials. **token\_service\_provider**
string
Returned | Specifies the network that provides the digital wallet token service.
**Allowable Values:**
`TOKEN_PROVIDER_VISA`, `TOKEN_PROVIDER_MASTERCARD` |
| token\_credentials. **opaque\_payment\_card**
string
Returned | Encrypted data field created by the issuer and passed to Google Wallet during the push provisioning process.
**Allowable Values:**
Encrypted string |
| card\_credentials
object
Conditionally returned | Contains Google’s Opaque Payment Card (OPC) data, which is used to save the funding primary account number (FPAN) to a Google account.
This object is returned if the value of the `card_setting` field in the request is `1`.
**Allowable Values:**
`google_opaque_payment_card` |
| card\_credentials. **google\_opaque\_payment\_card**
string
Returned | Encrypted data field created by the issuer and passed to Google Wallet during the push provisioning process.
**Allowable Values:**
Encrypted string |
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_15/index.html) Sample response body
JSON
```
{
"display_name": "My Visa Card",
"last_digits": "1234",
"user": {
"name": "Jane Doe",
"address_lines": [\
"123 Main St"\
],
"locality_name": "San Francisco",
"administrative_area_name": "CA",
"postal_code_number": "94105",
"country_code": "US",
"phone": "+14155550100"
},
"token_credentials": {
"card_network": "PAYMENT_NETWORK_VISA",
"token_service_provider": "TOKEN_PROVIDER_VISA",
"opaque_payment_card": "my_opc_base64..."
},
"card_credentials": {
"google_opaque_payment_card": "google_opc_base64..."
}
}
```
See all 23 lines
## [](/content/docs/core-api/digital-wallets-management\#get_clicktopay_mastercard_checkeligibility/index.html) 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](/content/docs/developer-guides/digital-wallets-and-tokenization#_click_to_pay/index.html).
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_4/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_url_query_parameters_5/index.html) 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` |
### [](/content/docs/core-api/digital-wallets-management\#_response_body_16/index.html) 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 |
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_16/index.html) Sample response body
JSON
```
{
"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"\
}\
}\
]
}
```
See all 21 lines
## [](/content/docs/core-api/digital-wallets-management\#post_clicktopay_mastercard_enroll/index.html) 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](/content/docs/developer-guides/digital-wallets-and-tokenization#_click_to_pay/index.html).
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_5/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_request_body_11/index.html) 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](https://www.iso.org/iso-3166-country-codes.html).
**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](https://id.loc.gov/vocabulary/iso639-2.html).
**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](/content/developer-guides/signature-verification/index.html).
**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:
`@``#``$``%``!``^``&``*``(``)`
`\``_``+``~``-``=``[``]``{``}`
`,``;``:``'``"``.``/``<``>``?` |
### [](/content/docs/core-api/digital-wallets-management\#_sample_request_body_11/index.html) Sample request body
JSON
```
{
"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"
}
```
See all 15 lines
### [](/content/docs/core-api/digital-wallets-management\#_response_body_17/index.html) Response body
| Fields | Description |
| --- | --- |
| token
string
Conditionally returned | Unique identifier of the Click to Pay request.
**Allowable Values:**
1–36 chars |
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_17/index.html) Sample response body
JSON
```
{
"token": "my_token_0000"
}
```
See all 3 lines
## [](/content/docs/core-api/digital-wallets-management\#get_clicktopay_mastercard_status_token/index.html) 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](/content/docs/developer-guides/digital-wallets-and-tokenization#_click_to_pay/index.html).
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_6/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_url_path_parameters_6/index.html) URL path parameters
| Fields | Description |
| --- | --- |
| token
string
Required | Unique identifier of the Click to Pay request.
**Allowable Values:**
Existing Click to Pay request token |
### [](/content/docs/core-api/digital-wallets-management\#_response_body_18/index.html) 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 |
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_18/index.html) Sample response body
JSON
```
{
"token": "my_token_0000",
"status": "SUCCESS",
"token_reference_id": "my_token_reference_id_1600"
}
```
See all 5 lines
## [](/content/docs/core-api/digital-wallets-management\#enroll_cardholder/index.html) 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](/content/docs/developer-guides/digital-wallets-and-tokenization#_click_to_pay/index.html).
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_7/index.html) Header parameter
| 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 |
### [](/content/docs/core-api/digital-wallets-management\#_request_body_12/index.html) 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:**
1–64 chars |
| card.billingAddress. **address2**
string
Optional | Optional second line of the billing address.
**Allowable Values:**
1–64 chars |
| card.billingAddress. **city**
string
Optional | City of the billing address.
**Allowable Values:**
1–32 chars |
| card.billingAddress. **state**
string
Optional | State of the billing address.
**Allowable Values:**
1–3 chars |
| 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:**
1–9 chars |
| 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](https://id.loc.gov/vocabulary/iso639-2.html).
**Allowable Values:**
2–5 chars |
| user. **country**
string
Required | ISO 3166-1 alpha-3 country code.
**Allowable Values:**
3 chars |
### [](/content/docs/core-api/digital-wallets-management\#_sample_request_body_12/index.html) Sample request body
JSON
```
{
"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"
}
}
}
```
See all 23 lines
### [](/content/docs/core-api/digital-wallets-management\#_response_body_19/index.html) Response body
| Fields | Description |
| --- | --- |
| requestTraceId
string
Returned | Unique identifier of the Visa Click to Pay request.
**Allowable Values:**
1–36 chars |
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_19/index.html) Sample response body
JSON
```
{
"requestTraceId": "2b6f0cc904d137be2e1730235f5664094b83"
}
```
See all 3 lines
## [](/content/docs/core-api/digital-wallets-management\#enroll_card/index.html) 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](/content/docs/developer-guides/digital-wallets-and-tokenization#_click_to_pay/index.html).
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_8/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_request_body_13/index.html) Request body
### [](/content/docs/core-api/digital-wallets-management\#_sample_request_body_13/index.html) Sample request body
JSON
```
{
"userToken": "1234567890",
"card": {
"cardToken": "2345678901",
"nameOnCard": "John Smith",
"billingAddress": {
"address1": "123 Elm Street",
"address2": "APT 1",
"city": "Oakland",
"state": "CA",
"country": "USA",
"postalCode": "94607"
}
}
}
```
See all 15 lines
### [](/content/docs/core-api/digital-wallets-management\#_response_body_20/index.html) Response body
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_20/index.html) Sample response body
JSON
```
{
"requestTraceId": "2b6f0cc904d137be2e1730235f5664094b83"
}
```
See all 3 lines
## [](/content/docs/core-api/digital-wallets-management\#get_user_data/index.html) 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](/content/docs/developer-guides/digital-wallets-and-tokenization#_click_to_pay/index.html).
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_9/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_url_path_parameters_7/index.html) URL path parameters
| Fields | Description |
| --- | --- |
| user\_token
string
Required | Unique identifier of the cardholder.
**Allowable Values:**
Existing Visa Click To Pay User Token |
### [](/content/docs/core-api/digital-wallets-management\#_response_body_21/index.html) 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\[\].intent. **type**
string
Returned | Type of the operation.
**Allowable Values:**
`PRODUCT_CODE` |
| data\[\].intent. **value**
string
Returned | Value of the operation.
**Allowable Values:**
`CLICK_TO_PAY` |
| 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\[\].consumerInformation. **externalConsumerID**
string
Conditionally returned | Unique identifier of the cardholder.
**Allowable Values:**
`externalConsumerID` |
| data\[\].consumerInformation. **firstName**
string
Conditionally returned | First name of the cardholder.
**Allowable Values:**
`firstName` |
| data\[\].consumerInformation. **middleName**
string
Conditionally returned | Middle name of the cardholder.
**Allowable Values:**
`middleName` |
| data\[\].consumerInformation. **lastName**
string
Conditionally returned | Last name of the cardholder.
**Allowable Values:**
`lastName` |
| data\[\].consumerInformation. **phones**
array of strings
Conditionally returned | Phone numbers of the cardholder.
**Allowable Values:**
Array of valid phone numbers |
| data\[\].consumerInformation. **emails**
array of strings
Conditionally returned | Email addresses of the cardholder.
**Allowable Values:**
Array of valid email addresses |
| data\[\].consumerInformation. **locale**
string
Conditionally returned | Language and country in which the Visa Click to Pay service communicates with the cardholder, in ISO-639-1 format.
**Allowable Values:**
`locale` |
| data\[\].consumerInformation. **countryCode**
string
Conditionally returned | Country code of the cardholder.
**Allowable Values:**
`countryCode` |
| data\[\].consumerInformation. **state**
string
Conditionally returned | State of the cardholder.
**Allowable Values:**
`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` |
| data\[\].paymentInstruments\[\]. **type**
string
Conditionally returned | Type of the payment instrument.
**Allowable Values:**
`CARD` |
| data\[\].paymentInstruments\[\]. **accountNumber**
string
Conditionally returned | Masked account number of the payment instrument.
**Allowable Values:**
16–19 chars |
| data\[\].paymentInstruments\[\]. **nameOnCard**
string
Conditionally returned | Name on the card.
**Allowable Values:**
1–120 chars |
| data\[\].paymentInstruments\[\]. **expirationDate**
string
Conditionally returned | Date of the expiration in the format YYYY-MM.
**Allowable Values:**
7 chars |
| data\[\].paymentInstruments\[\]. **tokenDetails**
object
Conditionally returned | **Allowable Values:**
`tokenReferenceID`, `tokenRequestorID` |
| data\[\].paymentInstruments\[\].tokenDetails. **tokenReferenceID**
string
Returned | Unique reference identifier for the token.
**Allowable Values:**
1–50 chars |
| data\[\].paymentInstruments\[\].tokenDetails. **tokenRequestorID**
string
Returned | Unique token requestor identifier.
**Allowable Values:**
1–11 chars |
| data\[\].paymentInstruments\[\]. **paymentAccountReference**
string
Conditionally returned | Reference of the payment account.
**Allowable Values:**
29–50 chars |
| data\[\].paymentInstruments\[\]. **billingAddress**
object
Conditionally returned | Billing address for Visa Click to Pay.
**Allowable Values:**
`address1`, `city`, `state`, `country`, `postalCode` |
| data\[\].paymentInstruments\[\].billingAddress. **address1**
string
Conditionally returned | First line of the billing address.
**Allowable Values:**
1–64 chars |
| data\[\].paymentInstruments\[\].billingAddress. **address2**
string
Conditionally returned | Optional second line of the billing address.
**Allowable Values:**
1–64 chars |
| data\[\].paymentInstruments\[\].billingAddress. **city**
string
Conditionally returned | City of the billing address.
**Allowable Values:**
1–32 chars |
| data\[\].paymentInstruments\[\].billingAddress. **state**
string
Conditionally returned | State of the billing address.
**Allowable Values:**
1–3 chars |
| data\[\].paymentInstruments\[\].billingAddress. **country**
string
Returned | Country of the billing address.
**Allowable Values:**
3 chars |
| data\[\].paymentInstruments\[\].billingAddress. **postalCode**
string
Conditionally returned | Postal code of the billing address.
**Allowable Values:**
1–9 chars |
| data\[\].paymentInstruments\[\]. **status**
string
Conditionally returned | Status of the payment instrument.
**Allowable Values:**
`ACTIVE`, `INACTIVE`, `SUSPENDED`, `DELETED` |
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_21/index.html) Sample response body
JSON
```
{
"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": "2026-05-05T12:12:12.000Z"\
},\
"lastName": "Miller",\
"firstName": "Alex",\
"middleName": "Robert",\
"countryCode": "USA",\
"externalConsumerID": "63421837-d597-4f0f-89e4-930c1a7b9e85",\
"nationalIdentifiers": [\
{\
"type": "PASSPORT",\
"value": "A123456"\
}\
]\
}\
}\
]
}
```
See all 62 lines
## [](/content/docs/core-api/digital-wallets-management\#update_card_holder_info/index.html) 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](/content/docs/developer-guides/digital-wallets-and-tokenization#_click_to_pay/index.html).
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_10/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_request_body_14/index.html) 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](https://id.loc.gov/vocabulary/iso639-2.html).
**Allowable Values:**
2–5 chars |
| user. **country**
string
Required | ISO 3166-1 alpha-3 country code.
**Allowable Values:**
3 chars |
### [](/content/docs/core-api/digital-wallets-management\#_sample_request_body_14/index.html) Sample request body
JSON
```
{
"user": {
"userToken": "1234567890",
"firstName": "John",
"lastName": "Smith",
"email": "example@email.com",
"phone": "111-111-1111",
"locale": "en_US",
"country": "USA"
}
}
```
See all 11 lines
### [](/content/docs/core-api/digital-wallets-management\#_response_body_22/index.html) Response body
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_22/index.html) Sample response body
JSON
```
{
"requestTraceId": "2b6f0cc904d137be2e1730235f5664094b83"
}
```
See all 3 lines
## [](/content/docs/core-api/digital-wallets-management\#delete_card_holder_info/index.html) 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](/content/docs/developer-guides/digital-wallets-and-tokenization#_click_to_pay/index.html).
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_11/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_request_body_15/index.html) Request body
| Fields | Description |
| --- | --- |
| userToken
string
Required | Unique identifier of the cardholder.
**Allowable Values:**
1–36 chars |
### [](/content/docs/core-api/digital-wallets-management\#_sample_request_body_15/index.html) Sample request body
JSON
```
{
"userToken": "1234567890"
}
```
See all 3 lines
### [](/content/docs/core-api/digital-wallets-management\#_response_body_23/index.html) Response body
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_23/index.html) Sample response body
JSON
```
{
"requestTraceId": "2b6f0cc904d137be2e1730235f5664094b83"
}
```
See all 3 lines
## [](/content/docs/core-api/digital-wallets-management\#update_card_info/index.html) 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](/content/docs/developer-guides/digital-wallets-and-tokenization#_click_to_pay/index.html).
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_12/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_request_body_16/index.html) Request body
### [](/content/docs/core-api/digital-wallets-management\#_sample_request_body_16/index.html) Sample request body
JSON
See all 15 lines
### [](/content/docs/core-api/digital-wallets-management\#_response_body_24/index.html) Response body
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_24/index.html) Sample response body
JSON
```
{
"requestTraceId": "2b6f0cc904d137be2e1730235f5664094b83"
}
```
See all 3 lines
## [](/content/docs/core-api/digital-wallets-management\#delete_card_info/index.html) 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](/content/docs/developer-guides/digital-wallets-and-tokenization#_click_to_pay/index.html).
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_13/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_url_path_parameters_8/index.html) URL path parameters
| Fields | Description |
| --- | --- |
| card\_token
string
Required | Unique identifier of the cardholder.
**Allowable Values:**
1–36 chars |
### [](/content/docs/core-api/digital-wallets-management\#_response_body_25/index.html) Response body
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_25/index.html) Sample response body
JSON
```
{
"requestTraceId": "2b6f0cc904d137be2e1730235f5664094b83"
}
```
See all 3 lines
## [](/content/docs/core-api/digital-wallets-management\#get_status/index.html) 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](/content/docs/developer-guides/digital-wallets-and-tokenization#_click_to_pay/index.html).
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_14/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_url_path_parameters_9/index.html) URL path parameters
| Fields | Description |
| --- | --- |
| requestTraceId
string
Required | Unique identifier of the Visa Click to Pay request.
**Allowable Values:**
1–36 chars |
### [](/content/docs/core-api/digital-wallets-management\#_response_body_26/index.html) 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\[\].intent. **type**
string
Returned | Type of the operation.
**Allowable Values:**
`PRODUCT_CODE` |
| details\[\].intent. **value**
string
Returned | Value of the operation.
**Allowable Values:**
`CLICK_TO_PAY` |
| details\[\]. **errorDetails**
array of objects
Returned | Details of error occurred while executing the operation.
**Allowable Values:**
`field`, `reason`, `message` |
| details\[\].errorDetails\[\]. **field**
string
Returned | Field that caused the error in the operation.
**Allowable Values:**
1–100 chars |
| details\[\].errorDetails\[\]. **reason**
string
Returned | Description of why the error has occurred.
**Allowable Values:**
1–100 chars |
| details\[\].errorDetails\[\]. **message**
string
Returned | Message describing the error.
**Allowable Values:**
1–256 chars |
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_26/index.html) Sample response body
JSON
```
{
"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"
}
}
```
See all 23 lines
## [](/content/docs/core-api/digital-wallets-management\#create_alias/index.html) Create a Visa Alias
**Action:**`POST` **Endpoint:**`/digitalwallets/aliasdirectory/visa/aliases`Use this endpoint to create a Visa Alias.
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_15/index.html) Header parameter
| 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 |
### [](/content/docs/core-api/digital-wallets-management\#_request_body_17/index.html) 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` |
| consent. **presenter**
string
Required | Presenter of the Visa Alias Directory Service (ADS) consent.
**Allowable Values:**
1–120 chars |
| consent. **validFromDateTime**
datetime
Required | 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
Required | Version of the Visa ADS consent.
**Allowable Values:**
1–9 chars |
| consent. **expiryDateTime**
datetime
Optional | 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
Optional | Intermediaries of the Visa ADS consent.
**Allowable Values:**
1–120 chars |
| paymentCredentials
array of objects
Required | 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:**
`cardToken`, `billingAddress`, `nameOnCard`, `cardType`, `issuerName`, `currencyCode`, `preferredFor` |
| paymentCredentials\[\]. **cardToken**
string
Required | Unique identifier of the card token.
**Allowable Values:**
1–36 chars
Existing card token |
| paymentCredentials\[\]. **billingAddress**
object
Required | Billing address for 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](https://www.iso.org/iso-3166-country-codes.html).
**Allowable Values:**
3 chars |
| 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:**
3 chars
Valid three-digit [ISO 4217 currency code](https://www.iso.org/iso-4217-currency-codes.html) (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**
array of objects
Optional | 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.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**
string
Optional | 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
Optional | 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
Optional | 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
Optional | 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
Optional | 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
Optional | 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 |
| identification
object
Optional | Identification of the user associated with the Visa Alias.
**Allowable Values:**
`type`, `value`, `verificationDetails` |
| identification. **type**
string
Required | 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
Required | 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
Optional | 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
Optional | 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
Optional | Authentication method used when the user provided the credentials for verification.
**Allowable Values:**
256 char |
| identification.verificationDetails. **creationDateTime**
datetime
Optional | 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
Optional | Returns `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
Optional | Returns `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` |
### [](/content/docs/core-api/digital-wallets-management\#_sample_request_body_17/index.html) Sample request body
JSON
```
{
"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": "2026-01-01T22:52:46.000Z",
"verifiedEmail": true,
"creationDateTime": "2026-01-01T22:52:46.000Z"
}
}
}
```
See all 61 lines
### [](/content/docs/core-api/digital-wallets-management\#_response_body_27/index.html) 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 |
| paymentCredentials\[\]. **id**
string
Returned | Unique identifier of the additional Visa Alias generated by the Alias Directory.
**Allowable Values:**
36 char max |
| paymentCredentials\[\]. **type**
string
Returned | The type of payment credential
**Allowable Values:**
`CARD`, `BANK` |
| paymentCredentials\[\]. **externalId**
string
Conditionally returned | External ID of the Visa Alias.
**Allowable Values:**
1–100 chars |
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_27/index.html) Sample response body
JSON
```
{
"id": "1f4f5e10-bde6-46a7-b2aa-576550054981",
"externalId": "21267931-7975-4b61-a-8691588sdfsdfa",
"paymentCredentials": [\
{\
"type": "CARD",\
"id": "19e538ea-edfb-4780-915e-2f6e02959e03",\
"externalId": "1111111111111111"\
}\
]
}
```
See all 11 lines
## [](/content/docs/core-api/digital-wallets-management\#get_alias_by_id/index.html) 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.
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_16/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_url_path_parameters_10/index.html) URL path parameters
| Fields | Description |
| --- | --- |
| aliasId
string
Required | Unique identifier of the Visa Alias.
**Allowable Values:**
Existing Visa Alias ID |
### [](/content/docs/core-api/digital-wallets-management\#_response_body_28/index.html) Response body
| Fields | Description |
| --- | --- |
| aliasValue
string
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
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.contactInfo\[\]. **type**
string
Returned | Type of contact information in the Alias Directory Service (ADS) profile.
**Allowable Values:**
`EMAIL`, `PHONE`, `DIRECTORY_ALIASID` |
| profile.contactInfo\[\]. **value**
string
Returned | Contact information value, which is the email address or phone number.
**Allowable Values:**
1–320 chars |
| profile. **dateOfBirth**
string
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` |
| additionalAliases
array of objects
Conditionally returned | Additional aliases associated with the Visa Alias.
**Allowable Values:**
`aliasType`, `aliasValue`, `status` |
| additionalAliases\[\]. **aliasType**
string
Conditionally returned | Type of Visa Alias associated with the cardholder.
**Allowable Values:**
`EMAIL`, `PHONE`, `DIRECTORY_ALIASID`, `PAYNAME` |
| additionalAliases\[\]. **aliasValue**
string
Conditionally returned | Value of the Visa Alias, such as an email address or phone number.
**Allowable Values:**
1–128 chars |
| additionalAliases\[\]. **status**
string
Conditionally returned | Status of the Visa Alias.
**Allowable Values:**
`ACTIVE`, `DISABLED`, `BLOCKED`, `EXPIRED`, `DELETED` |
| 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` |
| 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 | Returns `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 | Returns `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` |
| 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` |
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_28/index.html) Sample response body
JSON
```
{
"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": "2026-01-01T22:52:46Z",
"verifiedEmail": true,
"verifiedPhone": false,
"creationDateTime": "2026-01-01T22:52:46Z",
"authMethodReference": "EXTERNAL, SMS OTP, Email OTP"
}
},
"createdOn": "2026-01-01T22:52:46.000Z",
"lastModifiedOn": "2026-01-01T22:52:46.000Z",
"status": "ACTIVE"
}
```
See all 43 lines
## [](/content/docs/core-api/digital-wallets-management\#update_alias_by_id/index.html) 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.
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_17/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_url_path_parameters_11/index.html) URL path parameters
### [](/content/docs/core-api/digital-wallets-management\#_request_body_18/index.html) Request body
| Fields | Description |
| --- | --- |
| consent
object
Required | Visa Alias Directory Service (ADS) consent information.
**Allowable Values:**
`presenter`, `validFromDateTime`, `version`, `expiryDateTime`, `intermediaries` |
| consent. **presenter**
string
Required | Presenter of the Visa Alias Directory Service (ADS) consent.
**Allowable Values:**
1–120 chars |
| consent. **validFromDateTime**
datetime
Required | 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
Required | Version of the Visa ADS consent.
**Allowable Values:**
1–9 chars |
| consent. **expiryDateTime**
datetime
Optional | 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
Optional | Intermediaries of the Visa ADS consent.
**Allowable Values:**
1–120 chars |
| 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**
array of objects
Optional | 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.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**
string
Optional | 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
Optional | 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
Optional | 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
Optional | 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
Optional | 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
Optional | 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 |
| identification
object
Optional | Identification of the user associated with the Visa Alias.
**Allowable Values:**
`type`, `value`, `verificationDetails` |
| identification. **type**
string
Required | 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
Required | 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
Optional | 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
Optional | 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
Optional | Authentication method used when the user provided the credentials for verification.
**Allowable Values:**
256 char |
| identification.verificationDetails. **creationDateTime**
datetime
Optional | 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
Optional | Returns `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
Optional | Returns `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` |
### [](/content/docs/core-api/digital-wallets-management\#_sample_request_body_18/index.html) Sample request body
JSON
```
{
"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": "2026-01-01T22:52:46Z",
"verifiedEmail": true,
"verifiedPhone": false,
"creationDateTime": "2026-01-01T22:52:46Z",
"authMethodReference": "EXTERNAL, SMS OTP, Email OTP"
}
},
"createdOn": "2026-01-01T22:52:46Z",
"lastModifiedOn": "2026-01-01T22:52:46Z",
"status": "ACTIVE"
}
```
See all 43 lines
## [](/content/docs/core-api/digital-wallets-management\#delete_alias_by_id/index.html) 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.
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_18/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_url_path_parameters_12/index.html) URL path parameters
## [](/content/docs/core-api/digital-wallets-management\#get_alias_id_by_value/index.html) 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.
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_19/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_request_body_19/index.html) 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 |
### [](/content/docs/core-api/digital-wallets-management\#_sample_request_body_19/index.html) Sample request body
JSON
```
{
"aliasValue": "my_alias_value_1234"
}
```
See all 3 lines
### [](/content/docs/core-api/digital-wallets-management\#_response_body_29/index.html) Response body
| Fields | Description |
| --- | --- |
| id
string
Conditionally returned | UUID generated by Alias Directory, which identifies the Visa Alias.
**Allowable Values:**
1–128 chars |
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_29/index.html) Sample response body
JSON
```
{
"id": "my_alias_id_1234"
}
```
See all 3 lines
## [](/content/docs/core-api/digital-wallets-management\#update_alias_status/index.html) Update alias status
**Action:**`PUT` **Endpoint:**`/digitalwallets/aliasdirectory/visa/aliases/{aliasId}/status`Use this endpoint to update the status of a Visa Alias.
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_20/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_url_path_parameters_13/index.html) URL path parameters
### [](/content/docs/core-api/digital-wallets-management\#_request_body_20/index.html) Request body
| Fields | Description |
| --- | --- |
| status
string
Optional | Status of the Visa Alias.
**Allowable Values:**
ACTIVE, DISABLED |
### [](/content/docs/core-api/digital-wallets-management\#_sample_request_body_20/index.html) Sample request body
JSON
```
{
"status": "ACTIVE"
}
```
See all 3 lines
## [](/content/docs/core-api/digital-wallets-management\#create_card_by_alias/index.html) 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.
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_21/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_url_path_parameters_14/index.html) URL path parameters
### [](/content/docs/core-api/digital-wallets-management\#_request_body_21/index.html) 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` |
| 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](https://www.iso.org/iso-3166-country-codes.html).
**Allowable Values:**
3 chars |
| billingAddress. **addressLine1**
string
Optional | Address line 1 of the billing address associated with the payment credential.
**Allowable Values:**
99 char max |
| billingAddress. **addressLine2**
string
Optional | Address line 2 of the billing address associated with the payment credential.
**Allowable Values:**
99 char max |
| billingAddress. **buildingNumber**
string
Optional | Building number of the billing address associated with the payment credential.
**Allowable Values:**
1–60 chars |
| billingAddress. **city**
string
Optional | City of the billing address associated with the payment credential.
**Allowable Values:**
1–35 chars |
| billingAddress. **minorSubdivision**
string
Optional | Minor subdivision of the billing address associated with the payment credential.
**Allowable Values:**
1–50 chars |
| billingAddress. **postalCode**
string
Optional | Postal code of the billing address associated with the payment credential.
**Allowable Values:**
1–16 chars |
| billingAddress. **state**
string
Optional | State of the billing address associated with the payment credential.
**Allowable Values:**
1–16 chars |
| billingAddress. **streetName**
string
Optional | Street name of the billing address associated with the payment credential.
**Allowable Values:**
1–60 chars |
| 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](https://www.iso.org/iso-4217-currency-codes.html) (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` |
### [](/content/docs/core-api/digital-wallets-management\#_sample_request_body_21/index.html) Sample request body
JSON
```
{
"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"\
]
}
```
See all 22 lines
### [](/content/docs/core-api/digital-wallets-management\#_response_body_30/index.html) 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 |
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_30/index.html) Sample response body
JSON
```
{
"id": "a44c9553-e687-4f3c-b7e7-a4245d9f238e",
"type": "CARD",
"externalId": "63421837-d597-4f0f-89e4-930c1a7b9e85"
}
```
See all 5 lines
## [](/content/docs/core-api/digital-wallets-management\#get_cards_by_alias/index.html) 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.
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_22/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_url_path_parameters_15/index.html) URL path parameters
### [](/content/docs/core-api/digital-wallets-management\#_response_body_31/index.html) Response body
| Fields | Description |
| --- | --- |
| accountNumber
string
Returned | Account number of the payment credential.
**Allowable Values:**
12–19 chars |
| billingAddress
object
Returned | Billing address for the payment credential.
**Allowable Values:**
`country`, `addressLine1`, `addressLine2`, `buildingNumber`, `city`, `minorSubdivision`, `postalCode`, `state`, `streetName` |
| 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](https://www.iso.org/iso-3166-country-codes.html).
**Allowable Values:**
3 chars |
| billingAddress. **addressLine1**
string
Conditionally returned | Address line 1 of the billing address associated with the payment credential.
**Allowable Values:**
99 char max |
| billingAddress. **addressLine2**
string
Conditionally returned | Address line 2 of the billing address associated with the payment credential.
**Allowable Values:**
99 char max |
| billingAddress. **buildingNumber**
string
Conditionally returned | Building number of the billing address associated with the payment credential.
**Allowable Values:**
1–60 chars |
| billingAddress. **city**
string
Conditionally returned | City of the billing address associated with the payment credential.
**Allowable Values:**
1–35 chars |
| billingAddress. **minorSubdivision**
string
Conditionally returned | Minor subdivision of the billing address associated with the payment credential.
**Allowable Values:**
1–50 chars |
| billingAddress. **postalCode**
string
Conditionally returned | Postal code of the billing address associated with the payment credential.
**Allowable Values:**
1–16 chars |
| billingAddress. **state**
string
Conditionally returned | State of the billing address associated with the payment credential.
**Allowable Values:**
1–16 chars |
| billingAddress. **streetName**
string
Conditionally returned | Street name of the billing address associated with the payment credential.
**Allowable Values:**
1–60 chars |
| type
string
Returned | Type of payment credential associated with the Visa Alias.
**Allowable Values:**
`CARD` |
| accountNumberType
string
Conditionally returned | Type of account number associated with the payment credential.
**Allowable Values:**
`PAN`, `NIUBIZ`, `TOKEN` |
| cardType
string
Conditionally returned | Type of card associated with the payment credential.
**Allowable Values:**
1–70 chars |
| createdOn
datetime
Conditionally returned | Date and time when the payment credential was created.
**Allowable Values:**
24 chars
Format: YYYY-MM-DDTHH:MM:SS.000Z |
| 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](https://www.iso.org/iso-4217-currency-codes.html) (Alpha-3) |
| expirationDate
string
Conditionally returned | Expiration date of the card.
**Allowable Values:**
7 chars
Format: YYYY-MM |
| externalId
string
Conditionally returned | External ID of the payment credential, which corresponds to Marqeta’s card token.
**Allowable Values:**
1–100 chars |
| id
string
Conditionally returned | Unique identifier of the payment credential generated by Alias Directory.
**Allowable Values:**
1–36 chars |
| issuerName
string
Conditionally returned | Name of the issuer of the payment credential.
**Allowable Values:**
1–150 chars |
| lastFourDigits
string
Conditionally returned | Last four digits of the card number.
**Allowable Values:**
4 chars |
| 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 |
| nameOnCard
string
Conditionally returned | Name on the card associated with the payment credential.
**Allowable Values:**
1–120 chars |
| 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 |
| preferredFor\[\]. **type**
string
Returned | Type of operation associated with the payment credential.
**Allowable Values:**
`RECEIVE`, `SEND`, `PAY` |
| preferredFor\[\]. **date**
string
Conditionally returned | Date of the Receiving, Sending, or Paying operation.
**Allowable Values:**
10 chars
Format: YYYY-MM-DD |
| status
string
Conditionally returned | Status of the payment credential associated with the Visa Alias.
**Allowable Values:**
`ACTIVE`, `BLOCKED`, `DISABLED`, `EXPIRED` |
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_31/index.html) Sample response body
JSON
```
[\
{\
"accountNumber": "4111111145551142",\
"billingAddress": {\
"city": "Oakland",\
"state": "CA",\
"country": "USA",\
"postalCode": "94607",\
"streetName": "12",\
"addressLine1": "1000 Main Street",\
"addressLine2": "Suite 101",\
"buildingNumber": "56",\
"minorSubdivisionCode": "CA"\
},\
"type": "CARD",\
"accountNumberType": "TOKEN",\
"cardType": "Visa Platinum",\
"createdOn": "2026-06-21T13:00:00.000Z",\
"currencyCode": "USD",\
"expirationDate": "2026-01",\
"externalId": "63421837-d597-4f0f-89e4-930c1a7b9e85",\
"id": "a44c9553-e687-4f3c-b7e7-a4245d9f238e",\
"issuerName": "Bank A",\
"lastFourDigits": "1142",\
"lastUpdatedOn": "2026-06-22T15:12:00.000Z",\
"nameOnCard": "John Smith",\
"preferredFor": [\
{\
"date": "2026-01-01",\
"type": "RECEIVE"\
}\
],\
"status": "ACTIVE"\
}\
]
```
See all 35 lines
## [](/content/docs/core-api/digital-wallets-management\#get_payment_credentials_by_alias_id/index.html) Retrieve payment credential
**Action:**`GET` **Endpoint:**`/digitalwallets/aliasdirectory/visa/cards/{paymentCredentialId}`Use this endpoint to retrieve an existing payment credential.
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_23/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_url_path_parameters_16/index.html) URL path parameters
| Fields | Description |
| --- | --- |
| paymentCredentialId
string
Required | Unique identifier of an existing payment credential.
**Allowable Values:**
Existing payment credential ID |
### [](/content/docs/core-api/digital-wallets-management\#_response_body_32/index.html) Response body
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_32/index.html) Sample response body
JSON
```
[\
{\
"accountNumber": "4111111145551142",\
"billingAddress": {\
"city": "Oakland",\
"state": "CA",\
"country": "USA",\
"postalCode": "94607",\
"streetName": "12",\
"addressLine1": "1000 Main Street",\
"addressLine2": "Suite 101",\
"buildingNumber": "56",\
"minorSubdivisionCode": "CA"\
},\
"type": "CARD",\
"accountNumberType": "TOKEN",\
"cardType": "Visa Platinum",\
"createdOn": "2026-06-21T21: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": "2026-06-22T15:12:00.322Z",\
"nameOnCard": "John Smith",\
"preferredFor": [\
{\
"date": "2026-01-01",\
"type": "RECEIVE"\
}\
],\
"status": "ACTIVE"\
}\
]
```
See all 35 lines
## [](/content/docs/core-api/digital-wallets-management\#update_payment_credential/index.html) Update payment credential
**Action:**`PUT` **Endpoint:**`/digitalwallets/aliasdirectory/visa/cards/{paymentCredentialId}`Use this endpoint to update an existing payment credential.
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_24/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_url_path_parameters_17/index.html) URL path parameters
### [](/content/docs/core-api/digital-wallets-management\#_request_body_22/index.html) Request body
### [](/content/docs/core-api/digital-wallets-management\#_sample_request_body_22/index.html) Sample request body
JSON
See all 22 lines
## [](/content/docs/core-api/digital-wallets-management\#delete_payment_credential/index.html) Delete an existing payment credential
**Action:**`DELETE` **Endpoint:**`/digitalwallets/aliasdirectory/visa/cards/{paymentCredentialId}`Use this endpoint to delete an existing payment credential.
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_25/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_url_path_parameters_18/index.html) URL path parameters
## [](/content/docs/core-api/digital-wallets-management\#create_additional_aliases/index.html) 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.
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_26/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_url_path_parameters_19/index.html) URL path parameters
### [](/content/docs/core-api/digital-wallets-management\#_request_body_23/index.html) Request body
| Fields | Description |
| --- | --- |
| type
string
Required | Type of the additional Visa Alias.
**Allowable Values:**
`EMAIL`, `PHONE`, `DIRECTORY_ALIASID`, `PAYNAME` |
| value
string
Required | Unique identifier that represents the customer in the payment ecosystem.
**Allowable Values:**
1–128 chars |
### [](/content/docs/core-api/digital-wallets-management\#_sample_request_body_23/index.html) Sample request body
JSON
```
{
"type": "EMAIL",
"value": "1231231234"
}
```
See all 4 lines
### [](/content/docs/core-api/digital-wallets-management\#_response_body_33/index.html) Response body
| Fields | Description |
| --- | --- |
| id
string
Returned | UUID generated by Alias Directory, which identifies the Visa Alias.
**Allowable Values:**
1–36 chars |
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_33/index.html) Sample response body
JSON
```
{
"id": "my_alias_id_1234"
}
```
See all 3 lines
## [](/content/docs/core-api/digital-wallets-management\#delete_additional_alias_by_id/index.html) 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.
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_27/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_url_path_parameters_20/index.html) URL path parameters
| Fields | Description |
| --- | --- |
| additionalAliasId
string
Required | Unique identifier of the additional Visa Aliases.
**Allowable Values:**
Existing additional Visa Alias ID |
## [](/content/docs/core-api/digital-wallets-management\#get_alias_by_external_id/index.html) 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.
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_28/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_request_body_24/index.html) 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` |
### [](/content/docs/core-api/digital-wallets-management\#_sample_request_body_24/index.html) Sample request body
JSON
```
{
"externalId": "21267931-7975-4b61-be7a-86915883b2b4",
"type": "ALIAS"
}
```
See all 4 lines
### [](/content/docs/core-api/digital-wallets-management\#_response_body_34/index.html) 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 |
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_34/index.html) Sample response body
JSON
```
{
"associatedIds": [\
{\
"id": "a44c9553-e687-4f3c-b7e7-a4245d9f238e",\
"type": "PAYMENT_CREDENTIAL"\
}\
],
"id": "e336c8c8-2945-4be3-af3e-951ec2d01219"
}
```
See all 9 lines
## [](/content/docs/core-api/digital-wallets-management\#create_report/index.html) Create a report request
**Action:**`POST` **Endpoint:**`/digitalwallets/aliasdirectory/visa/reports`Use this endpoint to create a new report request.
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_29/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_request_body_25/index.html) Request body
| Fields | Description |
| --- | --- |
| filters
object
Required | Filters for the report.
**Allowable Values:**
`aliasStatuses`, `aliasType`, `billingEventTypes`, `endDate`, `startDate` |
| filters. **aliasStatuses**
array of strings
Required | Statuses of the Visa Aliases to include in the report.
**Allowable Values:**
`ACTIVE`, `DISABLED`, `BLOCKED`, `EXPIRED`, `DELETED` |
| filters. **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` |
| filters. **billingEventTypes**
array of strings
Optional | Billing event types to include in the report.
**Allowable Values:**
`aliasInquiry`, `createAlias`, `createBatch`, `createPaymentCredential`, `createReport`, `deleteAlias`, `deletePaymentCredential`, `getAlias`, `getAliasId`, `getAliasOnlineReport`, `getBatch`, `getBatchKeys`, `getBatchResult`, `getByExternalId`, `getPaymentCredential`, `getPaymentCredentials`, `getReport`, `getReportFile`, `resolveAlias`, `updateAlias`, `updateAliasStatus`, `updateBankPaymentCredential` |
| filters. **endDate**
string
Required | Date when the report ends in ISO UTC format YYYY-MM-DDThh:mm:ss.000Z
**Allowable Values:**
Format: YYYY-MM-DDThh:mm:ss.000Z |
| filters. **startDate**
string
Required | Date when the report starts in ISO UTC format YYYY-MM-DDThh:mm:ss.000Z
**Allowable Values:**
Format: YYYY-MM-DDThh:mm:ss.000Z |
| 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` |
### [](/content/docs/core-api/digital-wallets-management\#_sample_request_body_25/index.html) Sample request body
JSON
```
{
"format": "JSON",
"filters": {
"endDate": "2026-01-01T22:52:46Z",
"aliasType": "PHONE",
"startDate": "2026-01-01T22:52:46Z",
"aliasStatuses": [\
"ACTIVE"\
],
"billingEventTypes": [\
"createAlias"\
]
},
"reportType": "PLATFORM_REQUESTS"
}
```
See all 15 lines
### [](/content/docs/core-api/digital-wallets-management\#_response_body_35/index.html) Response body
| Fields | Description |
| --- | --- |
| reportId
string
Conditionally returned | Unique identifier of the report.
**Allowable Values:**
36 char max |
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_35/index.html) Sample response body
JSON
```
{
"reportId": "my_report_id_1234"
}
```
See all 3 lines
## [](/content/docs/core-api/digital-wallets-management\#get_report_by_id/index.html) 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.
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_30/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_url_path_parameters_21/index.html) URL path parameters
| Fields | Description |
| --- | --- |
| reportId
string
Required | Unique identifier of the report.
**Allowable Values:**
Existing report ID |
### [](/content/docs/core-api/digital-wallets-management\#_response_body_36/index.html) 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` |
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_36/index.html) Sample response body
JSON
```
{
"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": "2026-01-01T22:52:46Z",
"dataClassification": "VERY_IMPORTANT",
"expirationDateTime": "2025-01-01T22:52:46Z"
}
```
See all 12 lines
## [](/content/docs/core-api/digital-wallets-management\#get_file_by_report_and_file_id/index.html) 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.
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_31/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_url_path_parameters_22/index.html) 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 |
### [](/content/docs/core-api/digital-wallets-management\#_response_body_37/index.html) Response body
| Fields | Description |
| --- | --- |
| operationsCount
integer
Conditionally returned | The number of operations in the report
**Allowable Values:**
Any integer |
| operationType
string
Conditionally returned | The type of the operation |
| originatorActorId
string
Conditionally returned | The Originator Actor Id
**Allowable Values:**
36 char max |
| programId
string
Conditionally returned | The program ID
**Allowable Values:**
36 char max |
| statusCode
integer
Conditionally returned | The status code of the operation |
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_37/index.html) Sample response body
JSON
```
[\
{\
"programId": "baf85624-3cf6-4c52-b91f-b8f3493e7330",\
"statusCode": 200,\
"operationType": "resolveAlias",\
"operationsCount": 18,\
"originatorActorId": "012af73f-44d8-4c9c-bbee-628b07faae1c"\
}\
]
```
See all 9 lines
## [](/content/docs/core-api/digital-wallets-management\#inquire_alias_availability/index.html) 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 might be available.
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_32/index.html) Header parameter
| Fields | Description |
| --- | --- |
| participant-id
string
Required | Visa Business Identifier (BID) that is assigned to the program.
**Allowable Values:**
Existing participant ID |
| 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 |
### [](/content/docs/core-api/digital-wallets-management\#_request_body_26/index.html) 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 |
| filters\[\]. **field**
string
Optional | Fields used to filter the Visa Aliases.
**Allowable Values:**
`DIRECTORY_NAME`, `EXCLUDED_DIRECTORY_NAME`, `ENTITY_ID` |
| filters\[\]. **value**
array of strings
Optional | Values used to filter the Visa Aliases. Visa Alias values are either an email address or phone number.
**Allowable Values:**
1–128 chars |
| transactionDetails
object
Optional | Details of the transaction associated with the Alias.
**Allowable Values:**
`currencyCode` |
| transactionDetails. **currencyCode**
string
Optional | The currency code for the transaction in [ISO 4217 (Alpha-3)](https://www.iso.org/iso-4217-currency-codes.html) format.
**Allowable Values:**
3 chars |
| userDetails
object
Optional | Details of the user requesting the Visa Alias information. The information must not contain personal identifiable information (PII).
**Allowable Values:**
`userName` |
| userDetails. **userName**
string
Optional | Unique identifier of the user.
**Allowable Values:**
1–50 chars |
### [](/content/docs/core-api/digital-wallets-management\#_sample_request_body_26/index.html) Sample request body
JSON
```
{
"aliases": [\
"123456"\
],
"filters": [\
{\
"field": "DIRECTORY_NAME",\
"value": [\
"DIRECTORY_A",\
"DIRECTORY_B",\
"DIRECTORY_C"\
]\
}\
],
"transactionDetails": {
"currencyCode": "USD"
},
"userDetails": {
"userName": "johndoe313"
}
}
```
See all 21 lines
### [](/content/docs/core-api/digital-wallets-management\#_response_body_38/index.html) Response body
| Fields | Description |
| --- | --- |
| summary
object
Returned | Summary of available Visa Aliases.
**Allowable Values:**
`aliasesFound`, `aliasesNotFound`, `aliasesRepeated`, `aliasesTotal` |
| summary. **aliasesFound**
integer
Returned | Number of available Visa Aliases found.
**Allowable Values:**
0–900 |
| summary. **aliasesNotFound**
integer
Returned | Number of Visa Aliases not found.
**Allowable Values:**
0–900 |
| summary. **aliasesRepeated**
integer
Returned | Number of duplicate Visa Aliases.
**Allowable Values:**
0–900 |
| summary. **aliasesTotal**
integer
Returned | Total number of available Visa Aliases.
**Allowable Values:**
0–900 |
| details
array of objects
Conditionally returned | Information associated with available Visa Aliases.
**Allowable Values:**
`aliasType`, `aliasValue`, `directories`, `directoriesNames` |
| details\[\]. **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 details.
This field is returned if it exists in the resource.
**Allowable Values:**
`EMAIL`, `PHONE`, `DIRECTORY_ALIASID`, `PAYNAME` |
| details\[\]. **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 |
| details\[\]. **directories**
array of objects
Conditionally returned | List of directories associated with the Visa Alias.
**Allowable Values:**
`directoryName`, `entities` |
| details\[\].directories\[\]. **directoryName**
string
Conditionally returned | The directory name for the Visa Alias.
**Allowable Values:**
25 char max |
| details\[\].directories\[\]. **entities**
array of objects
Conditionally returned | List of entities associated with the directory.
**Allowable Values:**
`id`, `preferredFor` |
| details\[\].directories\[\].entities\[\]. **id**
string
Conditionally returned | Unique identifier of the entity.
**Allowable Values:**
1–36 chars |
| details\[\].directories\[\].entities\[\]. **preferredFor**
array of objects
Conditionally returned | List of preferred payment methods for the entity.
**Allowable Values:**
`type`, `date` |
| 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**
string
Conditionally returned | Date of the Receiving, Sending, or Paying operation.
**Allowable Values:**
10 chars
Format: YYYY-MM-DD |
| details\[\]. **directoriesNames**
array of strings
Conditionally returned | List of directory names associated with the Visa Alias.
**Allowable Values:**
1–128 chars |
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_38/index.html) Sample response body
JSON
```
[\
{\
"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"\
]\
}\
]\
}\
]
```
See all 42 lines
## [](/content/docs/core-api/digital-wallets-management\#resolve_alias/index.html) Resolve a Visa Alias
**Action:**`POST` **Endpoint:**`/digitalwallets/aliasdirectory/visa/aliases/resolve`Retrieve information about a Visa Alias and all the associated payment credentials.
### [](/content/docs/core-api/digital-wallets-management\#_header_parameter_33/index.html) Header parameter
### [](/content/docs/core-api/digital-wallets-management\#_request_body_27/index.html) 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:**
`field`, `value` |
| filters\[\]. **field**
string
Optional | Fields used to filter the Visa Aliases.
**Allowable Values:**
`DIRECTORY_NAME`, `EXCLUDED_DIRECTORY_NAME`, `ENTITY_ID` |
| filters\[\]. **value**
array of strings
Optional | Values used to filter the Visa Aliases. Visa Alias values are either an email address or phone number.
**Allowable Values:**
1–128 chars |
| transactionDetails
object
Optional | Details of the transaction associated with the Alias.
**Allowable Values:**
`currencyCode` |
| transactionDetails. **currencyCode**
string
Optional | The currency code for the transaction in [ISO 4217 (Alpha-3)](https://www.iso.org/iso-4217-currency-codes.html) format.
**Allowable Values:**
3 chars |
| userDetails
object
Optional | Details of the user requesting the Visa Alias information. The information must not contain personal identifiable information (PII).
**Allowable Values:**
`userName` |
| userDetails. **userName**
string
Optional | Unique identifier of the user.
**Allowable Values:**
1–50 chars |
### [](/content/docs/core-api/digital-wallets-management\#_sample_request_body_27/index.html) Sample request body
JSON
```
{
"aliasType": "PHONE",
"aliasValue": "1231231234",
"transactionDetails": {
"currencyCode": "USD"
},
"filters": [\
{\
"field": "DIRECTORY_NAME",\
"value": [\
"DIRECTORY_A",\
"DIRECTORY_B",\
"DIRECTORY_C"\
]\
}\
],
"userDetails": {
"userName": "username1234"
}
}
```
See all 20 lines
### [](/content/docs/core-api/digital-wallets-management\#_response_body_39/index.html) Response body
| Fields | Description |
| --- | --- |
| profile
object
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.contactInfo\[\]. **type**
string
Returned | Type of contact information in the Alias Directory Service (ADS) profile.
**Allowable Values:**
`EMAIL`, `PHONE`, `DIRECTORY_ALIASID` |
| profile.contactInfo\[\]. **value**
string
Returned | Contact information value, which is the email address or phone number.
**Allowable Values:**
1–320 chars |
| profile. **dateOfBirth**
string
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 |
| directoryName
string
Conditionally returned | The directory name of the Visa Alias.
**Allowable Values:**
1–128 chars |
| 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` |
| 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 | Returns `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 | Returns `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 of objects
Conditionally returned | List of payment credentials associated with the Visa Alias.
**Allowable Values:**
`accountNumber`, `billingAddress`, `type`, `accountNumberType`, `cardType`, `createdOn`, `currencyCode`, `expirationDate`, `externalId`, `id`, `issuerName`, `lastFourDigits`, `lastUpdatedOn`, `nameOnCard`, `preferredFor`, `status` |
| 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](https://www.iso.org/iso-3166-country-codes.html).
**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](https://www.iso.org/iso-4217-currency-codes.html) (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**
string
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` |
### [](/content/docs/core-api/digital-wallets-management\#_sample_response_body_39/index.html) Sample response body
JSON
```
[\
{\
"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": "2026-01-01T22:52:46.000Z",\
"preferredFor": [\
{\
"date": "2026-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": "2026-01-01T22:52:46Z",\
"verifiedEmail": true,\
"verifiedPhone": false,\
"creationDateTime": "2026-01-01T22:52:46Z",\
"authMethodReference": "EXTERNAL, SMS OTP, Email OTP"\
}\
}\
}\
]
```
See all 63 lines
Was this page helpful?
YesNo
Ctrl+I
Assistant
Responses are generated using AI and may contain mistakes.