Digital Wallets Management

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.

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.

Request body

Fields	Description
card_token string Required	Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars
certificates array of strings Required	Base64-encoded leaf and sub-CA certificates provided by Apple. The first element of the array should be the leaf certificate, followed by the sub-CA. Allowable Values: An array of one or more certificates provided by Apple
device_type string Required	Type of device into which the digital wallet token will be provisioned. Allowable Values: `MOBILE_PHONE`, `WATCH`, `TABLET`
nonce string Required	One-time-use nonce provided by Apple for security purposes. Allowable Values: Base64-encoded nonce from Apple
nonce_signature string Required	Apple-provided signature to the nonce. Allowable Values: Base64-encoded nonce signature from Apple
provisioning_app_version string Required	Version of the application making the provisioning request. Used for debugging and fraud prevention. Allowable Values: 1–50 chars

Sample request body

JSON

{
  "card_token": "my_card_token_1234",
  "device_type": "MOBILE_PHONE",
  "provisioning_app_version": "2.13.7",
  "certificates": [
    "my_certificate_ZIzj...",
    "my_certificate_SgMA..."
  ],
  "nonce": "my_nonce_JJCF",
  "nonce_signature": "my_nonce_signature_wbBn"
}

Response body

Fields	Description
activation_data string Returned	Cryptographic one-time passcode conforming to the payment network operator or service provider specifications. Allowable Values: Any value
card_token string Returned	Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars
created_time datetime Returned	Date and time when the digital wallet provisioning request was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
encrypted_pass_data string Returned	Payload encrypted with a shared key derived from the Apple Public Certificates and the generated ephemeral private key. Allowable Values: Any value
ephemeral_public_key string Returned	Ephemeral public key used for the provisioning attempt. Allowable Values: Any value
last_modified_time datetime Returned	Date and time when the digital wallet token provisioning request was last updated, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ

Sample response body

JSON

{
  "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..."
}

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.

Request body

Fields	Description
tokenUniqueReference string Required	Unique identifier of the token allocated to the card. Allowable Values: 1–64 chars
authRequestCorrelationId string Optional	Correlates multiple authentication requests. Allowable Values: 1–64 chars
authenticationMethod string Required	Authentication method used to verify the cardholder. Allowable Values: `Issuer Application`, `Web Portal`
decision string Required	Issuer decision after cardholder authentication. Allowable Values: `SUCCESS`, `FAILED`
commentText string Optional	Optional comment related to the decision. Allowable Values: 500 char max

Response body

Fields	Description
status string Returned	Indicates if the operation was successful. Allowable Values: `SUCCESS`, `FAILED`
message string Returned	Human-readable description of the outcome. Allowable Values: 255 char max

Create 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.

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

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"
}

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. 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. `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

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..."
}

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.

Request body

Fields	Description
card_token string Required	Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars
device_id string Required	Unique identifier of the user’s Google device, as provided by Google during the provisioning process. Allowable Values: 1–24 chars
device_type string Required	Type of device into which the digital wallet token will be provisioned. Allowable Values: `MOBILE_PHONE`, `TABLET`, `WATCH`
provisioning_app_version string Required	Version of the application making the provisioning request. Used for debugging and fraud prevention. Allowable Values: 1–50 chars
wallet_account_id string Required	User’s Google Wallet account ID, as provided by Google during the provisioning process. Allowable Values: 1–50 chars

Sample request body

JSON

{
  "card_token": "my_card_token_0987",
  "device_type": "MOBILE_PHONE",
  "provisioning_app_version": "2.13.3",
  "wallet_account_id": "my_wallet_account_id_sr51",
  "device_id": "my_device_id_r51j"
}

Response body

Fields	Description
card_token string Returned	Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars
created_time datetime Returned	Date and time when the digital wallet provisioning request was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
last_modified_time datetime Returned	Date and time when the digital wallet token provisioning request was last updated, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
push_tokenize_request_data object Returned	Contains details about a card tokenization push request. Allowable Values: `card_type`, `display_name`, `opaque_payment_card`, `last_digits`, `network`, `token_service_provider`
push_tokenize_request_data.display_name string Conditionally returned	Name of the card as displayed in the digital wallet, typically showing the card brand and last four digits of the primary account number (PAN). `Visa 5678`, for example. Allowable Values: Any value
push_tokenize_request_data.opaque_payment_card string Conditionally returned	Encrypted data field created by the issuer and passed to Google Wallet during the push provisioning process. Allowable Values: Any value
push_tokenize_request_data.last_digits string Conditionally returned	Last four digits of the primary account number of the physical or virtual card. Allowable Values: 4 chars
push_tokenize_request_data.network string Conditionally returned	Specifies the card network of the physical or virtual card. Allowable Values: `Visa`, `Mastercard`
push_tokenize_request_data.token_service_provider string Conditionally returned	Specifies the network that provides the digital wallet token service. Allowable Values: `TOKEN_PROVIDER_VISA`, `TOKEN_PROVIDER_MASTERCARD`
push_tokenize_request_data.user_address object Conditionally returned	Specifies the cardholder address. Allowable Values: `name`, `address1`, `address2`, `city`, `state`, `postal_code`, `country`, `phone`
push_tokenize_request_data.user_address.name string Returned	Name of the cardholder. Allowable Values: Any value
push_tokenize_request_data.user_address.address1 string Returned	Street address of the cardholder. Allowable Values: Any value
push_tokenize_request_data.user_address.address2 string Returned	Additional address information for the cardholder, such as a suite or apartment number. `Suite 600`, for example. Allowable Values: Any value
push_tokenize_request_data.user_address.city string Returned	City of the cardholder. Allowable Values: Any value
push_tokenize_request_data.user_address.state string Returned	Two-character state, provincial, or territorial abbreviation. `CA`, for example. For the complete list, see Valid state, provincial, territorial, and federal abbreviations. Allowable Values: Any value
push_tokenize_request_data.user_address.postal_code string Returned	Postal code of the cardholder, such as a United States ZIP code. `94612`, for example. Allowable Values: 255 char max
push_tokenize_request_data.user_address.country string Returned	Two-character ISO 3166 alpha-2 country code. `US`, for example. Allowable Values: 255 char max
push_tokenize_request_data.user_address.phone string Returned	Telephone number of the cardholder. Allowable Values: 255 char max

Sample response body

JSON

{
  "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"
    }
  }
}

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.

Request body

Fields	Description
card_token string Required	Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars
device_id string Required	User’s Samsung device unique identifier, as provided by Samsung during the provisioning process. Allowable Values: 1–24 chars
device_type string Required	Type of device into which the digital wallet token will be provisioned. Allowable Values: `MOBILE_PHONE`, `TABLET`, `WATCH`
provisioning_app_version string Required	Version of the application making the provisioning request. Used for debugging and fraud prevention. Allowable Values: 1–50 chars
wallet_user_id string Required	User’s Samsung Wallet account ID, as provided by Samsung during the provisioning process. Allowable Values: 1–50 chars

Response body

Fields	Description
card_token string Returned	Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars
created_time datetime Returned	Date and time when the digital wallet provisioning request was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
last_modified_time datetime Returned	Date and time when the digital wallet token provisioning request was last updated, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
push_tokenize_request_data object Conditionally returned	Contains details about a card tokenization push request. Allowable Values: `card_type`, `display_name`, `extra_provision_payload`, `last_digits`, `network`, `token_service_provider`
push_tokenize_request_data.card_type string Conditionally returned	Specifies the type of card. Allowable Values: `PAYMENT`, `DEBIT`, `CREDIT`, `LOYALTY`, `GIFT`
push_tokenize_request_data.display_name string Conditionally returned	Name of the card as displayed in the digital wallet, typically showing the card brand and last four digits of the primary account number (PAN). `Visa 5678`, for example. Allowable Values: Any value
push_tokenize_request_data.extra_provision_payload string Conditionally returned	Encrypted card or cardholder details. Allowable Values: Any value
push_tokenize_request_data.last_digits string Conditionally returned	Last four digits of the primary account number of the physical or virtual card. Allowable Values: 4 chars
push_tokenize_request_data.network string Conditionally returned	Specifies the card network of the physical or virtual card. Allowable Values: `Visa`, `Mastercard`
push_tokenize_request_data.token_service_provider string Conditionally returned	Specifies the network that provides the digital wallet token service, as determined by the Samsung Wallet library. Allowable Values: `VI`, `MC`

Create digital wallet token provisioning request for XPay

Action: POST Endpoint: /digitalwalletprovisionrequests/xpay

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.

Request body

Fields	Description
card_token string Required	Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars
device_id string Required	Unique identifier of the user’s XPay device, as provided by XPay during the provisioning process. Allowable Values: 1–24 chars
device_type string Required	Type of device into which the digital wallet token will be provisioned. Allowable Values: `MOBILE_PHONE`, `TABLET`, `WATCH`
provisioning_app_version string Required	Version of the application making the provisioning request. Used for debugging and fraud prevention. Allowable Values: 1–50 chars
token_requestor_id string Required	Unique numerical identifier of the digital wallet token requestor within the card network. These ID numbers map to `token_requestor_name` field values as follows: Mastercard - 50110030273 – `APPLE_PAY` - 50120834693 – `ANDROID_PAY` - 50139059239 – `SAMSUNG_PAY` Visa - 40010030273 – `APPLE_PAY` - 40010075001 – `ANDROID_PAY` - 40010043095 – `SAMSUNG_PAY` - 40010075196 – `MICROSOFT_PAY` - 40010075338 – `VISA_CHECKOUT` - 40010075449 – `FACEBOOK` - 40010075839 – `NETFLIX` - 40010077056 – `FITBIT_PAY` - 40010069887 – `GARMIN_PAY` Allowable Values: 11 char max Example Values: - Mastercard – 50110030273, 50120834693, 50139059239 - Visa – 40010030273, 40010075001, 40010075338, 40010075449, 40010075839, 40010043095
wallet_account_id string Required	User’s XPay account identifier, as provided by XPay during the provisioning process. Allowable Values: 1–50 chars

Response body

Fields	Description
card_token string Returned	Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars
created_time datetime Returned	Date and time when the digital wallet provisioning request was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
last_modified_time datetime Returned	Date and time when the digital wallet token provisioning request was last updated, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
push_tokenize_request_data object Conditionally returned	Contains details about a card tokenization push request. Allowable Values: `card_type`, `display_name`, `extra_provision_payload`, `last_digits`, `network`, `token_service_provider`
push_tokenize_request_data.card_type string Conditionally returned	Specifies the type of card. Allowable Values: `PAYMENT`, `DEBIT`, `CREDIT`, `LOYALTY`, `GIFT`
push_tokenize_request_data.display_name string Conditionally returned	Name of the card as displayed in the digital wallet, typically showing the card brand and last four digits of the primary account number (PAN). `Visa 5678`, for example. Allowable Values: Any value
push_tokenize_request_data.extra_provision_payload string Conditionally returned	Encrypted card or cardholder details. Allowable Values: Any value
push_tokenize_request_data.last_digits string Conditionally returned	Last four digits of the primary account number of the physical or virtual card. Allowable Values: 4 chars
push_tokenize_request_data.network string Conditionally returned	Specifies the card network of the physical or virtual card. Allowable Values: `Visa`, `Mastercard`
push_tokenize_request_data.token_service_provider string Conditionally returned	Specifies the network that provides the digital wallet token service. Allowable Values: `TOKEN_PROVIDER_VISA`, `TOKEN_PROVIDER_MASTERCARD`

Create digital wallet token transition

Action: POST Endpoint: /digitalwallettokentransitions Use this endpoint to transition a digital wallet token from one state to another.

Request body

Fields	Description
channel string Optional	Mechanism by which the transition was initiated. Allowable Values: `TOKEN_SERVICE_PROVIDER`, `TOKEN_SERVICE_PROVIDER_API`, `DIGITAL_WALLET`, `API`, `IVR`, `FRAUD`, `ADMIN`, `SYSTEM`
digital_wallet_token object Required	Contains identifiers of the digital wallet token resource and the card resource. Allowable Values: Unique identifiers of the digital wallet token resource and the card resource
digital_wallet_token.token string Required	Unique identifier of the digital wallet token resource. Allowable Values: 1–36 chars
digital_wallet_token.card_token string Optional	Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars
reason string Optional	The reason for the transition. Allowable Values: 255 char max
reason_code string Optional	Standard code describing the reason for the transition. NOTE: This field is required if your program uses v2 of the `user_card_state_version`, which is a program-specific configuration value that is managed by Marqeta and cannot be accessed via the API. To learn more about the `user_card_state_version` program configuration, contact your Marqeta representative. - 00: Object activated for the first time - 01: Requested by you - 02: Inactivity over time - 03: This address cannot accept mail or the addressee is unknown - 04: Negative account balance - 05: Account under review - 06: Suspicious activity was identified - 07: Activity outside the program parameters was identified - 08: Confirmed fraud was identified - 09: Matched with an Office of Foreign Assets Control list - 10: Card was reported lost - 11: Card information was cloned - 12: Account or card information was compromised - 13: Temporary status change while on hold/leave - 14: Initiated by Marqeta - 15: Initiated by issuer - 16: Card expired - 17: Failed KYC - 18: Changed to `ACTIVE` because information was properly validated - 19: Changed to `ACTIVE` because account activity was properly validated - 20: Change occurred prior to the normalization of reason codes - 21: Initiated by a third party, often a digital wallet provider - 22: PIN retry limit reached - 23: Card was reported stolen - 24: Address issue - 25: Name issue - 26: SSN issue - 27: DOB issue - 28: Email issue - 29: Phone issue - 30: Account/fulfillment mismatch - 31: Other reason - 32: Unblock request - 86: Notification of death Allowable Values: `00`, `01`, `02`, `03`, `04`, `05`, `06`, `07`, `08`, `09`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, `18`, `19`, `20`, `21`, `22`, `23`, `24`, `25`, `26`, `27`, `28`, `29`, `30`, `31`, `32`, `86`
state string Required	Specifies the state to which the digital wallet token will transition. The original state is `REQUESTED`. You cannot modify the state if its current value is either `REQUEST_DECLINED` or `TERMINATED`. Allowable Values: `ACTIVE`, `SUSPENDED`, `TERMINATED`
token string Optional	The unique identifier of the digital wallet token transition (not the identifier of the digital wallet token itself). If you do not include a value for the `token` field, the system will generate one automatically. This value is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated. Allowable Values: 1–36 chars
token_reference_id string Optional	The unique identifier of the digital wallet token within the card network. The `token_reference_id` is unique at the card network level. Allowable Values: 255 char max

Sample request body

JSON

{
  "token": "my_transition_04",
  "digital_wallet_token": {
    "token": "my_digital_wallet_token_0987"
  },
  "state": "ACTIVE",
  "reason": "Passed additional identity verification",
  "reason_code": "18"
}

Response body

Fields	Description
card_swap object Conditionally returned	Contains identifiers for swapping digital wallet tokens between cards. Allowable Values: `new_card_token`, `previous_card_token`
card_swap.new_card_token string Returned	Unique identifier of the new card resource to which the digital wallet tokens are assigned. Allowable Values: 1–36 chars
card_swap.previous_card_token string Returned	Unique identifier of the existing card resource that has digital wallet tokens assigned to it. Allowable Values: 1–36 chars
channel string Returned	Mechanism by which the transition was initiated. Allowable Values: `TOKEN_SERVICE_PROVIDER`, `DIGITAL_WALLET`, `API`, `IVR`, `FRAUD`, `ADMIN`, `SYSTEM`, `TOKEN_SERVICE_PROVIDER_API`
created_time datetime Conditionally returned	Date and time when the transition was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
digital_wallet_token object Returned	Contains identifiers of the digital wallet token resource and the card resource. Allowable Values: Unique identifiers of the digital wallet token resource and the card resource
digital_wallet_token.token string Returned	Unique identifier of the digital wallet token resource. Allowable Values: 1–36 chars
digital_wallet_token.card_token string Conditionally returned	Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars
fulfillment_status string Returned	Provisioning status of the digital wallet token. Allowable Values: `DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN`, `REJECTED`, `PROVISIONED`
reason string Conditionally returned	Reason for the transition. Allowable Values: 255 char max
reason_code string Conditionally returned	Standard code describing the reason for the transition: - 00: Object activated for the first time - 01: Requested by you - 02: Inactivity over time - 03: This address cannot accept mail or the addressee is unknown - 04: Negative account balance - 05: Account under review - 06: Suspicious activity was identified - 07: Activity outside the program parameters was identified - 08: Confirmed fraud was identified - 09: Matched with an Office of Foreign Assets Control list - 10: Card was reported lost - 11: Card information was cloned - 12: Account or card information was compromised - 13: Temporary status change while on hold/leave - 14: Initiated by Marqeta - 15: Initiated by issuer - 16: Card expired - 17: Failed KYC - 18: Changed to `ACTIVE` because information was properly validated - 19: Changed to `ACTIVE` because account activity was properly validated - 20: Change occurred prior to the normalization of reason codes - 21: Initiated by a third party, often a digital wallet provider - 22: PIN retry limit reached - 23: Card was reported stolen - 24: Address issue - 25: Name issue - 26: SSN issue - 27: DOB issue - 28: Email issue - 29: Phone issue - 30: Account/fulfillment mismatch - 31: Other reason - 32: Unblock request - 86: Notification of death Allowable Values: `00`, `01`, `02`, `03`, `04`, `05`, `06`, `07`, `08`, `09`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, `18`, `19`, `20`, `21`, `22`, `23`, `24`, `25`, `26`, `27`, `28`, `29`, `30`, `31`, `32`, `86`
state string Returned	Specifies the state to which the digital wallet token is transitioning. Allowable Values: `REQUESTED`, `REQUEST_DECLINED`, `ACTIVE`, `SUSPENDED`, `TERMINATED`
token string Returned	Unique identifier of the digital wallet token transition, and not the identifier of the digital wallet token itself. Allowable Values: 1–36 chars
type string Returned	Type of digital wallet token transition. `state.activated`, for example. Allowable Values: 36 char max

Sample response body

JSON

{
  "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"
}

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: <marqeta_state>. TSP state: <tsp_state>.`). Reconcile the digital wallet token’s state with the network before retrying.

Sample error response body

JSON

{
  "error_message": "Unsuccessful response from token services gateway",
  "error_code": "422003"
}

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.

URL path parameters

Fields	Description
token string Required	Unique identifier of the digital wallet token (DWT) transition. Allowable Values: Existing DWT transition token

URL query parameters

Fields	Description
fields string Optional	Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields. Allowable Values: Comma-delimited list of fields, or blank

Response body

Fields	Description
card_swap object Conditionally returned	Contains identifiers for swapping digital wallet tokens between cards. Allowable Values: `new_card_token`, `previous_card_token`
card_swap.new_card_token string Returned	Unique identifier of the new card resource to which the digital wallet tokens are assigned. Allowable Values: 1–36 chars
card_swap.previous_card_token string Returned	Unique identifier of the existing card resource that has digital wallet tokens assigned to it. Allowable Values: 1–36 chars
channel string Returned	Mechanism by which the transition was initiated. Allowable Values: `TOKEN_SERVICE_PROVIDER`, `DIGITAL_WALLET`, `API`, `IVR`, `FRAUD`, `ADMIN`, `SYSTEM`, `TOKEN_SERVICE_PROVIDER_API`
created_time datetime Conditionally returned	Date and time when the transition was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
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
digital_wallet_token object Returned	Contains identifiers of the digital wallet token resource and the card resource. Allowable Values: Unique identifiers of the digital wallet token resource and the card resource
digital_wallet_token.token string Returned	Unique identifier of the digital wallet token resource. Allowable Values: 1–36 chars
digital_wallet_token.card_token string Conditionally returned	Unique identifier of the card resource to use for the provisioning request. Allowable Values: 1–36 chars
fulfillment_status string Returned	Provisioning status of the digital wallet token. Allowable Values: `DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN`, `REJECTED`, `PROVISIONED`
reason string Conditionally returned	Reason for the transition. Allowable Values: 255 char max
reason_code string Conditionally returned	Standard code describing the reason for the transition: - 00: Object activated for the first time - 01: Requested by you - 02: Inactivity over time - 03: This address cannot accept mail or the addressee is unknown - 04: Negative account balance - 05: Account under review - 06: Suspicious activity was identified - 07: Activity outside the program parameters was identified - 08: Confirmed fraud was identified - 09: Matched with an Office of Foreign Assets Control list - 10: Card was reported lost - 11: Card information was cloned - 12: Account or card information was compromised - 13: Temporary status change while on hold/leave - 14: Initiated by Marqeta - 15: Initiated by issuer - 16: Card expired - 17: Failed KYC - 18: Changed to `ACTIVE` because information was properly validated - 19: Changed to `ACTIVE` because account activity was properly validated - 20: Change occurred prior to the normalization of reason codes - 21: Initiated by a third party, often a digital wallet provider - 22: PIN retry limit reached - 23: Card was reported stolen - 24: Address issue - 25: Name issue - 26: SSN issue - 27: DOB issue - 28: Email issue - 29: Phone issue - 30: Account/fulfillment mismatch - 31: Other reason - 32: Unblock request - 86: Notification of death Allowable Values: `00`, `01`, `02`, `03`, `04`, `05`, `06`, `07`, `08`, `09`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, `18`, `19`, `20`, `21`, `22`, `23`, `24`, `25`, `26`, `27`, `28`, `29`, `30`, `31`, `32`, `86`
state string Returned	Specifies the state to which the digital wallet token is transitioning. Allowable Values: `REQUESTED`, `REQUEST_DECLINED`, `ACTIVE`, `SUSPENDED`, `TERMINATED`
token string Returned	Unique identifier of the digital wallet token transition, and not the identifier of the digital wallet token itself. Allowable Values: 1–36 chars
type string Returned	Type of digital wallet token transition. `state.activated`, for example. Allowable Values: 36 char max

Sample response body

JSON

{
  "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"
}

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, pagination, and sorting.

URL path parameters

Fields	Description
token string Required	Unique identifier of the digital wallet token (DWT). Allowable Values: Existing DWT token

URL query parameters

Fields	Description
count integer Optional	Number of digital wallet transitions to retrieve. Allowable Values: Any integer Default value: 5
start_index integer Optional	The sort order index of the first digital wallet token in the returned array. Allowable Values: Any integer Default value: 0
fields string Optional	Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields. Allowable Values: Comma-delimited list of fields, or blank
sort_by string Optional	Field on which to sort. Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`. Prefix the field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order. Allowable Values: `createdTime`, `lastModifiedTime`, or any field in the resource model Default value: `-createdTime`

Response body

Fields	Description
count integer Conditionally returned	Number of resources returned. This field is returned if there are resources in your returned array. Allowable Values: Any integer
data array of objects Conditionally returned	Array of digital wallet token 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

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"
    }
  ]
}

List digital wallet tokens

Action: GET Endpoint: /digitalwallettokens Use this endpoint to retrieve a list of digital wallet tokens.

URL query parameters

Fields	Description
count integer Optional	Number of digital wallet token resources to retrieve. Allowable Values: 1–100 Default value: 10
start_index integer Optional	Sort order index of the first digital wallet token resource in the returned array. Allowable Values: Any integer Default value: 0
fields string Optional	Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields. Allowable Values: Comma-delimited list of fields, or blank
sort_by string Optional	Field on which to sort. Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`. Prefix the field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order. Allowable Values: `createdTime`, `lastModifiedTime`, or any field in the resource model Default value: `-createdTime`
start_date string Optional	Date when the digital wallet token becomes active. Allowable Values: Format: yyyy-MM-dd 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`

Response body

Fields	Description
count integer Conditionally returned	Number of resources returned. This field is returned if there are resources in your returned array. Allowable Values: Any integer
data array of objects Conditionally returned	Array of digital wallet token resources. Resources are returned as appropriate to your query. Allowable Values: Valid array of one or more digital wallet token resources
data[].address_verification object Conditionally returned	Contains address verification information. Allowable Values: `name`, `postal_code`, `street_address`, `zip`
data[].address_verification.name string Conditionally returned	Name of the cardholder. Allowable Values: 40 char max
data[].address_verification.postal_code string Conditionally returned	Postal code. Allowable Values: 10 char max
data[].address_verification.street_address string Conditionally returned	Street address provided by the cardholder. Allowable Values: 40 char max
data[].address_verification.zip string Conditionally returned	United States ZIP code. Allowable Values: 10 char max
data[].card_token string Conditionally returned	Unique identifier of the card. Allowable Values: Existing card token
data[].created_time datetime Conditionally returned	Date and time when the digital wallet token object was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
data[].device object Conditionally returned	Contains information related to the device being provisioned. Allowable Values: `device_id`, `ip_address`, `language_code`, `location`, `name`, `phone_number`, `token`, `type`
data[].device.device_id string Conditionally returned	Identity number of the device. Allowable Values: 24 char max
data[].device.ip_address string Conditionally returned	Device’s IP address. Allowable Values: IP address format, 50 char max
data[].device.language_code string Conditionally returned	Language the device is configured to use. Allowable Values: 50 char max
data[].device.location string Conditionally returned	Geographic coordinates of the device. Allowable Values: Latitude and longitude in `DDD.DD/DDD.DD` format. NOTE: Both the longitude and latitude are prefixed with either a `+` or `-` symbol, for example: `+42.29/-71.07`.
data[].device.name string Conditionally returned	Name of the device. Allowable Values: 50 char max
data[].device.phone_number string Conditionally returned	Device’s telephone number. Allowable Values: 50 char max
data[].device.token string Conditionally returned	Unique identifier of the device object. Allowable Values: 36 char max
data[].device.type string Conditionally returned	Type of device being provisioned. Allowable Values: `MOBILE_PHONE`, `WATCH`, `TABLET`, `MOBILE_PHONE_OR_TABLET`, `VEHICLE`, `APPLIANCE`, `LAPTOP`, `GAMING_DEVICE`, `WEARABLE_DEVICE`, `UNKNOWN`
data[].fulfillment_status string Conditionally returned	Digital wallet token’s provisioning status. For fulfillment status descriptions, see Create digital wallet token transition. Allowable Values: `DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN`, `REJECTED`, `PROVISIONED`
data[].issuer_eligibility_decision string Conditionally returned	The Marqeta platform’s decision as to whether the digital wallet token should be provisioned. - 0000: The token should be provisioned. - token.activation.verification.required: Provisioning is pending; further action is required for completion. For all other values, check the value of the `fulfillment_status` field to definitively ascertain the provisioning outcome. NOTE: The value `invalid.cid` indicates an invalid CVV2 number. Allowable Values: 0000, `cardaccount.verified`, `card.suspicious`, `token.activation.verification.required`, `token.activation-request.decline`, `card.not.active`, `invalid.cid`, `card.expired`, `card.suspended`, `cardholder.not.active`
data[].last_modified_time datetime Conditionally returned	Date and time when the digital wallet token object was last modified, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
data[].metadata object Conditionally returned	Contains additional information about the digital wallet token. Allowable Values: `cardproduct_preferred_notification_language`, `issuer_product_config_id`
data[].metadata.cardproduct_preferred_notification_language string Conditionally returned	Language specified in the `config.transaction_controls.notification_language` field of the card product: - ces – Czech - deu – German - eng – English - fra – French - 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. 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. Allowable Values: `REQUESTED`, `REQUEST_DECLINED`, `ACTIVE`, `SUSPENDED`, `TERMINATED`
data[].state_reason string Conditionally returned	Reason why the digital wallet token transitioned to its current state. Allowable Values: 255 char max
data[].token string Conditionally returned	Unique identifier of the digital wallet token. Allowable Values: Existing digital wallet token.
data[].token_service_provider object Conditionally returned	Contains information held and provided by the token service provider (card network). Allowable Values: `correlation_id`, `pan_reference_id`, `token_assurance_level`, `token_eligibility_decision`, `token_expiration`, `token_pan`, `token_reference_id`, `token_requestor_id`, `token_requestor_name`, `token_score`, `token_type`
data[].token_service_provider.correlation_id string Conditionally returned	For Mastercard only. Unique value representing a tokenization request. Allowable Values: Existing correlation identifier
data[].token_service_provider.pan_reference_id string Conditionally returned	Unique identifier of the digital wallet token primary account number (PAN) within the card network. Allowable Values: Existing PAN Reference ID
data[].token_service_provider.token_assurance_level string Conditionally returned	For Mastercard only. Represents the confidence level in the digital wallet token. Allowable Values: 0-99
data[].token_service_provider.token_eligibility_decision string Conditionally returned	Digital wallet’s decision as to whether the digital wallet token should be provisioned. Allowable Values: `DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN`
data[].token_service_provider.token_expiration string Conditionally returned	Expiration date of the digital wallet token. Allowable Values: Format: MMyy
data[].token_service_provider.token_pan string Conditionally returned	Primary account number (PAN) of the digital wallet token. Allowable Values: 16 char max
data[].token_service_provider.token_reference_id string Conditionally returned	Unique identifier of the digital wallet token within the card network. Allowable Values: Existing Token Reference ID
data[].token_service_provider.token_requestor_id string Conditionally returned	Unique numerical identifier of the token requestor within the card network. These ID numbers map to `token_requestor_name` field values as follows: Mastercard - 50110030273 – `APPLE_PAY` - 50120834693 – `ANDROID_PAY` - 50139059239 – `SAMSUNG_PAY` Visa - 40010030273 – `APPLE_PAY` - 40010075001 – `ANDROID_PAY` - 40010043095 – `SAMSUNG_PAY` - 40010075196 – `MICROSOFT_PAY` - 40010075338 – `VISA_CHECKOUT` - 40010075449 – `FACEBOOK` - 40010075839 – `NETFLIX` - 40010077056 – `FITBIT_PAY` - 40010069887 – `GARMIN_PAY` Allowable Values: 11 char max Example Values: - Mastercard – 50110030273, 50120834693, 50139059239 - Visa – 40010030273, 40010075001, 40010075338, 40010075449, 40010075839, 40010043095
data[].token_service_provider.token_requestor_name string Conditionally returned	Name of the token requestor within the card network. NOTE: The list of example values for this field is maintained by the card networks and is subject to change. Allowable Values: 255 char max Example Values: - Mastercard – `APPLE_PAY`, `ANDROID_PAY`, `SAMSUNG_PAY` - Visa – `APPLE_PAY`, `ANDROID_PAY`, `SAMSUNG_PAY`, `MICROSOFT_PAY`, `VISA_CHECKOUT`, `FACEBOOK`, `NETFLIX`, `FITBIT_PAY`, `GARMIN_PAY`
data[].token_service_provider.token_score string Conditionally returned	Token score assigned by the digital wallet. Allowable Values: 25 char max
data[].token_service_provider.token_type string Conditionally returned	Type of the digital wallet token. Allowable Values: `MERCHANT_CARD_ON_FILE`, `DEVICE_SECURE_ELEMENT`, `DEVICE_CLOUD_BASED`, `ECOMMERCE_DIGITAL_WALLET`
data[].transaction_device object Conditionally returned	Contains information about the device used in the transaction to enhance the risk decisioning process. Use this data to improve fraud prevention and dispute resolution. Allowable Values: `binding_id`, `ip_address`, `location`, `phone_number`
data[].transaction_device.binding_id string Conditionally returned	Unique identifier of the data component bound to the credential. Allowable Values: 48 char max
data[].transaction_device.ip_address string Conditionally returned	IP address of the device. The presence of the IP address helps determine if the transaction was initiated from an unusual network, helping establish a pattern of safe device usage that further confirms the authenticity of the consumer who initiated the transaction. Allowable Values: IP address format, 39 char max
data[].transaction_device.location string Conditionally returned	Geographic coordinates of the device. Contains the latitude and longitude of the device used when the cardholder was authenticated during checkout. This field helps to determine if the transaction was initiated from an unexpected location. Allowable Values: Latitude and longitude in `DDD.DD/DDD.DD` format.
data[].transaction_device.phone_number string Conditionally returned	Telephone number of the device. Contains the phone number that was used to authenticate the consumer during checkout, or the consumer’s preferred phone number. The presence of the phone number helps establish the consumer’s authenticity when matching the phone number provided during checkout to a list of known phone numbers for the consumer. Allowable Values: 15 char max
data[].user object Conditionally returned	Contains information about a cardholder. Allowable Values: `account_holder_group_token`, `active`, `address1`, `address2`, `authentication`, `birth_date`, `birth_place`, `business_token`, `city`, `company`, `corporate_card_holder`, `country`, `created_time`, `email`, `first_name`, `gender`, `honorific`, `id_card_expiration_date`, `id_card_number`, `identifications`, `ip_address`, `last_modified_time`, `last_name`, `metadata`, `middle_name`, `nationality`, `notes`, `parent_token`, `passport_expiration_date`, `passport_number`, `password`, `phone`, `postal_code`, `ssn`, `state`, `status`, `title`, `token`, `uses_parent_account`, `zip`
data[].user.account_holder_group_token string Conditionally returned	Associates the specified account holder group with the cardholder. Allowable Values: 36 char max
data[].user.active boolean Conditionally returned	Specifies if the cardholder is in the `ACTIVE` state on the Marqeta platform. Allowable Values: `true`, `false`
data[].user.address1 string Conditionally returned	Cardholder’s address. Allowable Values: 255 char max
data[].user.address2 string Conditionally returned	Additional address information for the cardholder. Allowable Values: 255 char max
data[].user.authentication object Conditionally returned	Contains the cardholder’s email address and password information. Allowable Values: `email_verified`, `email_verified_time`, `last_password_update_channel`, `last_password_update_time`
data[].user.authentication.email_verified boolean Conditionally returned	Specifies whether the email address has been verified. Allowable Values: `true`, `false`
data[].user.authentication.email_verified_time datetime Conditionally returned	Date and time when the email address was verified. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
data[].user.authentication.last_password_update_channel string Conditionally returned	Specifies the channel through which the password was last changed. Allowable Values: `USER_CHANGE`, `USER_RESET`
data[].user.authentication.last_password_update_time datetime Conditionally returned	Date and time when the password was last changed. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
data[].user.birth_date string Conditionally returned	Cardholder’s date of birth. Allowable Values: Format: yyyy-MM-dd
data[].user.birth_place string Conditionally returned	Country where the cardholder was born. Allowable Values: 255 char max ISO 3166 two-character country codes. For example, the country code for the United States is `US`. The ISO maintains the full list of ISO-3166 country codes.
data[].user.business_token string Conditionally returned	Unique identifier of the business resource. Allowable Values: Existing business resource token
data[].user.city string Conditionally returned	City where the cardholder resides. Allowable Values: 40 char max
data[].user.company string Conditionally returned	Company name. Allowable Values: 255 char max
data[].user.corporate_card_holder boolean Conditionally returned	Specifies if the cardholder holds a corporate card. Allowable Values: `true`, `false`
data[].user.country string Conditionally returned	Country where the cardholder resides. Allowable Values: 40 char max
data[].user.created_time datetime Returned	Date and time when the resource was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
data[].user.email string Conditionally returned	Valid email address of the cardholder. Allowable Values: 1–255 chars
data[].user.first_name string Conditionally returned	Cardholder’s first name. Allowable Values: 40 char max
data[].user.gender string Conditionally returned	Gender of the cardholder. Allowable Values: `F`, `M`
data[].user.honorific string Conditionally returned	Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on. Allowable Values: 10 char max
data[].user.id_card_expiration_date string Conditionally returned	Expiration date of the cardholder’s identification. Allowable Values: Format: yyyy-MM-dd
data[].user.id_card_number string Conditionally returned	Cardholder’s identification card number. Allowable Values: 255 char max
data[].user.identifications array of objects Conditionally returned	One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more `identifications` objects
data[].user.identifications[].expiration_date string Conditionally returned	Expiration date of the identification, if applicable. Allowable Values: Format: yyyy-MM-dd
data[].user.identifications[].type string Conditionally returned	Type of identification. Allowable Values: `SSN`, `TIN`, `SIN`, `NIN`, `PASSPORT_NUMBER`, `DRIVERS_LICENSE`, `BUSINESS_NUMBER`, `BUSINESS_TAX_ID`, `TAXPAYER_REFERENCE`
data[].user.identifications[].value string Conditionally returned	Number associated with the identification. Allowable Values: 255 char max
data[].user.ip_address string Conditionally returned	Cardholder’s IP address. Allowable Values: 39 char max
data[].user.last_modified_time datetime Returned	Date and time when the resource was last updated, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
data[].user.last_name string Conditionally returned	Cardholder’s last name. Allowable Values: 40 char max
data[].user.metadata object Conditionally returned	Associates any additional metadata you provide with the cardholder. Allowable Values: You can define the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"`
data[].user.middle_name string Conditionally returned	Cardholder’s middle name. Allowable Values: 40 char max
data[].user.nationality string Conditionally returned	Cardholder’s nationality. Allowable Values: 255 char max
data[].user.notes string Conditionally returned	Any additional information pertaining to the cardholder. Allowable Values: 255 char max
data[].user.parent_token string Conditionally returned	Unique identifier of the parent user or business resource. Allowable Values: 1–36 chars
data[].user.passport_expiration_date string Conditionally returned	Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd
data[].user.passport_number string Conditionally returned	Cardholder’s passport number. Allowable Values: 40 char max
data[].user.password string Conditionally returned	Password to the cardholder’s user account on the Marqeta platform. Allowable Values: 1–255 chars
data[].user.phone string Conditionally returned	Cardholder’s telephone number. Allowable Values: 255 char max
data[].user.postal_code string Conditionally returned	Postal code of the cardholder’s address. Allowable Values: 10 char max
data[].user.ssn string Conditionally returned	Cardholder’s Social Security Number (SSN). Allowable Values: Nine digits only, no delimiters.
data[].user.state string Conditionally returned	State or province where the cardholder resides. Allowable Values: 2 char max
data[].user.status string Conditionally returned	Specifies the status of the cardholder on the Marqeta platform. Allowable Values: `UNVERIFIED`, `LIMITED`, `ACTIVE`, `SUSPENDED`, `CLOSED`
data[].user.title string Conditionally returned	Professional title of the cardholder, such as Chief Comptroller. Allowable Values: 255 char max
data[].user.token string Conditionally returned	Unique identifier of the cardholder. Allowable Values: 1–36 chars
data[].user.uses_parent_account boolean Conditionally returned	Indicates whether the child shares balances with the parent (`true`), or the child’s balances are independent of the parent (`false`). Allowable Values: `true`, `false`
data[].user.zip string Conditionally returned	United States ZIP code of the cardholder’s address. Allowable Values: 10 char max
data[].wallet_provider_profile object Conditionally returned	Contains information held and provided by the digital wallet provider. Allowable Values: `account`, `device_score`, `pan_source`, `reason_code`, `recommendation_reasons`, `risk_assessment`
data[].wallet_provider_profile.account object Conditionally returned	Contains information related to the cardholder and provided by the digital wallet provider. Allowable Values: `email_address`, `id`, `score`
data[].wallet_provider_profile.account.email_address string Conditionally returned	Digital wallet provider’s email address for the cardholder. Allowable Values: 255 char max
data[].wallet_provider_profile.account.id string Conditionally returned	Digital wallet provider’s identity number for the cardholder. Allowable Values: 20 char max
data[].wallet_provider_profile.account.score string Conditionally returned	Score from the digital wallet provider. Allowable Values: 50 char max
data[].wallet_provider_profile.device_score string Conditionally returned	Score from the device. Allowable Values: 50 char max
data[].wallet_provider_profile.pan_source string Conditionally returned	Source from which the digital wallet provider obtained the card primary account number (PAN). Allowable Values: `KEY_ENTERED`, `ON_FILE`, `MOBILE_BANKING_APP`
data[].wallet_provider_profile.reason_code string Conditionally returned	Reason for the wallet provider’s provisioning decision. - 01 – Cardholder’s wallet account is too new relative to launch. - 02 – Cardholder’s wallet account is too new relative to provisioning request. - 03 – Cardholder’s wallet account/card pair is newer than date threshold. - 04 – Changes made to account data within the account threshold. - 05 – Suspicious transactions linked to this account. - 06 – Account has not had activity in the last year. - 07 – Suspended cards in the secure element. - 08 – Device was put in lost mode in the last seven days for longer than the duration threshold. - 09 – The number of provisioning attempts on this device in 24 hours exceeds threshold. - 0A – There have been more than the threshold number of different cards attempted at provisioning to this phone in 24 hours. - 0B – The card provisioning attempt contains a distinct name in excess of the threshold. - 0C – The device score is less than 3. - 0D – The account score is less than 4. - 0E – Device provisioning location outside of the cardholder’s wallet account home country. - 0G – Suspect fraud. Allowable Values: 01, 02, 03, 04, 05, 06, 07, 08, 09, 0A, 0B, 0C, 0D, 0E, 0G
data[].wallet_provider_profile.recommendation_reasons array of strings Conditionally returned	Array of recommendation reasons from the digital wallet provider. Allowable Values: Valid array of one or more recommendation reasons
data[].wallet_provider_profile.risk_assessment object Conditionally returned	Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token. Allowable Values: `score`, `version`
data[].wallet_provider_profile.risk_assessment.score string Conditionally returned	Wallet provider’s decision as to whether the digital wallet token should be provisioned. Allowable Values: `DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN`
data[].wallet_provider_profile.risk_assessment.version string Conditionally returned	Wallet provider’s risk assessment version. Allowable Values: Version information, as provided by the wallet provider
end_index integer Conditionally returned	Sort order index of the last resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer
is_more boolean Conditionally returned	A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that no more unreturned resources exist. This field is returned if there are resources in your returned array. Allowable Values: `true`, `false`
start_index integer Conditionally returned	Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer

Retrieve digital wallet token

Action: GET Endpoint: /digitalwallettokens/{token} Use this endpoint to retrieve a specific digital wallet token.

URL path parameters

Fields	Description
token string Required	Unique identifier of the digital wallet token (DWT). Allowable Values: Existing DWT token

Response body

Fields	Description
address_verification object Conditionally returned	Contains address verification information. Allowable Values: `name`, `postal_code`, `street_address`, `zip`
address_verification.name string Conditionally returned	Name of the cardholder. Allowable Values: 40 char max
address_verification.postal_code string Conditionally returned	Postal code. Allowable Values: 10 char max
address_verification.street_address string Conditionally returned	Street address provided by the cardholder. Allowable Values: 40 char max
address_verification.zip string Conditionally returned	United States ZIP code. Allowable Values: 10 char max
card_token string Conditionally returned	Unique identifier of the card. Allowable Values: Existing card token
created_time datetime Conditionally returned	Date and time when the digital wallet token object was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
device object Conditionally returned	Contains information related to the device being provisioned. Allowable Values: `device_id`, `ip_address`, `language_code`, `location`, `name`, `phone_number`, `token`, `type`
device.device_id string Conditionally returned	Identity number of the device. Allowable Values: 24 char max
device.ip_address string Conditionally returned	Device’s IP address. Allowable Values: IP address format, 50 char max
device.language_code string Conditionally returned	Language the device is configured to use. Allowable Values: 50 char max
device.location string Conditionally returned	Geographic coordinates of the device. Allowable Values: Latitude and longitude in `DDD.DD/DDD.DD` format. NOTE: Both the longitude and latitude are prefixed with either a `+` or `-` symbol, for example: `+42.29/-71.07`.
device.name string Conditionally returned	Name of the device. Allowable Values: 50 char max
device.phone_number string Conditionally returned	Device’s telephone number. Allowable Values: 50 char max
device.token string Conditionally returned	Unique identifier of the device object. Allowable Values: 36 char max
device.type string Conditionally returned	Type of device being provisioned. Allowable Values: `MOBILE_PHONE`, `WATCH`, `TABLET`, `MOBILE_PHONE_OR_TABLET`, `VEHICLE`, `APPLIANCE`, `LAPTOP`, `GAMING_DEVICE`, `WEARABLE_DEVICE`, `UNKNOWN`
fulfillment_status string Conditionally returned	Digital wallet token’s provisioning status. For fulfillment status descriptions, see Create digital wallet token transition. Allowable Values: `DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN`, `REJECTED`, `PROVISIONED`
issuer_eligibility_decision string Conditionally returned	The Marqeta platform’s decision as to whether the digital wallet token should be provisioned. - 0000: The token should be provisioned. - token.activation.verification.required: Provisioning is pending; further action is required for completion. For all other values, check the value of the `fulfillment_status` field to definitively ascertain the provisioning outcome. NOTE: The value `invalid.cid` indicates an invalid CVV2 number. Allowable Values: 0000, `cardaccount.verified`, `card.suspicious`, `token.activation.verification.required`, `token.activation-request.decline`, `card.not.active`, `invalid.cid`, `card.expired`, `card.suspended`, `cardholder.not.active`
last_modified_time datetime Conditionally returned	Date and time when the digital wallet token object was last modified, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
metadata object Conditionally returned	Contains additional information about the digital wallet token. Allowable Values: `cardproduct_preferred_notification_language`, `issuer_product_config_id`
metadata.cardproduct_preferred_notification_language string Conditionally returned	Language specified in the `config.transaction_controls.notification_language` field of the card product: - ces – Czech - deu – German - eng – English - fra – French - 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. 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. Allowable Values: `REQUESTED`, `REQUEST_DECLINED`, `ACTIVE`, `SUSPENDED`, `TERMINATED`
state_reason string Conditionally returned	Reason why the digital wallet token transitioned to its current state. Allowable Values: 255 char max
token string Conditionally returned	Unique identifier of the digital wallet token. Allowable Values: Existing digital wallet token.
token_service_provider object Conditionally returned	Contains information held and provided by the token service provider (card network). Allowable Values: `correlation_id`, `pan_reference_id`, `token_assurance_level`, `token_eligibility_decision`, `token_expiration`, `token_pan`, `token_reference_id`, `token_requestor_id`, `token_requestor_name`, `token_score`, `token_type`
token_service_provider.correlation_id string Conditionally returned	For Mastercard only. Unique value representing a tokenization request. Allowable Values: Existing correlation identifier
token_service_provider.pan_reference_id string Conditionally returned	Unique identifier of the digital wallet token primary account number (PAN) within the card network. Allowable Values: Existing PAN Reference ID
token_service_provider.token_assurance_level string Conditionally returned	For Mastercard only. Represents the confidence level in the digital wallet token. Allowable Values: 0-99
token_service_provider.token_eligibility_decision string Conditionally returned	Digital wallet’s decision as to whether the digital wallet token should be provisioned. Allowable Values: `DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN`
token_service_provider.token_expiration string Conditionally returned	Expiration date of the digital wallet token. Allowable Values: Format: MMyy
token_service_provider.token_pan string Conditionally returned	Primary account number (PAN) of the digital wallet token. Allowable Values: 16 char max
token_service_provider.token_reference_id string Conditionally returned	Unique identifier of the digital wallet token within the card network. Allowable Values: Existing Token Reference ID
token_service_provider.token_requestor_id string Conditionally returned	Unique numerical identifier of the token requestor within the card network. These ID numbers map to `token_requestor_name` field values as follows: Mastercard - 50110030273 – `APPLE_PAY` - 50120834693 – `ANDROID_PAY` - 50139059239 – `SAMSUNG_PAY` Visa - 40010030273 – `APPLE_PAY` - 40010075001 – `ANDROID_PAY` - 40010043095 – `SAMSUNG_PAY` - 40010075196 – `MICROSOFT_PAY` - 40010075338 – `VISA_CHECKOUT` - 40010075449 – `FACEBOOK` - 40010075839 – `NETFLIX` - 40010077056 – `FITBIT_PAY` - 40010069887 – `GARMIN_PAY` Allowable Values: 11 char max Example Values: - Mastercard – 50110030273, 50120834693, 50139059239 - Visa – 40010030273, 40010075001, 40010075338, 40010075449, 40010075839, 40010043095
token_service_provider.token_requestor_name string Conditionally returned	Name of the token requestor within the card network. NOTE: The list of example values for this field is maintained by the card networks and is subject to change. Allowable Values: 255 char max Example Values: - Mastercard – `APPLE_PAY`, `ANDROID_PAY`, `SAMSUNG_PAY` - Visa – `APPLE_PAY`, `ANDROID_PAY`, `SAMSUNG_PAY`, `MICROSOFT_PAY`, `VISA_CHECKOUT`, `FACEBOOK`, `NETFLIX`, `FITBIT_PAY`, `GARMIN_PAY`
token_service_provider.token_score string Conditionally returned	Token score assigned by the digital wallet. Allowable Values: 25 char max
token_service_provider.token_type string Conditionally returned	Type of the digital wallet token. Allowable Values: `MERCHANT_CARD_ON_FILE`, `DEVICE_SECURE_ELEMENT`, `DEVICE_CLOUD_BASED`, `ECOMMERCE_DIGITAL_WALLET`
transaction_device object Conditionally returned	Contains information about the device used in the transaction to enhance the risk decisioning process. Use this data to improve fraud prevention and dispute resolution. Allowable Values: `binding_id`, `ip_address`, `location`, `phone_number`
transaction_device.binding_id string Conditionally returned	Unique identifier of the data component bound to the credential. Allowable Values: 48 char max
transaction_device.ip_address string Conditionally returned	IP address of the device. The presence of the IP address helps determine if the transaction was initiated from an unusual network, helping establish a pattern of safe device usage that further confirms the authenticity of the consumer who initiated the transaction. Allowable Values: IP address format, 39 char max
transaction_device.location string Conditionally returned	Geographic coordinates of the device. Contains the latitude and longitude of the device used when the cardholder was authenticated during checkout. This field helps to determine if the transaction was initiated from an unexpected location. Allowable Values: Latitude and longitude in `DDD.DD/DDD.DD` format.
transaction_device.phone_number string Conditionally returned	Telephone number of the device. Contains the phone number that was used to authenticate the consumer during checkout, or the consumer’s preferred phone number. The presence of the phone number helps establish the consumer’s authenticity when matching the phone number provided during checkout to a list of known phone numbers for the consumer. Allowable Values: 15 char max
user object Conditionally returned	Contains information about a cardholder. Allowable Values: `account_holder_group_token`, `active`, `address1`, `address2`, `authentication`, `birth_date`, `birth_place`, `business_token`, `city`, `company`, `corporate_card_holder`, `country`, `created_time`, `email`, `first_name`, `gender`, `honorific`, `id_card_expiration_date`, `id_card_number`, `identifications`, `ip_address`, `last_modified_time`, `last_name`, `metadata`, `middle_name`, `nationality`, `notes`, `parent_token`, `passport_expiration_date`, `passport_number`, `password`, `phone`, `postal_code`, `ssn`, `state`, `status`, `title`, `token`, `uses_parent_account`, `zip`
user.account_holder_group_token string Conditionally returned	Associates the specified account holder group with the cardholder. Allowable Values: 36 char max
user.active boolean Conditionally returned	Specifies if the cardholder is in the `ACTIVE` state on the Marqeta platform. Allowable Values: `true`, `false`
user.address1 string Conditionally returned	Cardholder’s address. Allowable Values: 255 char max
user.address2 string Conditionally returned	Additional address information for the cardholder. Allowable Values: 255 char max
user.authentication object Conditionally returned	Contains the cardholder’s email address and password information. Allowable Values: `email_verified`, `email_verified_time`, `last_password_update_channel`, `last_password_update_time`
user.authentication.email_verified boolean Conditionally returned	Specifies whether the email address has been verified. Allowable Values: `true`, `false`
user.authentication.email_verified_time datetime Conditionally returned	Date and time when the email address was verified. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
user.authentication.last_password_update_channel string Conditionally returned	Specifies the channel through which the password was last changed. Allowable Values: `USER_CHANGE`, `USER_RESET`
user.authentication.last_password_update_time datetime Conditionally returned	Date and time when the password was last changed. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
user.birth_date string Conditionally returned	Cardholder’s date of birth. Allowable Values: Format: yyyy-MM-dd
user.birth_place string Conditionally returned	Country where the cardholder was born. Allowable Values: 255 char max ISO 3166 two-character country codes. For example, the country code for the United States is `US`. The ISO maintains the full list of ISO 3166 country codes.
user.business_token string Conditionally returned	Unique identifier of the business resource. Allowable Values: Existing business resource token
user.city string Conditionally returned	City where the cardholder resides. Allowable Values: 40 char max
user.company string Conditionally returned	Company name. Allowable Values: 255 char max
user.corporate_card_holder boolean Conditionally returned	Specifies if the cardholder holds a corporate card. Allowable Values: `true`, `false`
user.country string Conditionally returned	Country where the cardholder resides. Allowable Values: 40 char max
user.created_time datetime Returned	Date and time when the resource was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
user.email string Conditionally returned	Valid email address of the cardholder. Allowable Values: 1–255 chars
user.first_name string Conditionally returned	Cardholder’s first name. Allowable Values: 40 char max
user.gender string Conditionally returned	Gender of the cardholder. Allowable Values: `F`, `M`
user.honorific string Conditionally returned	Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on. Allowable Values: 10 char max
user.id_card_expiration_date string Conditionally returned	Expiration date of the cardholder’s identification. Allowable Values: Format: yyyy-MM-dd
user.id_card_number string Conditionally returned	Cardholder’s identification card number. Allowable Values: 255 char max
user.identifications array of objects Conditionally returned	One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more `identifications` objects
user.identifications[].expiration_date string Conditionally returned	Expiration date of the identification, if applicable. Allowable Values: Format: yyyy-MM-dd
user.identifications[].type string Conditionally returned	Type of identification. Allowable Values: `SSN`, `TIN`, `SIN`, `NIN`, `PASSPORT_NUMBER`, `DRIVERS_LICENSE`, `BUSINESS_NUMBER`, `BUSINESS_TAX_ID`, `TAXPAYER_REFERENCE`
user.identifications[].value string Conditionally returned	Number associated with the identification. Allowable Values: 255 char max
user.ip_address string Conditionally returned	Cardholder’s IP address. Allowable Values: 39 char max
user.last_modified_time datetime Returned	Date and time when the resource was last updated, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
user.last_name string Conditionally returned	Cardholder’s last name. Allowable Values: 40 char max
user.metadata object Conditionally returned	Associates any additional metadata you provide with the cardholder. Allowable Values: You can define the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"`
user.middle_name string Conditionally returned	Cardholder’s middle name. Allowable Values: 40 char max
user.nationality string Conditionally returned	Cardholder’s nationality. Allowable Values: 255 char max
user.notes string Conditionally returned	Any additional information pertaining to the cardholder. Allowable Values: 255 char max
user.parent_token string Conditionally returned	Unique identifier of the parent user or business resource. Allowable Values: 1–36 chars
user.passport_expiration_date string Conditionally returned	Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd
user.passport_number string Conditionally returned	Cardholder’s passport number. Allowable Values: 40 char max
user.password string Conditionally returned	Password to the cardholder’s user account on the Marqeta platform. Allowable Values: 1–255 chars
user.phone string Conditionally returned	Cardholder’s telephone number. Allowable Values: 255 char max
user.postal_code string Conditionally returned	Postal code of the cardholder’s address. Allowable Values: 10 char max
user.ssn string Conditionally returned	Cardholder’s Social Security Number (SSN). Allowable Values: Nine digits only, no delimiters.
user.state string Conditionally returned	State or province where the cardholder resides. Allowable Values: 2 char max
user.status string Conditionally returned	Specifies the status of the cardholder on the Marqeta platform. Allowable Values: `UNVERIFIED`, `LIMITED`, `ACTIVE`, `SUSPENDED`, `CLOSED`
user.title string Conditionally returned	Professional title of the cardholder, such as Chief Comptroller. Allowable Values: 255 char max
user.token string Conditionally returned	Unique identifier of the cardholder. Allowable Values: 1–36 chars
user.uses_parent_account boolean Conditionally returned	Indicates whether the child shares balances with the parent (`true`), or the child’s balances are independent of the parent (`false`). Allowable Values: `true`, `false`
user.zip string Conditionally returned	United States ZIP code of the cardholder’s address. Allowable Values: 10 char max
wallet_provider_profile object Conditionally returned	Contains information held and provided by the digital wallet provider. Allowable Values: `account`, `device_score`, `pan_source`, `reason_code`, `recommendation_reasons`, `risk_assessment`
wallet_provider_profile.account object Conditionally returned	Contains information related to the cardholder and provided by the digital wallet provider. Allowable Values: `email_address`, `id`, `score`
wallet_provider_profile.account.email_address string Conditionally returned	Digital wallet provider’s email address for the cardholder. Allowable Values: 255 char max
wallet_provider_profile.account.id string Conditionally returned	Digital wallet provider’s identity number for the cardholder. Allowable Values: 20 char max
wallet_provider_profile.account.score string Conditionally returned	Score from the digital wallet provider. Allowable Values: 50 char max
wallet_provider_profile.device_score string Conditionally returned	Score from the device. Allowable Values: 50 char max
wallet_provider_profile.pan_source string Conditionally returned	Source from which the digital wallet provider obtained the card primary account number (PAN). Allowable Values: `KEY_ENTERED`, `ON_FILE`, `MOBILE_BANKING_APP`
wallet_provider_profile.reason_code string Conditionally returned	Reason for the wallet provider’s provisioning decision. - 01 – Cardholder’s wallet account is too new relative to launch. - 02 – Cardholder’s wallet account is too new relative to provisioning request. - 03 – Cardholder’s wallet account/card pair is newer than date threshold. - 04 – Changes made to account data within the account threshold. - 05 – Suspicious transactions linked to this account. - 06 – Account has not had activity in the last year. - 07 – Suspended cards in the secure element. - 08 – Device was put in lost mode in the last seven days for longer than the duration threshold. - 09 – The number of provisioning attempts on this device in 24 hours exceeds threshold. - 0A – There have been more than the threshold number of different cards attempted at provisioning to this phone in 24 hours. - 0B – The card provisioning attempt contains a distinct name in excess of the threshold. - 0C – The device score is less than 3. - 0D – The account score is less than 4. - 0E – Device provisioning location outside of the cardholder’s wallet account home country. - 0G – Suspect fraud. Allowable Values: 01, 02, 03, 04, 05, 06, 07, 08, 09, 0A, 0B, 0C, 0D, 0E, 0G
wallet_provider_profile.recommendation_reasons array of strings Conditionally returned	Array of recommendation reasons from the digital wallet provider. Allowable Values: Valid array of one or more recommendation reasons
wallet_provider_profile.risk_assessment object Conditionally returned	Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token. Allowable Values: `score`, `version`
wallet_provider_profile.risk_assessment.score string Conditionally returned	Wallet provider’s decision as to whether the digital wallet token should be provisioned. Allowable Values: `DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN`
wallet_provider_profile.risk_assessment.version string Conditionally returned	Wallet provider’s risk assessment version. Allowable Values: Version information, as provided by the wallet provider

Sample response body

JSON

{
  "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"
  }
}

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.

URL path parameters

Fields	Description
card_token string Required	Unique identifier of the card. Used to minimize the need to exchange card details during subsequent calls, and also for troubleshooting. Allowable Values: Existing card token

URL query parameters

Fields	Description
count integer Optional	Number of digital wallet token resources to retrieve. Allowable Values: Any integer Default value: 5
start_index integer Optional	Sort order index of the first digital wallet token resource in the returned array. Allowable Values: Any integer Default value: 0
sort_by string Optional	Field on which to sort. Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`. Prefix the field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order. Allowable Values: `createdTime`, `lastModifiedTime`, or any field in the resource model Default value: `-createdTime`

Response body

Fields	Description
count integer Conditionally returned	Number of resources returned. This field is returned if there are resources in your returned array. Allowable Values: Any integer
data array of objects Conditionally returned	Array of digital wallet token resources. Resources are returned as appropriate to your query. Allowable Values: Valid array of one or more digital wallet token resources
data[].address_verification object Conditionally returned	Contains address verification information. Allowable Values: `name`, `postal_code`, `street_address`, `zip`
data[].address_verification.name string Conditionally returned	Name of the cardholder. Allowable Values: 40 char max
data[].address_verification.postal_code string Conditionally returned	Postal code. Allowable Values: 10 char max
data[].address_verification.street_address string Conditionally returned	Street address provided by the cardholder. Allowable Values: 40 char max
data[].address_verification.zip string Conditionally returned	United States ZIP code. Allowable Values: 10 char max
data[].card_token string Conditionally returned	Unique identifier of the card. Allowable Values: Existing card token
data[].created_time datetime Conditionally returned	Date and time when the digital wallet token object was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
data[].device object Conditionally returned	Contains information related to the device being provisioned. Allowable Values: `device_id`, `ip_address`, `language_code`, `location`, `name`, `phone_number`, `token`, `type`
data[].device.device_id string Conditionally returned	Identity number of the device. Allowable Values: 24 char max
data[].device.ip_address string Conditionally returned	Device’s IP address. Allowable Values: IP address format, 50 char max
data[].device.language_code string Conditionally returned	Language the device is configured to use. Allowable Values: 50 char max
data[].device.location string Conditionally returned	Geographic coordinates of the device. Allowable Values: Latitude and longitude in `DDD.DD/DDD.DD` format. NOTE: Both the longitude and latitude are prefixed with either a `+` or `-` symbol, for example: `+42.29/-71.07`.
data[].device.name string Conditionally returned	Name of the device. Allowable Values: 50 char max
data[].device.phone_number string Conditionally returned	Device’s telephone number. Allowable Values: 50 char max
data[].device.token string Conditionally returned	Unique identifier of the device object. Allowable Values: 36 char max
data[].device.type string Conditionally returned	Type of device being provisioned. Allowable Values: `MOBILE_PHONE`, `WATCH`, `TABLET`, `MOBILE_PHONE_OR_TABLET`, `VEHICLE`, `APPLIANCE`, `LAPTOP`, `GAMING_DEVICE`, `WEARABLE_DEVICE`, `UNKNOWN`
data[].fulfillment_status string Conditionally returned	Digital wallet token’s provisioning status. For fulfillment status descriptions, see Create digital wallet token transition. Allowable Values: `DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN`, `REJECTED`, `PROVISIONED`
data[].issuer_eligibility_decision string Conditionally returned	The Marqeta platform’s decision as to whether the digital wallet token should be provisioned. - 0000: The token should be provisioned. - token.activation.verification.required: Provisioning is pending; further action is required for completion. For all other values, check the value of the `fulfillment_status` field to definitively ascertain the provisioning outcome. NOTE: The value `invalid.cid` indicates an invalid CVV2 number. Allowable Values: 0000, `cardaccount.verified`, `card.suspicious`, `token.activation.verification.required`, `token.activation-request.decline`, `card.not.active`, `invalid.cid`, `card.expired`, `card.suspended`, `cardholder.not.active`
data[].last_modified_time datetime Conditionally returned	Date and time when the digital wallet token object was last modified, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
data[].metadata object Conditionally returned	Contains additional information about the digital wallet token. Allowable Values: `cardproduct_preferred_notification_language`, `issuer_product_config_id`
data[].metadata.cardproduct_preferred_notification_language string Conditionally returned	Language specified in the `config.transaction_controls.notification_language` field of the card product: - ces – Czech - deu – German - eng – English - fra – French - 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. 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. Allowable Values: `REQUESTED`, `REQUEST_DECLINED`, `ACTIVE`, `SUSPENDED`, `TERMINATED`
data[].state_reason string Conditionally returned	Reason why the digital wallet token transitioned to its current state. Allowable Values: 255 char max
data[].token string Conditionally returned	Unique identifier of the digital wallet token. Allowable Values: Existing digital wallet token.
data[].token_service_provider object Conditionally returned	Contains information held and provided by the token service provider (card network). Allowable Values: `correlation_id`, `pan_reference_id`, `token_assurance_level`, `token_eligibility_decision`, `token_expiration`, `token_pan`, `token_reference_id`, `token_requestor_id`, `token_requestor_name`, `token_score`, `token_type`
data[].token_service_provider.correlation_id string Conditionally returned	For Mastercard only. Unique value representing a tokenization request. Allowable Values: Existing correlation identifier
data[].token_service_provider.pan_reference_id string Conditionally returned	Unique identifier of the digital wallet token primary account number (PAN) within the card network. Allowable Values: Existing PAN Reference ID
data[].token_service_provider.token_assurance_level string Conditionally returned	For Mastercard only. Represents the confidence level in the digital wallet token. Allowable Values: 0-99
data[].token_service_provider.token_eligibility_decision string Conditionally returned	Digital wallet’s decision as to whether the digital wallet token should be provisioned. Allowable Values: `DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN`
data[].token_service_provider.token_expiration string Conditionally returned	Expiration date of the digital wallet token. Allowable Values: Format: MMyy
data[].token_service_provider.token_pan string Conditionally returned	Primary account number (PAN) of the digital wallet token. Allowable Values: 16 char max
data[].token_service_provider.token_reference_id string Conditionally returned	Unique identifier of the digital wallet token within the card network. Allowable Values: Existing Token Reference ID
data[].token_service_provider.token_requestor_id string Conditionally returned	Unique numerical identifier of the token requestor within the card network. These ID numbers map to `token_requestor_name` field values as follows: Mastercard - 50110030273 – `APPLE_PAY` - 50120834693 – `ANDROID_PAY` - 50139059239 – `SAMSUNG_PAY` Visa - 40010030273 – `APPLE_PAY` - 40010075001 – `ANDROID_PAY` - 40010043095 – `SAMSUNG_PAY` - 40010075196 – `MICROSOFT_PAY` - 40010075338 – `VISA_CHECKOUT` - 40010075449 – `FACEBOOK` - 40010075839 – `NETFLIX` - 40010077056 – `FITBIT_PAY` - 40010069887 – `GARMIN_PAY` Allowable Values: 11 char max Example Values: - Mastercard – 50110030273, 50120834693, 50139059239 - Visa – 40010030273, 40010075001, 40010075338, 40010075449, 40010075839, 40010043095
data[].token_service_provider.token_requestor_name string Conditionally returned	Name of the token requestor within the card network. NOTE: The list of example values for this field is maintained by the card networks and is subject to change. Allowable Values: 255 char max Example Values: - Mastercard – `APPLE_PAY`, `ANDROID_PAY`, `SAMSUNG_PAY` - Visa – `APPLE_PAY`, `ANDROID_PAY`, `SAMSUNG_PAY`, `MICROSOFT_PAY`, `VISA_CHECKOUT`, `FACEBOOK`, `NETFLIX`, `FITBIT_PAY`, `GARMIN_PAY`
data[].token_service_provider.token_score string Conditionally returned	Token score assigned by the digital wallet. Allowable Values: 25 char max
data[].token_service_provider.token_type string Conditionally returned	Type of the digital wallet token. Allowable Values: `MERCHANT_CARD_ON_FILE`, `DEVICE_SECURE_ELEMENT`, `DEVICE_CLOUD_BASED`, `ECOMMERCE_DIGITAL_WALLET`
data[].transaction_device object Conditionally returned	Contains information about the device used in the transaction to enhance the risk decisioning process. Use this data to improve fraud prevention and dispute resolution. Allowable Values: `binding_id`, `ip_address`, `location`, `phone_number`
data[].transaction_device.binding_id string Conditionally returned	Unique identifier of the data component bound to the credential. Allowable Values: 48 char max
data[].transaction_device.ip_address string Conditionally returned	IP address of the device. The presence of the IP address helps determine if the transaction was initiated from an unusual network, helping establish a pattern of safe device usage that further confirms the authenticity of the consumer who initiated the transaction. Allowable Values: IP address format, 39 char max
data[].transaction_device.location string Conditionally returned	Geographic coordinates of the device. Contains the latitude and longitude of the device used when the cardholder was authenticated during checkout. This field helps to determine if the transaction was initiated from an unexpected location. Allowable Values: Latitude and longitude in `DDD.DD/DDD.DD` format.
data[].transaction_device.phone_number string Conditionally returned	Telephone number of the device. Contains the phone number that was used to authenticate the consumer during checkout, or the consumer’s preferred phone number. The presence of the phone number helps establish the consumer’s authenticity when matching the phone number provided during checkout to a list of known phone numbers for the consumer. Allowable Values: 15 char max
data[].user object Conditionally returned	Contains information about a cardholder. Allowable Values: `account_holder_group_token`, `active`, `address1`, `address2`, `authentication`, `birth_date`, `birth_place`, `business_token`, `city`, `company`, `corporate_card_holder`, `country`, `created_time`, `email`, `first_name`, `gender`, `honorific`, `id_card_expiration_date`, `id_card_number`, `identifications`, `ip_address`, `last_modified_time`, `last_name`, `metadata`, `middle_name`, `nationality`, `notes`, `parent_token`, `passport_expiration_date`, `passport_number`, `password`, `phone`, `postal_code`, `ssn`, `state`, `status`, `title`, `token`, `uses_parent_account`, `zip`
data[].user.account_holder_group_token string Conditionally returned	Associates the specified account holder group with the cardholder. Allowable Values: 36 char max
data[].user.active boolean Conditionally returned	Specifies if the cardholder is in the `ACTIVE` state on the Marqeta platform. Allowable Values: `true`, `false`
data[].user.address1 string Conditionally returned	Cardholder’s address. Allowable Values: 255 char max
data[].user.address2 string Conditionally returned	Additional address information for the cardholder. Allowable Values: 255 char max
data[].user.authentication object Conditionally returned	Contains the cardholder’s email address and password information. Allowable Values: `email_verified`, `email_verified_time`, `last_password_update_channel`, `last_password_update_time`
data[].user.authentication.email_verified boolean Conditionally returned	Specifies whether the email address has been verified. Allowable Values: `true`, `false`
data[].user.authentication.email_verified_time datetime Conditionally returned	Date and time when the email address was verified. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
data[].user.authentication.last_password_update_channel string Conditionally returned	Specifies the channel through which the password was last changed. Allowable Values: `USER_CHANGE`, `USER_RESET`
data[].user.authentication.last_password_update_time datetime Conditionally returned	Date and time when the password was last changed. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
data[].user.birth_date string Conditionally returned	Cardholder’s date of birth. Allowable Values: Format: yyyy-MM-dd
data[].user.birth_place string Conditionally returned	Country where the cardholder was born. Allowable Values: 255 char max ISO 3166 two-character country codes. For example, the country code for the United States is `US`. The ISO maintains the full list of ISO-3166 country codes.
data[].user.business_token string Conditionally returned	Unique identifier of the business resource. Allowable Values: Existing business resource token
data[].user.city string Conditionally returned	City where the cardholder resides. Allowable Values: 40 char max
data[].user.company string Conditionally returned	Company name. Allowable Values: 255 char max
data[].user.corporate_card_holder boolean Conditionally returned	Specifies if the cardholder holds a corporate card. Allowable Values: `true`, `false`
data[].user.country string Conditionally returned	Country where the cardholder resides. Allowable Values: 40 char max
data[].user.created_time datetime Returned	Date and time when the resource was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
data[].user.email string Conditionally returned	Valid email address of the cardholder. Allowable Values: 1–255 chars
data[].user.first_name string Conditionally returned	Cardholder’s first name. Allowable Values: 40 char max
data[].user.gender string Conditionally returned	Gender of the cardholder. Allowable Values: `F`, `M`
data[].user.honorific string Conditionally returned	Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on. Allowable Values: 10 char max
data[].user.id_card_expiration_date string Conditionally returned	Expiration date of the cardholder’s identification. Allowable Values: Format: yyyy-MM-dd
data[].user.id_card_number string Conditionally returned	Cardholder’s identification card number. Allowable Values: 255 char max
data[].user.identifications array of objects Conditionally returned	One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more `identifications` objects
data[].user.identifications[].expiration_date string Conditionally returned	Expiration date of the identification, if applicable. Allowable Values: Format: yyyy-MM-dd
data[].user.identifications[].type string Conditionally returned	Type of identification. Allowable Values: `SSN`, `TIN`, `SIN`, `NIN`, `PASSPORT_NUMBER`, `DRIVERS_LICENSE`, `BUSINESS_NUMBER`, `BUSINESS_TAX_ID`, `TAXPAYER_REFERENCE`
data[].user.identifications[].value string Conditionally returned	Number associated with the identification. Allowable Values: 255 char max
data[].user.ip_address string Conditionally returned	Cardholder’s IP address. Allowable Values: 39 char max
data[].user.last_modified_time datetime Returned	Date and time when the resource was last updated, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
data[].user.last_name string Conditionally returned	Cardholder’s last name. Allowable Values: 40 char max
data[].user.metadata object Conditionally returned	Associates any additional metadata you provide with the cardholder. Allowable Values: You can define the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"`
data[].user.middle_name string Conditionally returned	Cardholder’s middle name. Allowable Values: 40 char max
data[].user.nationality string Conditionally returned	Cardholder’s nationality. Allowable Values: 255 char max
data[].user.notes string Conditionally returned	Any additional information pertaining to the cardholder. Allowable Values: 255 char max
data[].user.parent_token string Conditionally returned	Unique identifier of the parent user or business resource. Allowable Values: 1–36 chars
data[].user.passport_expiration_date string Conditionally returned	Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd
data[].user.passport_number string Conditionally returned	Cardholder’s passport number. Allowable Values: 40 char max
data[].user.password string Conditionally returned	Password to the cardholder’s user account on the Marqeta platform. Allowable Values: 1–255 chars
data[].user.phone string Conditionally returned	Cardholder’s telephone number. Allowable Values: 255 char max
data[].user.postal_code string Conditionally returned	Postal code of the cardholder’s address. Allowable Values: 10 char max
data[].user.ssn string Conditionally returned	Cardholder’s Social Security Number (SSN). Allowable Values: Nine digits only, no delimiters.
data[].user.state string Conditionally returned	State or province where the cardholder resides. Allowable Values: 2 char max
data[].user.status string Conditionally returned	Specifies the status of the cardholder on the Marqeta platform. Allowable Values: `UNVERIFIED`, `LIMITED`, `ACTIVE`, `SUSPENDED`, `CLOSED`
data[].user.title string Conditionally returned	Professional title of the cardholder, such as Chief Comptroller. Allowable Values: 255 char max
data[].user.token string Conditionally returned	Unique identifier of the cardholder. Allowable Values: 1–36 chars
data[].user.uses_parent_account boolean Conditionally returned	Indicates whether the child shares balances with the parent (`true`), or the child’s balances are independent of the parent (`false`). Allowable Values: `true`, `false`
data[].user.zip string Conditionally returned	United States ZIP code of the cardholder’s address. Allowable Values: 10 char max
data[].wallet_provider_profile object Conditionally returned	Contains information held and provided by the digital wallet provider. Allowable Values: `account`, `device_score`, `pan_source`, `reason_code`, `recommendation_reasons`, `risk_assessment`
data[].wallet_provider_profile.account object Conditionally returned	Contains information related to the cardholder and provided by the digital wallet provider. Allowable Values: `email_address`, `id`, `score`
data[].wallet_provider_profile.account.email_address string Conditionally returned	Digital wallet provider’s email address for the cardholder. Allowable Values: 255 char max
data[].wallet_provider_profile.account.id string Conditionally returned	Digital wallet provider’s identity number for the cardholder. Allowable Values: 20 char max
data[].wallet_provider_profile.account.score string Conditionally returned	Score from the digital wallet provider. Allowable Values: 50 char max
data[].wallet_provider_profile.device_score string Conditionally returned	Score from the device. Allowable Values: 50 char max
data[].wallet_provider_profile.pan_source string Conditionally returned	Source from which the digital wallet provider obtained the card primary account number (PAN). Allowable Values: `KEY_ENTERED`, `ON_FILE`, `MOBILE_BANKING_APP`
data[].wallet_provider_profile.reason_code string Conditionally returned	Reason for the wallet provider’s provisioning decision. - 01 – Cardholder’s wallet account is too new relative to launch. - 02 – Cardholder’s wallet account is too new relative to provisioning request. - 03 – Cardholder’s wallet account/card pair is newer than date threshold. - 04 – Changes made to account data within the account threshold. - 05 – Suspicious transactions linked to this account. - 06 – Account has not had activity in the last year. - 07 – Suspended cards in the secure element. - 08 – Device was put in lost mode in the last seven days for longer than the duration threshold. - 09 – The number of provisioning attempts on this device in 24 hours exceeds threshold. - 0A – There have been more than the threshold number of different cards attempted at provisioning to this phone in 24 hours. - 0B – The card provisioning attempt contains a distinct name in excess of the threshold. - 0C – The device score is less than 3. - 0D – The account score is less than 4. - 0E – Device provisioning location outside of the cardholder’s wallet account home country. - 0G – Suspect fraud. Allowable Values: 01, 02, 03, 04, 05, 06, 07, 08, 09, 0A, 0B, 0C, 0D, 0E, 0G
data[].wallet_provider_profile.recommendation_reasons array of strings Conditionally returned	Array of recommendation reasons from the digital wallet provider. Allowable Values: Valid array of one or more recommendation reasons
data[].wallet_provider_profile.risk_assessment object Conditionally returned	Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token. Allowable Values: `score`, `version`
data[].wallet_provider_profile.risk_assessment.score string Conditionally returned	Wallet provider’s decision as to whether the digital wallet token should be provisioned. Allowable Values: `DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN`
data[].wallet_provider_profile.risk_assessment.version string Conditionally returned	Wallet provider’s risk assessment version. Allowable Values: Version information, as provided by the wallet provider
end_index integer Conditionally returned	Sort order index of the last resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer
is_more boolean Conditionally returned	A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that no more unreturned resources exist. This field is returned if there are resources in your returned array. Allowable Values: `true`, `false`
start_index integer Conditionally returned	Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer

Sample response body

JSON

{
  "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"
      }
    }
  ]
}

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.

URL path parameters

Fields	Description
token string Required	Unique identifier of the digital wallet token (DWT). Allowable Values: Existing DWT token

Response body

Fields	Description
address_verification object Conditionally returned	Contains address verification information. Allowable Values: `name`, `postal_code`, `street_address`, `zip`
address_verification.name string Conditionally returned	Name of the cardholder. Allowable Values: 40 char max
address_verification.postal_code string Conditionally returned	Postal code. Allowable Values: 10 char max
address_verification.street_address string Conditionally returned	Street address provided by the cardholder. Allowable Values: 40 char max
address_verification.zip string Conditionally returned	United States ZIP code. Allowable Values: 10 char max
card_token string Conditionally returned	Unique identifier of the card. Allowable Values: Existing card token
created_time datetime Conditionally returned	Date and time when the digital wallet token object was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
device object Conditionally returned	Contains information related to the device being provisioned. Allowable Values: `device_id`, `ip_address`, `language_code`, `location`, `name`, `phone_number`, `token`, `type`
device.device_id string Conditionally returned	Identity number of the device. Allowable Values: 24 char max
device.ip_address string Conditionally returned	Device’s IP address. Allowable Values: IP address format, 50 char max
device.language_code string Conditionally returned	Language the device is configured to use. Allowable Values: 50 char max
device.location string Conditionally returned	Geographic coordinates of the device. Allowable Values: Latitude and longitude in `DDD.DD/DDD.DD` format. NOTE: Both the longitude and latitude are prefixed with either a `+` or `-` symbol, for example: `+42.29/-71.07`.
device.name string Conditionally returned	Name of the device. Allowable Values: 50 char max
device.phone_number string Conditionally returned	Device’s telephone number. Allowable Values: 50 char max
device.token string Conditionally returned	Unique identifier of the device object. Allowable Values: 36 char max
device.type string Conditionally returned	Type of device being provisioned. Allowable Values: `MOBILE_PHONE`, `WATCH`, `TABLET`, `MOBILE_PHONE_OR_TABLET`, `VEHICLE`, `APPLIANCE`, `LAPTOP`, `GAMING_DEVICE`, `WEARABLE_DEVICE`, `UNKNOWN`
fulfillment_status string Conditionally returned	Digital wallet token’s provisioning status. For fulfillment status descriptions, see Create digital wallet token transition. Allowable Values: `DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN`, `REJECTED`, `PROVISIONED`
issuer_eligibility_decision string Conditionally returned	The Marqeta platform’s decision as to whether the digital wallet token should be provisioned. - 0000: The token should be provisioned. - token.activation.verification.required: Provisioning is pending; further action is required for completion. For all other values, check the value of the `fulfillment_status` field to definitively ascertain the provisioning outcome. NOTE: The value `invalid.cid` indicates an invalid CVV2 number. Allowable Values: 0000, `cardaccount.verified`, `card.suspicious`, `token.activation.verification.required`, `token.activation-request.decline`, `card.not.active`, `invalid.cid`, `card.expired`, `card.suspended`, `cardholder.not.active`
last_modified_time datetime Conditionally returned	Date and time when the digital wallet token object was last modified, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
metadata object Conditionally returned	Contains additional information about the digital wallet token. Allowable Values: `cardproduct_preferred_notification_language`, `issuer_product_config_id`
metadata.cardproduct_preferred_notification_language string Conditionally returned	Language specified in the `config.transaction_controls.notification_language` field of the card product: - ces – Czech - deu – German - eng – English - fra – French - 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. 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. Allowable Values: `REQUESTED`, `REQUEST_DECLINED`, `ACTIVE`, `SUSPENDED`, `TERMINATED`
state_reason string Conditionally returned	Reason why the digital wallet token transitioned to its current state. Allowable Values: 255 char max
token string Conditionally returned	Unique identifier of the digital wallet token. Allowable Values: Existing digital wallet token.
token_service_provider object Conditionally returned	Contains information held and provided by the token service provider (card network). Allowable Values: `correlation_id`, `pan_reference_id`, `token_assurance_level`, `token_eligibility_decision`, `token_expiration`, `token_pan`, `token_reference_id`, `token_requestor_id`, `token_requestor_name`, `token_score`, `token_type`
token_service_provider.correlation_id string Conditionally returned	For Mastercard only. Unique value representing a tokenization request. Allowable Values: Existing correlation identifier
token_service_provider.pan_reference_id string Conditionally returned	Unique identifier of the digital wallet token primary account number (PAN) within the card network. Allowable Values: Existing PAN Reference ID
token_service_provider.token_assurance_level string Conditionally returned	For Mastercard only. Represents the confidence level in the digital wallet token. Allowable Values: 0-99
token_service_provider.token_eligibility_decision string Conditionally returned	Digital wallet’s decision as to whether the digital wallet token should be provisioned. Allowable Values: `DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN`
token_service_provider.token_expiration string Conditionally returned	Expiration date of the digital wallet token. Allowable Values: Format: MMyy
token_service_provider.token_pan string Conditionally returned	Primary account number (PAN) of the digital wallet token. Allowable Values: 16 char max
token_service_provider.token_reference_id string Conditionally returned	Unique identifier of the digital wallet token within the card network. Allowable Values: Existing Token Reference ID
token_service_provider.token_requestor_id string Conditionally returned	Unique numerical identifier of the token requestor within the card network. These ID numbers map to `token_requestor_name` field values as follows: Mastercard - 50110030273 – `APPLE_PAY` - 50120834693 – `ANDROID_PAY` - 50139059239 – `SAMSUNG_PAY` Visa - 40010030273 – `APPLE_PAY` - 40010075001 – `ANDROID_PAY` - 40010043095 – `SAMSUNG_PAY` - 40010075196 – `MICROSOFT_PAY` - 40010075338 – `VISA_CHECKOUT` - 40010075449 – `FACEBOOK` - 40010075839 – `NETFLIX` - 40010077056 – `FITBIT_PAY` - 40010069887 – `GARMIN_PAY` Allowable Values: 11 char max Example Values: - Mastercard – 50110030273, 50120834693, 50139059239 - Visa – 40010030273, 40010075001, 40010075338, 40010075449, 40010075839, 40010043095
token_service_provider.token_requestor_name string Conditionally returned	Name of the token requestor within the card network. NOTE: The list of example values for this field is maintained by the card networks and is subject to change. Allowable Values: 255 char max Example Values: - Mastercard – `APPLE_PAY`, `ANDROID_PAY`, `SAMSUNG_PAY` - Visa – `APPLE_PAY`, `ANDROID_PAY`, `SAMSUNG_PAY`, `MICROSOFT_PAY`, `VISA_CHECKOUT`, `FACEBOOK`, `NETFLIX`, `FITBIT_PAY`, `GARMIN_PAY`
token_service_provider.token_score string Conditionally returned	Token score assigned by the digital wallet. Allowable Values: 25 char max
token_service_provider.token_type string Conditionally returned	Type of the digital wallet token. Allowable Values: `MERCHANT_CARD_ON_FILE`, `DEVICE_SECURE_ELEMENT`, `DEVICE_CLOUD_BASED`, `ECOMMERCE_DIGITAL_WALLET`
transaction_device object Conditionally returned	Contains information about the device used in the transaction to enhance the risk decisioning process. Use this data to improve fraud prevention and dispute resolution. Allowable Values: `binding_id`, `ip_address`, `location`, `phone_number`
transaction_device.binding_id string Conditionally returned	Unique identifier of the data component bound to the credential. Allowable Values: 48 char max
transaction_device.ip_address string Conditionally returned	IP address of the device. The presence of the IP address helps determine if the transaction was initiated from an unusual network, helping establish a pattern of safe device usage that further confirms the authenticity of the consumer who initiated the transaction. Allowable Values: IP address format, 39 char max
transaction_device.location string Conditionally returned	Geographic coordinates of the device. Contains the latitude and longitude of the device used when the cardholder was authenticated during checkout. This field helps to determine if the transaction was initiated from an unexpected location. Allowable Values: Latitude and longitude in `DDD.DD/DDD.DD` format.
transaction_device.phone_number string Conditionally returned	Telephone number of the device. Contains the phone number that was used to authenticate the consumer during checkout, or the consumer’s preferred phone number. The presence of the phone number helps establish the consumer’s authenticity when matching the phone number provided during checkout to a list of known phone numbers for the consumer. Allowable Values: 15 char max
user object Conditionally returned	Contains information about a cardholder. Allowable Values: `account_holder_group_token`, `active`, `address1`, `address2`, `authentication`, `birth_date`, `birth_place`, `business_token`, `city`, `company`, `corporate_card_holder`, `country`, `created_time`, `email`, `first_name`, `gender`, `honorific`, `id_card_expiration_date`, `id_card_number`, `identifications`, `ip_address`, `last_modified_time`, `last_name`, `metadata`, `middle_name`, `nationality`, `notes`, `parent_token`, `passport_expiration_date`, `passport_number`, `password`, `phone`, `postal_code`, `ssn`, `state`, `status`, `title`, `token`, `uses_parent_account`, `zip`
user.account_holder_group_token string Conditionally returned	Associates the specified account holder group with the cardholder. Allowable Values: 36 char max
user.active boolean Conditionally returned	Specifies if the cardholder is in the `ACTIVE` state on the Marqeta platform. Allowable Values: `true`, `false`
user.address1 string Conditionally returned	Cardholder’s address. Allowable Values: 255 char max
user.address2 string Conditionally returned	Additional address information for the cardholder. Allowable Values: 255 char max
user.authentication object Conditionally returned	Contains the cardholder’s email address and password information. Allowable Values: `email_verified`, `email_verified_time`, `last_password_update_channel`, `last_password_update_time`
user.authentication.email_verified boolean Conditionally returned	Specifies whether the email address has been verified. Allowable Values: `true`, `false`
user.authentication.email_verified_time datetime Conditionally returned	Date and time when the email address was verified. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
user.authentication.last_password_update_channel string Conditionally returned	Specifies the channel through which the password was last changed. Allowable Values: `USER_CHANGE`, `USER_RESET`
user.authentication.last_password_update_time datetime Conditionally returned	Date and time when the password was last changed. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
user.birth_date string Conditionally returned	Cardholder’s date of birth. Allowable Values: Format: yyyy-MM-dd
user.birth_place string Conditionally returned	Country where the cardholder was born. Allowable Values: 255 char max ISO 3166 two-character country codes. For example, the country code for the United States is `US`. The ISO maintains the full list of ISO-3166 country codes.
user.business_token string Conditionally returned	Unique identifier of the business resource. Allowable Values: Existing business resource token
user.city string Conditionally returned	City where the cardholder resides. Allowable Values: 40 char max
user.company string Conditionally returned	Company name. Allowable Values: 255 char max
user.corporate_card_holder boolean Conditionally returned	Specifies if the cardholder holds a corporate card. Allowable Values: `true`, `false`
user.country string Conditionally returned	Country where the cardholder resides. Allowable Values: 40 char max
user.created_time datetime Returned	Date and time when the resource was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
user.email string Conditionally returned	Valid email address of the cardholder. Allowable Values: 1–255 chars
user.first_name string Conditionally returned	Cardholder’s first name. Allowable Values: 40 char max
user.gender string Conditionally returned	Gender of the cardholder. Allowable Values: `F`, `M`
user.honorific string Conditionally returned	Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on. Allowable Values: 10 char max
user.id_card_expiration_date string Conditionally returned	Expiration date of the cardholder’s identification. Allowable Values: Format: yyyy-MM-dd
user.id_card_number string Conditionally returned	Cardholder’s identification card number. Allowable Values: 255 char max
user.identifications array of objects Conditionally returned	One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more `identifications` objects
user.identifications[].expiration_date string Conditionally returned	Expiration date of the identification, if applicable. Allowable Values: Format: yyyy-MM-dd
user.identifications[].type string Conditionally returned	Type of identification. Allowable Values: `SSN`, `TIN`, `SIN`, `NIN`, `PASSPORT_NUMBER`, `DRIVERS_LICENSE`, `BUSINESS_NUMBER`, `BUSINESS_TAX_ID`, `TAXPAYER_REFERENCE`
user.identifications[].value string Conditionally returned	Number associated with the identification. Allowable Values: 255 char max
user.ip_address string Conditionally returned	Cardholder’s IP address. Allowable Values: 39 char max
user.last_modified_time datetime Returned	Date and time when the resource was last updated, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
user.last_name string Conditionally returned	Cardholder’s last name. Allowable Values: 40 char max
user.metadata object Conditionally returned	Associates any additional metadata you provide with the cardholder. Allowable Values: You can define the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"`
user.middle_name string Conditionally returned	Cardholder’s middle name. Allowable Values: 40 char max
user.nationality string Conditionally returned	Cardholder’s nationality. Allowable Values: 255 char max
user.notes string Conditionally returned	Any additional information pertaining to the cardholder. Allowable Values: 255 char max
user.parent_token string Conditionally returned	Unique identifier of the parent user or business resource. Allowable Values: 1–36 chars
user.passport_expiration_date string Conditionally returned	Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd
user.passport_number string Conditionally returned	Cardholder’s passport number. Allowable Values: 40 char max
user.password string Conditionally returned	Password to the cardholder’s user account on the Marqeta platform. Allowable Values: 1–255 chars
user.phone string Conditionally returned	Cardholder’s telephone number. Allowable Values: 255 char max
user.postal_code string Conditionally returned	Postal code of the cardholder’s address. Allowable Values: 10 char max
user.ssn string Conditionally returned	Cardholder’s Social Security Number (SSN). Allowable Values: Nine digits only, no delimiters.
user.state string Conditionally returned	State or province where the cardholder resides. Allowable Values: 2 char max
user.status string Conditionally returned	Specifies the status of the cardholder on the Marqeta platform. Allowable Values: `UNVERIFIED`, `LIMITED`, `ACTIVE`, `SUSPENDED`, `CLOSED`
user.title string Conditionally returned	Professional title of the cardholder, such as Chief Comptroller. Allowable Values: 255 char max
user.token string Conditionally returned	Unique identifier of the cardholder. Allowable Values: 1–36 chars
user.uses_parent_account boolean Conditionally returned	Indicates whether the child shares balances with the parent (`true`), or the child’s balances are independent of the parent (`false`). Allowable Values: `true`, `false`
user.zip string Conditionally returned	United States ZIP code of the cardholder’s address. Allowable Values: 10 char max
wallet_provider_profile object Conditionally returned	Contains information held and provided by the digital wallet provider. Allowable Values: `account`, `device_score`, `pan_source`, `reason_code`, `recommendation_reasons`, `risk_assessment`
wallet_provider_profile.account object Conditionally returned	Contains information related to the cardholder and provided by the digital wallet provider. Allowable Values: `email_address`, `id`, `score`
wallet_provider_profile.account.email_address string Conditionally returned	Digital wallet provider’s email address for the cardholder. Allowable Values: 255 char max
wallet_provider_profile.account.id string Conditionally returned	Digital wallet provider’s identity number for the cardholder. Allowable Values: 20 char max
wallet_provider_profile.account.score string Conditionally returned	Score from the digital wallet provider. Allowable Values: 50 char max
wallet_provider_profile.device_score string Conditionally returned	Score from the device. Allowable Values: 50 char max
wallet_provider_profile.pan_source string Conditionally returned	Source from which the digital wallet provider obtained the card primary account number (PAN). Allowable Values: `KEY_ENTERED`, `ON_FILE`, `MOBILE_BANKING_APP`
wallet_provider_profile.reason_code string Conditionally returned	Reason for the wallet provider’s provisioning decision. - 01 – Cardholder’s wallet account is too new relative to launch. - 02 – Cardholder’s wallet account is too new relative to provisioning request. - 03 – Cardholder’s wallet account/card pair is newer than date threshold. - 04 – Changes made to account data within the account threshold. - 05 – Suspicious transactions linked to this account. - 06 – Account has not had activity in the last year. - 07 – Suspended cards in the secure element. - 08 – Device was put in lost mode in the last seven days for longer than the duration threshold. - 09 – The number of provisioning attempts on this device in 24 hours exceeds threshold. - 0A – There have been more than the threshold number of different cards attempted at provisioning to this phone in 24 hours. - 0B – The card provisioning attempt contains a distinct name in excess of the threshold. - 0C – The device score is less than 3. - 0D – The account score is less than 4. - 0E – Device provisioning location outside of the cardholder’s wallet account home country. - 0G – Suspect fraud. Allowable Values: 01, 02, 03, 04, 05, 06, 07, 08, 09, 0A, 0B, 0C, 0D, 0E, 0G
wallet_provider_profile.recommendation_reasons array of strings Conditionally returned	Array of recommendation reasons from the digital wallet provider. Allowable Values: Valid array of one or more recommendation reasons
wallet_provider_profile.risk_assessment object Conditionally returned	Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token. Allowable Values: `score`, `version`
wallet_provider_profile.risk_assessment.score string Conditionally returned	Wallet provider’s decision as to whether the digital wallet token should be provisioned. Allowable Values: `DECISION_RED`, `DECISION_YELLOW`, `DECISION_GREEN`
wallet_provider_profile.risk_assessment.version string Conditionally returned	Wallet provider’s risk assessment version. Allowable Values: Version information, as provided by the wallet provider

Sample response body

JSON

{
  "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_pan": "my_token_pan_6792",
    "token_score": "02",
    "token_eligibility_decision": "DECISION_GREEN"
  },
  "device": {
    "type": "MOBILE_PHONE",
    "language_code": "eng",
    "device_id": "my_device_id_9575",
    "phone_number": "12345678900",
    "name": "Phone Name",
    "location": "+37.81/-122.26",
    "ip_address": "x.x.x.x"
  },
  "wallet_provider_profile": {
    "account": {
      "score": "05"
    },
    "risk_assessment": {
      "score": "DECISION_YELLOW",
      "version": "0001.00"
    },
    "device_score": "03",
    "pan_source": "KEY_ENTERED"
  },
  "address_verification": {
    "name": "Address Verification Name",
    "street_address": "223 Elm Street",
    "postal_code": "94703"
  }
}

Create request for Apple Wallet web push provisioning

Action: POST Endpoint: /digitalwallets/wpp/applePayJWT Use this endpoint to add a card to Apple Wallet via a web application.

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

Request body

Fields	Description
card_token string Required	Unique identifier of the card resource. Allowable Values: Existing card token
req-sys-id string Required	Identifier generated by the card program. These identifiers are used for troubleshooting requests between the card program and Marqeta. Allowable Values: 36 char max

Response body

Fields	Description
jws object Returned	Object containing JSON Web Signature (JWS) data. Allowable Values: Existing JWS object
jws.header object Returned	Contains header data for the JWS object. Allowable Values: Existing `kid` string
jws.header.kid string Returned	Unique identifier of the JSON Web Signature (JWS) public key of the key pair used to generate the signature. Allowable Values: Any value
jws.protected string Returned	Contains header parameters that are integrity-protected by the JSON Web Signature (JWS). Allowable Values: Any value
jws.payload string Returned	JSON Web Signature (JWS) message payload. Allowable Values: Any value
jws.signature string Returned	The JSON Web Signature (JWS). Allowable Values: Any value
state string Returned	Unique state associated with the digital wallet token. The Marqeta platform returns a universally unique identifier (UUID) in this field. Allowable Values: 255 char

Create request for Google Wallet web push provisioning

Action: POST Endpoint: /digitalwallets/wpp/googlePayPushProvisioningNotification Use this endpoint to add a card to Google Wallet via a web application. This endpoint does not return a payload in response to a request. Instead, a successful call will return a response code only.

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

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`

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.

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

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`

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
}

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 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

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..."
  }
}

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.

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

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`

Response body

Fields	Description
is_eligible boolean Conditionally returned	Indicates whether the `bin_prefix` is eligible for Click to Pay. - `true`: The `bin_prefix` is eligible for Click to Pay. - `false`: The `bin_prefix` is not eligible for Click to Pay. Allowable Values: `true`, `false`
image_assets array of objects Conditionally returned	List of image assets for the Click to Pay logo if `include_asset` is set to `true` in the request. Allowable Values: A valid array of `image_asset` objects
image_assets[].type string Conditionally returned	Type of media. Specified as Multipurpose Internet Mail Extension (MIME). Supported media types include: - application/pdf - image/png - image/svg+xml - text/plain - text/html Allowable Values: 32 char max
image_assets[].data string Conditionally returned	Media data content. Allowable Values: Base64-encoded media data
image_assets[].height string Conditionally returned	Height of non-SVG image asset. Specified in pixels. Allowable Values: 6 char max
image_assets[].width string Conditionally returned	Width of non-SVG image asset. Specified in pixels. Allowable Values: 6 char max

Sample response body

JSON

{
  "is_eligible": true,
  "image_assets": [
    {
      "media_content": {
        "type": "image/png",
        "data": "iVBORw0KGgoAAAANSUhEUgAAAMAAAADACAYAAABS3GwHAAAAAXNSR0IArs4c6... (truncated for readability)",
        "height": "192px",
        "width": "192px"
      }
    },
    {
      "media_content": {
        "type": "image/svg+xml",
        "data": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyB3... (truncated for readability)",
        "height": "192px",
        "width": "192px"
      }
    }
  ]
}

Enroll a card to Click to Pay for Mastercard

Action: POST Endpoint: /digitalwallets/clicktopay/mastercard/enroll Use this endpoint to enroll a card in Click to Pay for Mastercard. For more information about this ecommerce checkout solution, see Click to Pay.

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

Request body

Fields	Description
card_token string Required	Unique identifier of the card resource. Allowable Values: 1–36 chars Existing card token
user_token string Required	Unique identifier of the cardholder. Allowable Values: 1–36 chars
user_details array of objects Required	User’s email address and mobile phone number with country code. Allowable Values: A valid array of `user_details` objects
user_details[].email_address string Required	User’s email address. Allowable Values: 255 char max
user_details[].mobile_number object Required	User’s mobile phone number and country code. Allowable Values: `country_code`, `phone_number`
user_details[].mobile_number.country_code string Required	User’s mobile phone number country code only. Allowable Values: 255 char max
user_details[].mobile_number.phone_number string Required	User’s mobile phone number without country code. Allowable Values: 255 char max
locale_country string Required	The user-provided country code. The ISO 3166 country code is a two-letter country code that represents a country. For example, the numeric code for the United States is `US`. The ISO maintains the ISO 3166 country codes. Allowable Values: 2 chars
locale_language string Required	The user-provided language choice. The ISO 639-2 language code is a two-letter country code that represents a language. The ISO maintains the ISO 639-2 language codes. Allowable Values: 2 chars
callback_url string Optional	The URL to which the Click to Pay request status is sent via webhooks. Allowable Values: A valid URL
callback_authentication_type string Optional	The type of authentication required for the callback URL. - `OAUTH_BEARER_TOKEN`: OAuth bearer token for the callback URL. - `BASIC_AUTH`: Basic auth username and password for the callback URL. Allowable Values: `OAUTH_BEARER_TOKEN`, `BASIC_AUTH`
oauth_bearer_token string Optional	OAuth bearer token to access your callback URL if the `callback_authentication_type` is `OAUTH_BEARER_TOKEN`. Allowable Values: A bearer token that can be used to authenticate the callback API on the receiving end
callback_secret_for_signature string Optional	Randomly chosen string used for implementing HMAC-SHA1. HMAC-SHA1 provides an added layer of security by authenticating the message and validating message integrity. Using this functionality requires that your callback endpoint verify the message signature. For information about implementing this functionality, see Signature Verification. Allowable Values: 20–50 chars - Must contain at least one numeral - Must contain at least one lowercase letter - Must contain at least one uppercase letter - Must contain at least one of these symbols: + `@` `#` `$` `%` `!` `^` `&` `*` `(` `)` + `\` `_` `+` `~` `-` `=` `[` `]` `{` `}` + `,` `;` `:` `'` `"` `.` `/` `<` `>` `?` ```
basic_auth_username string Optional	Basic auth username to access your callback URL if authentication type is basic. If authentication type is basic, both username and password are required. Allowable Values: 1–50 chars
basic_auth_password string Optional	Basic auth password to access your callback URL if authentication type is basic. If authentication type is basic, both username and password are required. Allowable Values: 20–50 chars - Must contain at least one numeral - Must contain at least one lowercase letter - Must contain at least one uppercase letter - Must contain at least one of these symbols: `@` `#` `$` `%` `!` `^` `&` `*` `(` `)` `\` `_` `+` `~` `-` `=` `[` `]` `{` `}` `,` `;` `:` `'` `"` `.` `/` `<` `>` `?`

Sample request body

JSON

{
  "card_token": "my_card_token_1234",
  "user_token": "my_user_token_1234",
  "user_details": [
    {
      "email_address": "test@test.com",
      "mobile_number": {
        "country_code": "44",
        "phone_number": "1234567890"
      }
    }
  ],
  "locale_country": "US",
  "locale_language": "en"
}

Response body

Fields	Description
token string Conditionally returned	Unique identifier of the Click to Pay request. Allowable Values: 1–36 chars

Sample response body

JSON

{
  "token": "my_token_0000"
}

Retrieve Click to Pay for Mastercard enrollment status

Action: GET Endpoint: /digitalwallets/clicktopay/mastercard/status/{token} Use this endpoint to return the status of a specific Click to Pay for Mastercard request. For more information about this ecommerce checkout solution, see Click to Pay.

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

URL path parameters

Fields	Description
token string Required	Unique identifier of the Click to Pay request. Allowable Values: Existing Click to Pay request token

Response body

Fields	Description
token string Conditionally returned	Unique identifier of the Click to Pay request, used to track the status of the request. Allowable Values: 36 char max
status string Conditionally returned	The status of the Click to Pay request. - `SUCCESS`: The Click to Pay request was successful. - `FAILED`: The Click to Pay request failed. - `RECEIVED`: The Click to Pay request was received. Allowable Values: `SUCCESS`, `FAILED`, `RECEIVED`
token_reference_id string Conditionally returned	Unique identifier of the digital wallet token within the card network. Allowable Values: 255 char max

Sample response body

JSON

{
  "token": "my_token_0000",
  "status": "SUCCESS",
  "token_reference_id": "my_token_reference_id_1600"
}

Enroll a cardholder to Click to Pay for Visa

Action: POST Endpoint: /digitalwallets/clicktopay/visa/enroll Use this endpoint to enroll a new cardholder in Click to Pay for Visa. For more information about this ecommerce checkout solution, see Click to Pay.

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

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. Allowable Values: 2–5 chars
user.country string Required	ISO 3166-1 alpha-3 country code. Allowable Values: 3 chars

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"
    }
  }
}

Response body

Fields	Description
requestTraceId string Returned	Unique identifier of the Visa Click to Pay request. Allowable Values: 1–36 chars

Sample response body

JSON

{
  "requestTraceId": "2b6f0cc904d137be2e1730235f5664094b83"
}

Enroll a card to Click to Pay for Visa

Action: POST Endpoint: /digitalwallets/clicktopay/visa/enrollcards Use this endpoint to enroll a new card for an existing cardholder in Click to Pay for Visa. For more information about this ecommerce checkout solution, see Click to Pay.

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

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
userToken string Required	Unique identifier of the cardholder. Allowable Values: 1–36 chars

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"
    }
  }
}

Response body

Fields	Description
requestTraceId string Returned	Unique identifier of the Visa Click to Pay request. Allowable Values: 1–36 chars

Sample response body

JSON

{
  "requestTraceId": "2b6f0cc904d137be2e1730235f5664094b83"
}

Retrieve user data for Click to Pay for Visa

Action: GET Endpoint: /digitalwallets/clicktopay/visa/getdata/{user_token} Use this endpoint to get user data for Click to Pay for Visa. For more information about this ecommerce checkout solution, see Click to Pay.

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

URL path parameters

Fields	Description
user_token string Required	Unique identifier of the cardholder. Allowable Values: Existing Visa Click To Pay User Token

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`

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"
          }
        ]
      }
    }
  ]
}

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.

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

Request body

Fields	Description
user object Required	User’s email address, mobile phone number without country code, first name, last name, locale, and country. Allowable Values: `userToken`, `email`, `phone`, `firstName`, `lastName`, `locale`, `country`
user.userToken string Required	Unique identifier of the cardholder. Allowable Values: 1–36 chars
user.email string Required	User’s email address. Allowable Values: 255 char max
user.phone string Required	User’s mobile phone number according to ITU-T E.164 (2010) number structure. NOTE: In the E.164 format, the ”+” sign is not included. Allowable Values: 1–16 chars
user.firstName string Required	User’s first name. Allowable Values: 1–35 chars
user.lastName string Required	User’s last name. Allowable Values: 1–35 chars
user.locale string Required	The user-provided language choice. The ISO 639-2 language code is a two-letter country code that represents a language. The ISO maintains the ISO 639-2 language codes. Allowable Values: 2–5 chars
user.country string Required	ISO 3166-1 alpha-3 country code. Allowable Values: 3 chars

Sample request body

JSON

{
  "user": {
    "userToken": "1234567890",
    "firstName": "John",
    "lastName": "Smith",
    "email": "example@email.com",
    "phone": "111-111-1111",
    "locale": "en_US",
    "country": "USA"
  }
}

Response body

Fields	Description
requestTraceId string Returned	Unique identifier of the Visa Click to Pay request. Allowable Values: 1–36 chars

Sample response body

JSON

{
  "requestTraceId": "2b6f0cc904d137be2e1730235f5664094b83"
}

Delete cardholder information for Click to Pay for Visa

Action: DELETE Endpoint: /digitalwallets/clicktopay/visa/users Use this endpoint to delete cardholder information for Click to Pay for Visa. For more information about this ecommerce checkout solution, see Click to Pay.

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

Request body

Fields	Description
userToken string Required	Unique identifier of the cardholder. Allowable Values: 1–36 chars

Sample request body

JSON

{
  "userToken": "1234567890"
}

Response body

Fields	Description
requestTraceId string Returned	Unique identifier of the Visa Click to Pay request. Allowable Values: 1–36 chars

Sample response body

JSON

{
  "requestTraceId": "2b6f0cc904d137be2e1730235f5664094b83"
}

Update card information for Click to Pay for Visa

Action: PUT Endpoint: /digitalwallets/clicktopay/visa/cards Use this endpoint to update card information for Click to Pay for Visa. For more information about this ecommerce checkout solution, see Click to Pay.

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

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
userToken string Required	Unique identifier of the cardholder. Allowable Values: 1–36 chars

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"
    }
  }
}

Response body

Fields	Description
requestTraceId string Returned	Unique identifier of the Visa Click to Pay request. Allowable Values: 1–36 chars

Sample response body

JSON

{
  "requestTraceId": "2b6f0cc904d137be2e1730235f5664094b83"
}

Delete card information for Click to Pay for Visa

Action: DELETE Endpoint: /digitalwallets/clicktopay/visa/cards/{card_token} Use this endpoint to delete card information for Click to Pay for Visa. For more information about this ecommerce checkout solution, see Click to Pay.

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

URL path parameters

Fields	Description
card_token string Required	Unique identifier of the cardholder. Allowable Values: 1–36 chars

Response body

Fields	Description
requestTraceId string Returned	Unique identifier of the Visa Click to Pay request. Allowable Values: 1–36 chars

Sample response body

JSON

{
  "requestTraceId": "2b6f0cc904d137be2e1730235f5664094b83"
}

Retrieve Click to Pay for Visa request status

Action: GET Endpoint: /digitalwallets/clicktopay/visa/status/{requestTraceId} Use this endpoint to return the status of a Click to Pay for Visa request. For more information about this ecommerce checkout solution, see Click to Pay.

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

URL path parameters

Fields	Description
requestTraceId string Required	Unique identifier of the Visa Click to Pay request. Allowable Values: 1–36 chars

Response body

Fields	Description
status string Returned	Status of the operation. Allowable Values: `IN_PROGRESS`, `COMPLETED`
consumerInformation object Conditionally returned	Consumer information. Allowable Values: Existing `consumerInformation` object
consumerInformation.externalConsumerID string Conditionally returned	External consumer ID. Allowable Values: 1–100 chars
consumerInformation.externalConsumerIDOwnerBID string Conditionally returned	Visa Business Identifier (BID) of the entity to which an External Consumer ID belongs. Allowable Values: 1–8 chars
details array of undefineds Conditionally returned	Additional status details of the operation. Allowable Values: Array of `details` object
details[].status string Returned	Status of the operation. Allowable Values: `SUCCESS`, `FAILED`
details[].intent object Returned	Intent of the Visa Click to Pay operation. Allowable Values: `type`, `value`
details[].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

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"
  }
}

Create a Visa Alias

Action: POST Endpoint: /digitalwallets/aliasdirectory/visa/aliases Use this endpoint to create a Visa Alias.

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

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. 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 (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`

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"
    }
  }
}

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

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"
    }
  ]
}

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.

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

URL path parameters

Fields	Description
aliasId string Required	Unique identifier of the Visa Alias. Allowable Values: Existing Visa Alias ID

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`

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"
}

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.

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

URL path parameters

Fields	Description
aliasId string Required	Unique identifier of the Visa Alias. Allowable Values: Existing Visa Alias ID

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`

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"
}

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.

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

URL path parameters

Fields	Description
aliasId string Required	Unique identifier of the Visa Alias. Allowable Values: Existing Visa Alias ID

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.

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

Request body

Fields	Description
aliasValue string Optional	Visa Alias value, which can be an email, a phone number, ID of an alias directory, or a payname. If a phone number is used for the Visa Alias, it must follow ITU-T E.164 (2010) number structure. NOTE: In the E.164 format, the ”+” sign is not included. Allowable Values: 1–128 chars

Sample request body

JSON

{
  "aliasValue": "my_alias_value_1234"
}

Response body

Fields	Description
id string Conditionally returned	UUID generated by Alias Directory, which identifies the Visa Alias. Allowable Values: 1–128 chars

Sample response body

JSON

{
  "id": "my_alias_id_1234"
}

Update alias status

Action: PUT Endpoint: /digitalwallets/aliasdirectory/visa/aliases/{aliasId}/status Use this endpoint to update the status of a Visa Alias.

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

URL path parameters

Fields	Description
aliasId string Required	Unique identifier of the Visa Alias. Allowable Values: Existing Visa Alias ID

Request body

Fields	Description
status string Optional	Status of the Visa Alias. Allowable Values: ACTIVE, DISABLED

Sample request body

JSON

{
  "status": "ACTIVE"
}

Create Visa Alias payment credential

Action: POST Endpoint: /digitalwallets/aliasdirectory/visa/aliases/{aliasId}/cards Use this endpoint to create a payment credential associated with a Visa Alias.

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

URL path parameters

Fields	Description
aliasId string Required	Unique identifier of the Visa Alias. Allowable Values: Existing Visa Alias ID

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. 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 (Alpha-3)
preferredFor array of strings Optional	Indicates if a payment credential is a preferred Receiving, Sending, or Paying account. Allowable Values: `RECEIVE`, `SEND`, `PAYING`

Sample request body

JSON

{
  "cardToken": "4111111145551142",
  "billingAddress": {
    "country": "USA",
    "streetName": "12",
    "city": "San Francisco",
    "postalCode": "94105",
    "addressLine1": "1000 Market Street",
    "buildingNumber": "56",
    "addressLine2": "Suite 101",
    "state": "CA",
    "minorSubdivisionCode": "CA"
  },
  "nameOnCard": "John Doe",
  "cardType": "Visa Platinum",
  "issuerName": "Bank A",
  "currencyCode": "USD",
  "preferredFor": [
    "RECEIVE",
    "SEND"
  ]
}

Response body

Fields	Description
id string Returned	UUID generated by Alias Directory, a utility used to identify the payment credential. Allowable Values: 36 char max
type string Returned	Indicates the type of payment credential. Allowable Values: `CARD`, `BANK`
externalId string Conditionally returned	External ID of the payment credential, which corresponds to Marqeta’s card token. Allowable Values: 1–100 chars

Sample response body

JSON

{
  "id": "a44c9553-e687-4f3c-b7e7-a4245d9f238e",
  "type": "CARD",
  "externalId": "63421837-d597-4f0f-89e4-930c1a7b9e85"
}

Retrieve a Visa Alias payment credentials

Action: GET Endpoint: /digitalwallets/aliasdirectory/visa/aliases/{aliasId}/cards Use this endpoint to retrieve a list of payment credentials associated with a Visa Alias.

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

URL path parameters

Fields	Description
aliasId string Required	Unique identifier of the Visa Alias. Allowable Values: Existing Visa Alias ID

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. 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 (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`

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"
  }
]

Retrieve payment credential

Action: GET Endpoint: /digitalwallets/aliasdirectory/visa/cards/{paymentCredentialId} Use this endpoint to retrieve an existing payment credential.

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

URL path parameters

Fields	Description
paymentCredentialId string Required	Unique identifier of an existing payment credential. Allowable Values: Existing payment credential ID

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. 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 (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`

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"
  }
]

Update payment credential

Action: PUT Endpoint: /digitalwallets/aliasdirectory/visa/cards/{paymentCredentialId} Use this endpoint to update an existing payment credential.

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

URL path parameters

Fields	Description
paymentCredentialId string Required	Unique identifier of an existing payment credential. Allowable Values: Existing payment credential ID

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. 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 (Alpha-3)
preferredFor array of strings Optional	Indicates if a payment credential is a preferred Receiving, Sending, or Paying account. Allowable Values: `RECEIVE`, `SEND`, `PAYING`

Sample request body

JSON

{
  "cardToken": "4111111145551142",
  "billingAddress": {
    "country": "USA",
    "streetName": "12",
    "city": "San Francisco",
    "postalCode": "94105",
    "addressLine1": "1000 Market Street",
    "buildingNumber": "56",
    "addressLine2": "Suite 101",
    "state": "CA",
    "minorSubdivisionCode": "CA"
  },
  "nameOnCard": "John Doe",
  "cardType": "Visa Platinum",
  "issuerName": "Bank A",
  "currencyCode": "USD",
  "preferredFor": [
    "RECEIVE",
    "SEND"
  ]
}

Delete an existing payment credential

Action: DELETE Endpoint: /digitalwallets/aliasdirectory/visa/cards/{paymentCredentialId} Use this endpoint to delete an existing payment credential.

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

URL path parameters

Fields	Description
paymentCredentialId string Required	Unique identifier of an existing payment credential. Allowable Values: Existing payment credential ID

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.

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

URL path parameters

Fields	Description
aliasId string Required	Unique identifier of the Visa Alias. Allowable Values: Existing Visa Alias ID

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

Sample request body

JSON

{
  "type": "EMAIL",
  "value": "1231231234"
}

Response body

Fields	Description
id string Returned	UUID generated by Alias Directory, which identifies the Visa Alias. Allowable Values: 1–36 chars

Sample response body

JSON

{
  "id": "my_alias_id_1234"
}

Delete an additional Visa Alias

Action: DELETE Endpoint: /digitalwallets/aliasdirectory/visa/additionalAliases/{additionalAliasId} Use this endpoint to delete an additional Visa Alias by its Visa Alias ID.

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

URL path parameters

Fields	Description
additionalAliasId string Required	Unique identifier of the additional Visa Aliases. Allowable Values: Existing additional Visa Alias ID

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.

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

Request body

Fields	Description
externalId string Required	External ID of the Visa Alias. Allowable Values: 1–100 chars
type string Required	Type of Visa Alias in the Alias Directory Service (ADS) profile. Visa supports phone and email as Visa Alias types that can be used in place of sensitive payment credentials. Allowable Values: `ALIAS`, `PAYMENT_CREDENTIAL`

Sample request body

JSON

{
  "externalId": "21267931-7975-4b61-be7a-86915883b2b4",
  "type": "ALIAS"
}

Response body

Fields	Description
associatedIds array of objects Returned	List of associated Visa Alias IDs. Allowable Values: `associatedIds`
associatedIds[].id string Conditionally returned	ID of the payment credential associated with the Visa Alias. Allowable Values: 1–64 chars
associatedIds[].type string Conditionally returned	Type of payment credential associated with the Visa Alias. Allowable Values: `ALIAS`, `PAYMENT_CREDENTIAL`
id string Conditionally returned	UUID generated by Alias Directory, which identifies the Visa Alias. Allowable Values: 1–36 chars

Sample response body

JSON

{
  "associatedIds": [
    {
      "id": "a44c9553-e687-4f3c-b7e7-a4245d9f238e",
      "type": "PAYMENT_CREDENTIAL"
    }
  ],
  "id": "e336c8c8-2945-4be3-af3e-951ec2d01219"
}

Create a report request

Action: POST Endpoint: /digitalwallets/aliasdirectory/visa/reports Use this endpoint to create a new report request.

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

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`

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"
}

Response body

Fields	Description
reportId string Conditionally returned	Unique identifier of the report. Allowable Values: 36 char max

Sample response body

JSON

{
  "reportId": "my_report_id_1234"
}

Retrieve report status by report ID

Action: GET Endpoint: /digitalwallets/aliasdirectory/visa/reports/{reportId} Use this endpoint to retrieve the status of a report by its report ID.

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

URL path parameters

Fields	Description
reportId string Required	Unique identifier of the report. Allowable Values: Existing report ID

Response body

Fields	Description
creationDateTime datetime Conditionally returned	The timestamp when the report was created in ISO UTC format YYYY-MM-DDThh:mm:ss.000Z Allowable Values: `YYYY-MM-DDThh:mm:ss.000Z`
dataClassification string Conditionally returned	Data classification of the report. Allowable Values: 1–36 chars
expirationDateTime datetime Conditionally returned	The timestamp after which the report won’t be available for download in ISO UTC format YYYY-MM-DDThh:mm:ss.000Z Allowable Values: `YYYY-MM-DDThh:mm:ss.000Z`
fileIds array of strings Conditionally returned	UUIDs of the files generated by the report. Allowable Values:
format string Conditionally returned	Format of the report. Allowable Values: 1–36 chars
id string Conditionally returned	UUID generated by Alias Directory, which identifies the report. Allowable Values: 1–36 chars
reportType string Conditionally returned	Indicates the type of report. Allowable Values: `PLATFORM_REQUESTS`, `DIRECTORY_STATUS`, `PAYMENT_CREDENTIAL_DETAILS`
status string Conditionally returned	Indicates the status of the report. Allowable Values: `CREATED`, `IN_PROGRESS`, `COMPLETED`

Sample response body

JSON

{
  "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"
}

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.

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

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

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

Sample response body

JSON

[
  {
    "programId": "baf85624-3cf6-4c52-b91f-b8f3493e7330",
    "statusCode": 200,
    "operationType": "resolveAlias",
    "operationsCount": 18,
    "originatorActorId": "012af73f-44d8-4c9c-bbee-628b07faae1c"
  }
]

Check for Visa Alias

Action: POST Endpoint: /digitalwallets/aliasdirectory/visa/aliases/inquiry Use this endpoint to check for available Visa Aliases for alias resolution. One or more Visa Aliases may be available.

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

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) 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

Sample request body

JSON

{
  "aliases": [
    "123456"
  ],
  "filters": [
    {
      "field": "DIRECTORY_NAME",
      "value": [
        "DIRECTORY_A",
        "DIRECTORY_B",
        "DIRECTORY_C"
      ]
    }
  ],
  "transactionDetails": {
    "currencyCode": "USD"
  },
  "userDetails": {
    "userName": "johndoe313"
  }
}

Response body

Fields	Description
summary object 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

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"
        ]
      }
    ]
  }
]

Resolve a Visa Alias

Action: POST Endpoint: /digitalwallets/aliasdirectory/visa/aliases/resolve Retrieve information about a Visa Alias and all the associated payment credentials.

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

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) 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

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"
  }
}

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. Allowable Values: 3 chars
paymentCredentials[].billingAddress.addressLine1 string Conditionally returned	Address line 1 of the billing address associated with the payment credential. Allowable Values: 99 char max
paymentCredentials[].billingAddress.addressLine2 string Conditionally returned	Address line 2 of the billing address associated with the payment credential. Allowable Values: 99 char max
paymentCredentials[].billingAddress.buildingNumber string Conditionally returned	Building number of the billing address associated with the payment credential. Allowable Values: 1–60 chars
paymentCredentials[].billingAddress.city string Conditionally returned	City of the billing address associated with the payment credential. Allowable Values: 1–35 chars
paymentCredentials[].billingAddress.minorSubdivision string Conditionally returned	Minor subdivision of the billing address associated with the payment credential. Allowable Values: 1–50 chars
paymentCredentials[].billingAddress.postalCode string Conditionally returned	Postal code of the billing address associated with the payment credential. Allowable Values: 1–16 chars
paymentCredentials[].billingAddress.state string Conditionally returned	State of the billing address associated with the payment credential. Allowable Values: 1–16 chars
paymentCredentials[].billingAddress.streetName string Conditionally returned	Street name of the billing address associated with the payment credential. Allowable Values: 1–60 chars
paymentCredentials[].type string Returned	Type of payment credential associated with the Visa Alias. Allowable Values: `CARD`
paymentCredentials[].accountNumberType string Conditionally returned	Type of account number associated with the payment credential. Allowable Values: `PAN`, `NIUBIZ`, `TOKEN`
paymentCredentials[].cardType string Conditionally returned	Type of card associated with the payment credential. Allowable Values: 1–70 chars
paymentCredentials[].createdOn datetime Conditionally returned	Date and time when the payment credential was created. Allowable Values: 24 chars Format: YYYY-MM-DDTHH:MM:SS.000Z
paymentCredentials[].currencyCode string Conditionally returned	Three-digit ISO 4217 currency code for the payment credential. Allowable Values: 3 chars Valid three-digit ISO 4217 currency code (Alpha-3)
paymentCredentials[].expirationDate string Conditionally returned	Expiration date of the card. Allowable Values: 7 chars Format: YYYY-MM
paymentCredentials[].externalId string Conditionally returned	External ID of the payment credential, which corresponds to Marqeta’s card token. Allowable Values: 1–100 chars
paymentCredentials[].id string Conditionally returned	Unique identifier of the payment credential generated by Alias Directory. Allowable Values: 1–36 chars
paymentCredentials[].issuerName string Conditionally returned	Name of the issuer of the payment credential. Allowable Values: 1–150 chars
paymentCredentials[].lastFourDigits string Conditionally returned	Last four digits of the card number. Allowable Values: 4 chars
paymentCredentials[].lastUpdatedOn datetime Conditionally returned	Date and time when the payment credential was last updated. Allowable Values: 24 chars Format: YYYY-MM-DDTHH:MM:SS.000Z
paymentCredentials[].nameOnCard string Conditionally returned	Name on the card associated with the payment credential. Allowable Values: 1–120 chars
paymentCredentials[].preferredFor array of objects Conditionally returned	Indicates if a payment credential is a preferred Receiving, Sending, or Paying account. This array is returned if you passed the `preferredFor` field when creating a Visa Alias or when adding a new payment credential to an existing Visa Alias. Allowable Values: A valid array of `preferredFor` objects
paymentCredentials[].preferredFor[].type string Returned	Type of operation associated with the payment credential. Allowable Values: `RECEIVE`, `SEND`, `PAY`
paymentCredentials[].preferredFor[].date 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`

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"
      }
    }
  }
]

Bulk Card Orders

Tokenization-as-a-Service

⌘I

​Create digital wallet token provisioning request for Apple Wallet

​Request body

​Sample request body

​Response body

​Sample response body

​Submit a post-tokenization authentication decision

​Request body

​Response body

​Create a digital wallet token provisioning request for Google Wallet as part of UPP

​Request body

​Sample request body

​Response body

​Sample response body

​Create digital wallet token provisioning request for Google Wallet

​Request body

​Sample request body

​Response body

​Sample response body

​Create digital wallet token provisioning request for Samsung Wallet

​Request body

​Response body

​Create digital wallet token provisioning request for XPay

​Request body

​Response body

​Create digital wallet token transition

​Request body

​Sample request body

​Response body

​Sample response body

​Error responses

​Sample error response body

​Retrieve digital wallet token transition

​URL path parameters

​URL query parameters

​Response body

​Sample response body

​List transitions for digital wallet token

​URL path parameters

​URL query parameters

​Response body

​Sample response body

​List digital wallet tokens

​URL query parameters

​Response body

​Retrieve digital wallet token

​URL path parameters

​Response body

​Sample response body

​List digital wallet tokens for card

​URL path parameters

​URL query parameters

​Response body

​Sample response body

​Retrieve digital wallet token PAN

​URL path parameters

​Response body

​Sample response body

​Create request for Apple Wallet web push provisioning

​Header parameter

​Request body

​Response body

​Create request for Google Wallet web push provisioning

​Header parameter

​Request body

​Create a request for Google Wallet web push provisioning (UPP)

​Header parameter

​Request body

​Sample request body

​Response body

​Sample response body

​Check eligibility for Click to Pay for Mastercard

​Header parameter

​URL query parameters

​Response body

​Sample response body

​Enroll a card to Click to Pay for Mastercard

​Header parameter

​Request body

​Sample request body

​Response body

Create digital wallet token provisioning request for Apple Wallet

Request body

Sample request body

Response body

Sample response body

Submit a post-tokenization authentication decision

Request body

Response body

Create a digital wallet token provisioning request for Google Wallet as part of UPP

Request body

Sample request body

Response body

Sample response body

Create digital wallet token provisioning request for Google Wallet

Request body

Sample request body

Response body

Sample response body

Create digital wallet token provisioning request for Samsung Wallet

Request body

Response body

Create digital wallet token provisioning request for XPay

Request body

Response body

Create digital wallet token transition

Request body

Sample request body

Response body

Sample response body

Error responses

Sample error response body

Retrieve digital wallet token transition

URL path parameters

URL query parameters

Response body

Sample response body

List transitions for digital wallet token

URL path parameters

URL query parameters

Response body

Sample response body

List digital wallet tokens

URL query parameters

Response body

Retrieve digital wallet token

URL path parameters

Response body

Sample response body

List digital wallet tokens for card

URL path parameters

URL query parameters

Response body

Sample response body

Retrieve digital wallet token PAN

URL path parameters

Response body

Sample response body

Create request for Apple Wallet web push provisioning

Header parameter

Request body

Response body

Create request for Google Wallet web push provisioning

Header parameter

Request body

Create a request for Google Wallet web push provisioning (UPP)

Header parameter

Request body

Sample request body

Response body

Sample response body

Check eligibility for Click to Pay for Mastercard

Header parameter

URL query parameters

Response body

Sample response body

Enroll a card to Click to Pay for Mastercard

Header parameter

Request body

Sample request body

Response body