Tokenization-as-a-Service

This feature is currently in beta and subject to change. It also requires additional activation steps. To learn more about the beta program for this feature and about activating it for your program, contact your Marqeta representative.

Marqeta offers tokenization as a service, allowing you to use Marqeta’s tokenization features even if Marqeta is not your issuer processor.

Use the /digitalwalletprovisionrequests endpoints to instantly issue new virtual cards and provision digital wallets.
Use the /digitalwallettokentransitions endpoint to create or retrieve digital wallet token transitions.
Use the /digitalwallettokens endpoint to retrieve digital wallet tokens by list, by card, or by individual token.
Use the /cardactions endpoint to transfer digital wallet tokens to new cards, or update the expiry date of a digital wallet token.
Use the /webhooks endpoint to send optional customer notifications for system events.

Create digital wallet provisioning request for Apple Wallet

Action: POST Endpoint: /digitalwalletprovisionrequests/applepay Use the /digitalwalletprovisionrequests/applepay endpoint to return card data for use in provisioning a digital wallet token into Apple Wallet. The returned card data is encrypted using the digital wallet provider’s encryption key, thereby reducing your Payment Card Industry (PCI) compliance overhead.

Header parameter

Fields	Description
req-sys-id string Optional	Random pseudo-unique identifier of a request, used for troubleshooting between multiple parties. Usually a globally unique identifier (GUID). Allowable Values: 1–36 chars
region string Optional	Region of the card requested for provisioning. Applicable to both physical and virtual cards. Allowable Values: `NAM`, `EMEA`, `APAC`
isVirtualCard boolean Optional	Header flag to identify the type of the card requested for provisioning. Value is `true` for virtual cards, `false` for physical cards. Allowable Values: Example: `true`

Request body

Fields	Description
encrypted_card_data object Required	Encrypted data object. This object is first encrypted using the recipient’s public key and sent in JSON Web Encryption (JWE) format and then signed using the sender’s private key using JSON Web Signature (JWS). It represents the decrypted format. Allowable Values: `card_token`, `card_type`, `cardholder_info`, `expiration`, `metadata`, `primary_account_number`
encrypted_card_data.expiration object Required	Specifies the expiry date for the card. Allowable Values: `month`, `year`
encrypted_card_data.expiration.month string Required	Specifies the expiry month for the card in MM format. `01`, for example. Allowable Values: Format: MM
encrypted_card_data.expiration.year string Required	Specifies the expiry year for the card in yyyy format. `2024`, for example. Allowable Values: Format: yyyy
encrypted_card_data.card_token string Optional	Unique identifier of the card. Allowable Values: 1–36 chars
encrypted_card_data.primary_account_number string Required	Account number of the card being tokenized. Allowable Values: 12–19 chars
encrypted_card_data.card_type string Optional	Specifies the type of card. This field is required for Samsung Wallet. Allowable Values: `CREDIT`, `DEBIT`
encrypted_card_data.cardholder_info object Optional	Contains personal information about the cardholder. Allowable Values: `cardholder_address`, `email_address`, `first_name`, `last_name`, `phone_number`
encrypted_card_data.cardholder_info.first_name string Optional	First or given name of the cardholder. Allowable Values: 40 char max
encrypted_card_data.cardholder_info.last_name string Optional	Last or family name of the cardholder. Allowable Values: 40 char max
encrypted_card_data.cardholder_info.cardholder_address object Optional	Specifies the cardholder’s address. Allowable Values: `address_line_1`, `address_line_2`, `city`, `country_code`, `postal_code`, `state`
encrypted_card_data.cardholder_info.cardholder_address.address_line_1 string Required	Street address of the cardholder. Allowable Values: 1–255 chars
encrypted_card_data.cardholder_info.cardholder_address.address_line_2 string Optional	Additional address information for the cardholder, such as a suite, floor, room, PO Box or apartment number. `Suite 600`, for example. Allowable Values: 255 char max
encrypted_card_data.cardholder_info.cardholder_address.postal_code string Required	Postal code of the cardholder. Allowable Values: 1–50 chars
encrypted_card_data.cardholder_info.cardholder_address.city string Optional	City of the cardholder. Allowable Values: 40 char max
encrypted_card_data.cardholder_info.cardholder_address.state string Optional	State or province code associated with the cardholder’s address. Allowable Values: 3 char max
encrypted_card_data.cardholder_info.cardholder_address.country_code string Optional	Two-character ISO 3166-1 alpha-2 country code. `US`, for example. Allowable Values: 2 char max
encrypted_card_data.cardholder_info.email_address string Optional	Email address of the cardholder. Allowable Values: 255 char max
encrypted_card_data.cardholder_info.phone_number string Optional	Phone number of the cardholder. This number is used when Marqeta performs step-up authentication on your behalf. Allowable Values: 255 char max
encrypted_card_data.metadata array of objects Optional	Additional metadata related to the card details object. Allowable Values: Valid array of card details metadata objects
encrypted_card_data.metadata[].name string Required	Specifies the metadata attribute name, such as `CARD_ART_ID`, `MAX_TOKENS_PER_CARD`, and so on. Allowable Values: 255 char max
encrypted_card_data.metadata[].value string Required	Specifies the value of the metadata attribute. Allowable Values: 255 char max
card_token string Optional	Unique identifier of the card. Allowable Values: 1–36 chars
device_type string Optional	Specifies the type of device. Allowable Values: `APPLIANCE`, `GAMING_DEVICE`, `LAPTOP`, `MOBILE_PHONE`, `MOBILE_PHONE_OR_TABLET`, `PERSONAL_COMPUTER`, `TABLET`, `UNKNOWN`, `UNRECOGNIZED`, `VEHICLE`, `WATCH`
provisioning_app_version string Optional	Specifies the version of the application making the provisioning request. This field is used for debugging and fraud prevention. Allowable Values: 50 char max
certificates array of strings Required	Leaf and sub-CA certificates provided by Apple. Base 64 encoded. The first element of the array should be the leaf certificate, followed by the sub-CA. Allowable Values: 1–8192 chars
nonce string Required	One-time-use nonce provided by Apple for security purposes. Allowable Values: 1–32 chars
nonce_signature string Required	Apple-provided signature to the nonce. Allowable Values: 1–512 chars

Sample request body

Sample Apple Pay request

JSON

{
  "encrypted_card_data": {
    "expiration": {
      "month": "01",
      "year": "2025"
    },
    "card_token": "card-token-811",
    "primary_account_number": "4111111111111111",
    "cardholder_info": {
      "first_name": "Jane",
      "last_name": "Liu",
      "cardholder_address": {
        "city": "Oakland",
        "state": "CA",
        "address_line_1": "180 Grand Ave",
        "address_line_2": "Floor 6",
        "postal_code": "94612",
        "country_code": "US"
      },
      "email_address": "marqetaTest@marqeta.com",
      "phone_number": "1234567890"
    }
  },
  "nonce": "tKVkWRmUTaUiE3zO",
  "certificates": [
    "MIID/DCCA6OgAwIBAgIIRBkEefDVkQ0wCgYIKoZIzj....",
    "MIIC9zCCAnygAwIBAgIIb+/Y9emjp+4wCgYIKoZIzj...."
  ],
  "nonce_signature": "rcQ+z8FCP+jKkgRJ",
  "provisioning_app_version": "2.13.7"
}

Response body

Fields	Description
created_time datetime Returned	Date and time when the resource was created, in UTC. Allowable Values: date-time Format: yyyy-MM-ddThh:mm:ssZ
last_modified_time datetime Returned	Date and time when the resource was created, in UTC. Allowable Values: date-time Format: yyyy-MM-ddThh:mm:ssZ
card_token string Conditionally returned	Unique identifier of the card. Allowable Values: 1–36 chars
encrypted_pass_data string Returned	This object is encrypted with a shared key derived from the Apple Public Certificates and the generated ephemeral private key. This is binary data, but is presented here in base64 format. Do not persist this data. Because the scheme and contents could change, they are only subject to the `maxLength` limit of the NSData object, which is eight exabytes. For more information, see https://developer.apple.com/documentation/passkit/pkaddpaymentpassrequest/1615926-encryptedpassdata. Allowable Values: 1–1000000 chars
activation_data string Returned	Cryptographic one-time passcode (OTP) conforming to the payment network operator or service provider specifications. This is binary data, but is presented here in base64 format and has no practical max length. For more information, see https://developer.apple.com/documentation/passkit/pkaddpaymentpassrequest/1615914-activationdata. Allowable Values: 1–1000000 chars
ephemeral_public_key string Returned	Ephemeral public key used for the provisioning attempt. This is binary data, but is presented here in base64 format and has no practical max length. For more information, see https://developer.apple.com/documentation/passkit/pkaddpaymentpassrequest/1615952-ephemeralpublickey. Allowable Values: 1–1000000 chars

Sample response body

Sample Apple Pay response

JSON

{
  "created_time": "2026-07-08T16:37:28Z",
  "last_modified_time": "2026-07-08T16:37:28Z",
  "card_token": "card-token-9",
  "encrypted_pass_data": "UnYokfsEG5fQbKPy+4UJ3BF5N0D....",
  "activation_data": "TUJQQUMtMS1GSy03NDgwNTIuMS0tVER....",
  "ephemeral_public_key": "BCJ++11ucFSG7Z+ZECshFHSFpA...."
}

Create digital wallet provisioning request for Google Wallet

Action: POST Endpoint: /digitalwalletprovisionrequests/googlepay Use the /digitalwalletprovisionrequests/googlepay endpoint to return card data for use in provisioning a digital wallet token into Google Wallet. The returned card data is encrypted using the digital wallet provider’s encryption key, thereby reducing your Payment Card Industry (PCI) compliance overhead.

Header parameter

Fields	Description
req-sys-id string Optional	Random pseudo-unique identifier of a request, used for troubleshooting between multiple parties. Usually a globally unique identifier (GUID). Allowable Values: 1–36 chars
region string Optional	Region of the card requested for provisioning. Applicable to both physical and virtual cards. Allowable Values: `NAM`, `EMEA`, `APAC`
isVirtualCard boolean Optional	Header flag to identify the type of the card requested for provisioning. Value is `true` for virtual cards, `false` for physical cards. Allowable Values: Example: `true`

Request body

Fields	Description
encrypted_card_data object Required	Encrypted data object. This object is first encrypted using the recipient’s public key and sent in JSON Web Encryption (JWE) format and then signed using the sender’s private key using JSON Web Signature (JWS). It represents the decrypted format. Allowable Values: `card_token`, `card_type`, `cardholder_info`, `expiration`, `metadata`, `primary_account_number`
encrypted_card_data.expiration object Required	Specifies the expiry date for the card. Allowable Values: `month`, `year`
encrypted_card_data.expiration.month string Required	Specifies the expiry month for the card in MM format. `01`, for example. Allowable Values: Format: MM
encrypted_card_data.expiration.year string Required	Specifies the expiry year for the card in yyyy format. `2024`, for example. Allowable Values: Format: yyyy
encrypted_card_data.card_token string Optional	Unique identifier of the card. Allowable Values: 1–36 chars
encrypted_card_data.primary_account_number string Required	Account number of the card being tokenized. Allowable Values: 12–19 chars
encrypted_card_data.card_type string Optional	Specifies the type of card. This field is required for Samsung Wallet. Allowable Values: `CREDIT`, `DEBIT`
encrypted_card_data.cardholder_info object Optional	Contains personal information about the cardholder. Allowable Values: `cardholder_address`, `email_address`, `first_name`, `last_name`, `phone_number`
encrypted_card_data.cardholder_info.first_name string Optional	First or given name of the cardholder. Allowable Values: 40 char max
encrypted_card_data.cardholder_info.last_name string Optional	Last or family name of the cardholder. Allowable Values: 40 char max
encrypted_card_data.cardholder_info.cardholder_address object Optional	Specifies the cardholder’s address. Allowable Values: `address_line_1`, `address_line_2`, `city`, `country_code`, `postal_code`, `state`
encrypted_card_data.cardholder_info.cardholder_address.address_line_1 string Required	Street address of the cardholder. Allowable Values: 1–255 chars
encrypted_card_data.cardholder_info.cardholder_address.address_line_2 string Optional	Additional address information for the cardholder, such as a suite, floor, room, PO Box or apartment number. `Suite 600`, for example. Allowable Values: 255 char max
encrypted_card_data.cardholder_info.cardholder_address.postal_code string Required	Postal code of the cardholder. Allowable Values: 1–50 chars
encrypted_card_data.cardholder_info.cardholder_address.city string Optional	City of the cardholder. Allowable Values: 40 char max
encrypted_card_data.cardholder_info.cardholder_address.state string Optional	State or province code associated with the cardholder’s address. Allowable Values: 3 char max
encrypted_card_data.cardholder_info.cardholder_address.country_code string Optional	Two-character ISO 3166-1 alpha-2 country code. `US`, for example. Allowable Values: 2 char max
encrypted_card_data.cardholder_info.email_address string Optional	Email address of the cardholder. Allowable Values: 255 char max
encrypted_card_data.cardholder_info.phone_number string Optional	Phone number of the cardholder. This number is used when Marqeta performs step-up authentication on your behalf. Allowable Values: 255 char max
encrypted_card_data.metadata array of objects Optional	Additional metadata related to the card details object. Allowable Values: Valid array of card details metadata objects
encrypted_card_data.metadata[].name string Required	Specifies the metadata attribute name, such as `CARD_ART_ID`, `MAX_TOKENS_PER_CARD`, and so on. Allowable Values: 255 char max
encrypted_card_data.metadata[].value string Required	Specifies the value of the metadata attribute. Allowable Values: 255 char max
card_token string Optional	Unique identifier of the card. Allowable Values: 1–36 chars
device_type string Optional	Specifies the type of device. Allowable Values: `APPLIANCE`, `GAMING_DEVICE`, `LAPTOP`, `MOBILE_PHONE`, `MOBILE_PHONE_OR_TABLET`, `PERSONAL_COMPUTER`, `TABLET`, `UNKNOWN`, `UNRECOGNIZED`, `VEHICLE`, `WATCH`
provisioning_app_version string Optional	Specifies the version of the application making the provisioning request. This field is used for debugging and fraud prevention. Allowable Values: 50 char max
wallet_account_id string Required	User’s Google Wallet account ID, as provided by Google during the provisioning process. Google refers to this field as `ActiveWalletId`. Allowable Values: 1–50 chars
device_id string Required	Unique identifier of the user’s Google device, as provided by Google during the provisioning process. Google refers to this field as `StableHardwareId`. Allowable Values: 1–24 chars

Sample request body

Sample Google Pay request

JSON

{
  "encrypted_card_data": {
    "expiration": {
      "month": "01",
      "year": "2025"
    },
    "card_token": "card-token-811",
    "primary_account_number": "4111111111111111",
    "cardholder_info": {
      "first_name": "Jane",
      "last_name": "Liu",
      "cardholder_address": {
        "city": "Oakland",
        "state": "CA",
        "address_line_1": "180 Grand Ave",
        "address_line_2": "Floor 6",
        "postal_code": "94612",
        "country_code": "US"
      },
      "email_address": "marqetaTest@marqeta.com",
      "phone_number": "1234567890"
    }
  },
  "device_id": "W85OGhjZTk2dsr452dgsr51j",
  "wallet_user_id": "ae25OGhjZTk2dsr452dgsr51",
  "provisioning_app_version": "2.13.3",
  "wallet_account_id": "ae123GhjZTk1dsr123dgsr12"
}

Response body

Fields	Description
created_time datetime Returned	Date and time when the resource was created, in UTC. Allowable Values: date-time Format: yyyy-MM-ddThh:mm:ssZ
last_modified_time datetime Returned	Date and time when the resource was created, in UTC. Allowable Values: date-time Format: yyyy-MM-ddThh:mm:ssZ
card_token string Conditionally returned	Unique identifier of the card. Allowable Values: 1–36 chars
push_tokenize_request_data object Returned	Contains data pertaining to a Google push tokenization request. Allowable Values: `display_name`, `last_digits`, `network`, `opaque_payment_card`, `token_service_provider`, `user_address`
push_tokenize_request_data.display_name string Returned	Name of the card as displayed in the digital wallet, typically showing the card brand and last four digits of the primary account number (PAN). `Visa 5678`, for example. Allowable Values: 255 char max
push_tokenize_request_data.last_digits string Returned	Last four digits of the funding primary account number (FPAN), which is the primary account number of the physical or virtual card. Allowable Values: 4 chars
push_tokenize_request_data.network string Returned	Card network, as defined by Google; expected to align with the value of the `token_service_provider` field. Allowable Values: `Mastercard`, `Visa`
push_tokenize_request_data.token_service_provider string Returned	Token service provider, as defined by Google; expected to align with the value of the `network` field. Allowable Values: `TOKEN_PROVIDER_MASTERCARD`, `TOKEN_PROVIDER_VISA`
push_tokenize_request_data.opaque_payment_card string Returned	Encrypted card data passed to Google in base64 format. This data should not be modified in transit. For more information, see https://developers.google.com/pay/issuers/apis/push-provisioning/android/push-provisioning-objects#opaque_payment_card_opc. Allowable Values: 1–5000 chars
push_tokenize_request_data.user_address object Returned	Contains cardholder address information for a Google Wallet push tokenization request. Although not required, Marqeta recommends that you provide all the information in this object. Any missing or invalid address information may result in the user being prompted to complete or correct the address. For more information, see https://developers.google.com/pay/issuers/apis/push-provisioning/android/push-provisioning-objects#useraddress. Allowable Values: `address1`, `address2`, `city`, `country`, `name`, `phone`, `postal_code`
push_tokenize_request_data.user_address.name string Conditionally returned	Name of the cardholder. Allowable Values: 255 char max
push_tokenize_request_data.user_address.address1 string Returned	Street address of the cardholder. Allowable Values: 1–255 chars
push_tokenize_request_data.user_address.address2 string Conditionally returned	Secondary address information, such as a suite or apartment number Allowable Values: 255 char max
push_tokenize_request_data.user_address.city string Conditionally returned	City of the cardholder. Allowable Values: 255 char max
push_tokenize_request_data.user_address.state string Conditionally returned	State or province code of the address. Allowable Values: 3 char max
push_tokenize_request_data.user_address.postal_code string Returned	Postal code of the cardholder, such as a United States ZIP code. Allowable Values: 1–50 chars
push_tokenize_request_data.user_address.country string Conditionally returned	Two-character ISO 3166-1 alpha-2 country code. Allowable Values: 2 char max
push_tokenize_request_data.user_address.phone string Conditionally returned	Phone number of the cardholder. Allowable Values: 50 char max

Sample response body

Sample Google Pay response

JSON

{
  "created_time": "2025-09-09T18:08:07Z",
  "last_modified_time": "2025-09-09T18:08:07Z",
  "card_token": "my_card_01",
  "push_tokenize_request_data": {
    "display_name": "Visa Card",
    "last_digits": "1008",
    "network": "Visa",
    "token_service_provider": "TOKEN_PROVIDER_VISA",
    "opaque_payment_card": "eyJraWQiOiIzVkhSWVVSUlRVT1....",
    "user_address": {
      "name": "Jane Liu",
      "address1": "180 Grand Avenue",
      "city": "Oakland",
      "state": "CA",
      "zip": "94612",
      "country": "US",
      "phone": "18000001111",
      "postal_code": "94612"
    }
  }
}

Create a digital wallet provisioning request for Google Wallet (UPP)

Action: POST Endpoint: /digitalwalletprovisionrequests/v2/googlepay Use the /digitalwalletprovisionrequests/v2/googlepay endpoint to retrieve the card data needed to provision a digital wallet token into Google Wallet via the UPP (User-Presented Provisioning) flow. The returned card data is encrypted using the digital wallet provider’s encryption key, thereby reducing your Payment Card Industry (PCI) compliance overhead.

Header parameter

Fields	Description
req-sys-id string Optional	Random pseudo-unique identifier of a request, used for troubleshooting between multiple parties. Usually a globally unique identifier (GUID). Allowable Values: 1–36 chars
region string Optional	Region of the card requested for provisioning. Applicable to both physical and virtual cards. Allowable Values: `NAM`, `EMEA`, `APAC`
isVirtualCard boolean Optional	Header flag to identify the type of the card requested for provisioning. Value is `true` for virtual cards, `false` for physical cards. Allowable Values: Example: `true`

Request body

Fields	Description
encrypted_card_data object Required	Encrypted data object. This object is first encrypted using the recipient’s public key and sent in JSON Web Encryption (JWE) format and then signed using the sender’s private key using JSON Web Signature (JWS). It represents the decrypted format. Allowable Values: `card_token`, `card_type`, `cardholder_info`, `expiration`, `metadata`, `primary_account_number`
encrypted_card_data.expiration object Required	Specifies the expiry date for the card. Allowable Values: `month`, `year`
encrypted_card_data.expiration.month string Required	Specifies the expiry month for the card in MM format. `01`, for example. Allowable Values: Format: MM
encrypted_card_data.expiration.year string Required	Specifies the expiry year for the card in yyyy format. `2024`, for example. Allowable Values: Format: yyyy
encrypted_card_data.card_token string Optional	Unique identifier of the card. Allowable Values: 1–36 chars
encrypted_card_data.primary_account_number string Required	Account number of the card being tokenized. Allowable Values: 12–19 chars
encrypted_card_data.card_type string Optional	Specifies the type of card. This field is required for Samsung Wallet. Allowable Values: `CREDIT`, `DEBIT`
encrypted_card_data.cardholder_info object Optional	Contains personal information about the cardholder. Allowable Values: `cardholder_address`, `email_address`, `first_name`, `last_name`, `phone_number`
encrypted_card_data.cardholder_info.first_name string Optional	First or given name of the cardholder. Allowable Values: 40 char max
encrypted_card_data.cardholder_info.last_name string Optional	Last or family name of the cardholder. Allowable Values: 40 char max
encrypted_card_data.cardholder_info.cardholder_address object Optional	Specifies the cardholder’s address. Allowable Values: `address_line_1`, `address_line_2`, `city`, `country_code`, `postal_code`, `state`
encrypted_card_data.cardholder_info.cardholder_address.address_line_1 string Required	Street address of the cardholder. Allowable Values: 1–255 chars
encrypted_card_data.cardholder_info.cardholder_address.address_line_2 string Optional	Additional address information for the cardholder, such as a suite, floor, room, PO Box or apartment number. `Suite 600`, for example. Allowable Values: 255 char max
encrypted_card_data.cardholder_info.cardholder_address.postal_code string Required	Postal code of the cardholder. Allowable Values: 1–50 chars
encrypted_card_data.cardholder_info.cardholder_address.city string Optional	City of the cardholder. Allowable Values: 40 char max
encrypted_card_data.cardholder_info.cardholder_address.state string Optional	State or province code associated with the cardholder’s address. Allowable Values: 3 char max
encrypted_card_data.cardholder_info.cardholder_address.country_code string Optional	Two-character ISO 3166-1 alpha-2 country code. `US`, for example. Allowable Values: 2 char max
encrypted_card_data.cardholder_info.email_address string Optional	Email address of the cardholder. Allowable Values: 255 char max
encrypted_card_data.cardholder_info.phone_number string Optional	Phone number of the cardholder. This number is used when Marqeta performs step-up authentication on your behalf. Allowable Values: 255 char max
encrypted_card_data.metadata array of objects Optional	Additional metadata related to the card details object. Allowable Values: Valid array of card details metadata objects
encrypted_card_data.metadata[].name string Required	Specifies the metadata attribute name, such as `CARD_ART_ID`, `MAX_TOKENS_PER_CARD`, and so on. Allowable Values: 255 char max
encrypted_card_data.metadata[].value string Required	Specifies the value of the metadata attribute. Allowable Values: 255 char max
card_token string Optional	Unique identifier of the card. Allowable Values: 1–36 chars
device_type string Optional	Specifies the type of device. Allowable Values: `APPLIANCE`, `GAMING_DEVICE`, `LAPTOP`, `MOBILE_PHONE`, `MOBILE_PHONE_OR_TABLET`, `PERSONAL_COMPUTER`, `TABLET`, `UNKNOWN`, `UNRECOGNIZED`, `VEHICLE`, `WATCH`
provisioning_app_version string Optional	Version of the application making the provisioning request. Used for debugging and fraud prevention. Allowable Values: 50 char max
wallet_account_id string Required	User’s Google Wallet account ID, as provided by Google during the provisioning process. Google refers to this field as `ActiveWalletId`. Allowable Values: 1–50 chars
device_id string Required	Unique identifier of the user’s Google device, as provided by Google during the provisioning process. Google refers to this field as `StableHardwareId`. Allowable Values: 1–24 chars
server_session_id string Optional	Unique identifier of the session, provided by the digital wallet provider for the UPP provisioning flow. Allowable Values: 1–50 characters
token_requestor_id string Optional	Identifier of the token requestor, used to generate the TSP OPC. Required when tokenizing a Visa card to a Fitbit device; omitting this field in that scenario will cause the request to fail.

Sample request body

Sample Google Pay UPP request

JSON

{
  "encrypted_card_data": {
    "expiration": {
      "month": "01",
      "year": "2025"
    },
    "card_token": "card-token-811",
    "primary_account_number": "4111111111111111",
    "cardholder_info": {
      "first_name": "Jane",
      "last_name": "Liu",
      "cardholder_address": {
        "city": "Oakland",
        "state": "CA",
        "address_line_1": "180 Grand Ave",
        "address_line_2": "Floor 6",
        "postal_code": "94612",
        "country_code": "US"
      },
      "email_address": "marqetaTest@marqeta.com",
      "phone_number": "1234567890"
    }
  },
  "device_id": "W85OGhjZTk2dsr452dgsr51j",
  "wallet_account_id": "ae123GhjZTk1dsr123dgsr12",
  "provisioning_app_version": "2.13.3",
  "server_session_id": "sess-abc123def456",
  "token_requestor_id": "40010030273"
}

Response body

Fields	Description
created_time datetime Conditionally returned	Date and time when the resource was created, in UTC. Allowable Values: date-time Format: yyyy-MM-ddThh:mm:ssZ
last_modified_time datetime Conditionally returned	Date and time when the resource was created, in UTC. Allowable Values: date-time Format: yyyy-MM-ddThh:mm:ssZ
card_token string Conditionally returned	Unique identifier of the card. Allowable Values: 1–36 chars
push_tokenize_request_data object Conditionally returned	Contains data pertaining to a Google push tokenization request. Allowable Values: `display_name`, `last_digits`, `network`, `opaque_payment_card`, `token_service_provider`, `user_address`
push_tokenize_request_data.display_name string Returned	Name of the card as displayed in the digital wallet, typically showing the card brand and last four digits of the primary account number (PAN). `Visa 5678`, for example. Allowable Values: 255 char max
push_tokenize_request_data.last_digits string Returned	Last four digits of the funding primary account number (FPAN), which is the primary account number of the physical or virtual card. Allowable Values: 4 chars
push_tokenize_request_data.network string Returned	Card network, as defined by Google; expected to align with the value of the `token_service_provider` field. Allowable Values: `Mastercard`, `Visa`
push_tokenize_request_data.token_service_provider string Returned	Token service provider, as defined by Google; expected to align with the value of the `network` field. Allowable Values: `TOKEN_PROVIDER_MASTERCARD`, `TOKEN_PROVIDER_VISA`
push_tokenize_request_data.opaque_payment_card string Returned	Encrypted card data passed to Google in base64 format. This data should not be modified in transit. For more information, see https://developers.google.com/pay/issuers/apis/push-provisioning/android/push-provisioning-objects#opaque_payment_card_opc. Allowable Values: 1–5000 chars
push_tokenize_request_data.user_address object Returned	Contains cardholder address information for a Google Wallet push tokenization request. Although not required, Marqeta recommends that you provide all the information in this object. Any missing or invalid address information may result in the user being prompted to complete or correct the address. For more information, see https://developers.google.com/pay/issuers/apis/push-provisioning/android/push-provisioning-objects#useraddress. Allowable Values: `address1`, `address2`, `city`, `country`, `name`, `phone`, `postal_code`
push_tokenize_request_data.user_address.name string Conditionally returned	Name of the cardholder. Allowable Values: 255 char max
push_tokenize_request_data.user_address.address1 string Returned	Street address of the cardholder. Allowable Values: 1–255 chars
push_tokenize_request_data.user_address.address2 string Conditionally returned	Secondary address information, such as a suite or apartment number Allowable Values: 255 char max
push_tokenize_request_data.user_address.city string Conditionally returned	City of the cardholder. Allowable Values: 255 char max
push_tokenize_request_data.user_address.state string Conditionally returned	State or province code of the address. Allowable Values: 3 char max
push_tokenize_request_data.user_address.postal_code string Returned	Postal code of the cardholder, such as a United States ZIP code. Allowable Values: 1–50 chars
push_tokenize_request_data.user_address.country string Conditionally returned	Two-character ISO 3166-1 alpha-2 country code. Allowable Values: 2 char max
push_tokenize_request_data.user_address.phone string Conditionally returned	Phone number of the cardholder. Allowable Values: 50 char max
google_opaque_payment_card string Conditionally returned	Encrypted data field created by the issuer and passed to Google Wallet during the UPP push provisioning process. Allowable Values: Encrypted string

Sample response body

Sample Google Pay UPP response

JSON

{
  "created_time": "2025-09-09T18:08:07Z",
  "last_modified_time": "2025-09-09T18:08:07Z",
  "card_token": "my_card_01",
  "google_opaque_payment_card": "eyJraWQiOiIzVkhSWVVSUlRVT1....",
  "push_tokenize_request_data": {
    "display_name": "Visa Card",
    "last_digits": "1008",
    "network": "Visa",
    "token_service_provider": "TOKEN_PROVIDER_VISA",
    "opaque_payment_card": "eyJraWQiOiIzVkhSWVVSUlRVT1....",
    "user_address": {
      "name": "Jane Liu",
      "address1": "180 Grand Avenue",
      "city": "Oakland",
      "state": "CA",
      "zip": "94612",
      "country": "US",
      "phone": "18000001111",
      "postal_code": "94612"
    }
  }
}

Error responses

HTTP Status	Description
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"
}

Create digital wallet provisioning request for Samsung Wallet

Action: POST Endpoint: /digitalwalletprovisionrequests/samsungpay Use the /digitalwalletprovisionrequests/samsungpay endpoint to return card data for use in provisioning a digital wallet token into Samsung Wallet. The returned card data is encrypted using the digital wallet provider’s encryption key, thereby reducing your Payment Card Industry (PCI) compliance overhead.

Header parameter

Fields	Description
req-sys-id string Optional	Random pseudo-unique identifier of a request, used for troubleshooting between multiple parties. Usually a globally unique identifier (GUID). Allowable Values: 1–36 chars

Request body

Fields	Description
encrypted_card_data object Required	Encrypted data object. This object is first encrypted using the recipient’s public key and sent in JSON Web Encryption (JWE) format and then signed using the sender’s private key using JSON Web Signature (JWS). It represents the decrypted format. Allowable Values: `card_token`, `card_type`, `cardholder_info`, `expiration`, `metadata`, `primary_account_number`
encrypted_card_data.expiration object Required	Specifies the expiry date for the card. Allowable Values: `month`, `year`
encrypted_card_data.expiration.month string Required	Specifies the expiry month for the card in MM format. `01`, for example. Allowable Values: Format: MM
encrypted_card_data.expiration.year string Required	Specifies the expiry year for the card in yyyy format. `2024`, for example. Allowable Values: Format: yyyy
encrypted_card_data.card_token string Optional	Unique identifier of the card. Allowable Values: 1–36 chars
encrypted_card_data.primary_account_number string Required	Account number of the card being tokenized. Allowable Values: 12–19 chars
encrypted_card_data.card_type string Optional	Specifies the type of card. This field is required for Samsung Wallet. Allowable Values: `CREDIT`, `DEBIT`
encrypted_card_data.cardholder_info object Optional	Contains personal information about the cardholder. Allowable Values: `cardholder_address`, `email_address`, `first_name`, `last_name`, `phone_number`
encrypted_card_data.cardholder_info.first_name string Optional	First or given name of the cardholder. Allowable Values: 40 char max
encrypted_card_data.cardholder_info.last_name string Optional	Last or family name of the cardholder. Allowable Values: 40 char max
encrypted_card_data.cardholder_info.cardholder_address object Optional	Specifies the cardholder’s address. Allowable Values: `address_line_1`, `address_line_2`, `city`, `country_code`, `postal_code`, `state`
encrypted_card_data.cardholder_info.cardholder_address.address_line_1 string Required	Street address of the cardholder. Allowable Values: 1–255 chars
encrypted_card_data.cardholder_info.cardholder_address.address_line_2 string Optional	Additional address information for the cardholder, such as a suite, floor, room, PO Box or apartment number. `Suite 600`, for example. Allowable Values: 255 char max
encrypted_card_data.cardholder_info.cardholder_address.postal_code string Required	Postal code of the cardholder. Allowable Values: 1–50 chars
encrypted_card_data.cardholder_info.cardholder_address.city string Optional	City of the cardholder. Allowable Values: 40 char max
encrypted_card_data.cardholder_info.cardholder_address.state string Optional	State or province code associated with the cardholder’s address. Allowable Values: 3 char max
encrypted_card_data.cardholder_info.cardholder_address.country_code string Optional	Two-character ISO 3166-1 alpha-2 country code. `US`, for example. Allowable Values: 2 char max
encrypted_card_data.cardholder_info.email_address string Optional	Email address of the cardholder. Allowable Values: 255 char max
encrypted_card_data.cardholder_info.phone_number string Optional	Phone number of the cardholder. This number is used when Marqeta performs step-up authentication on your behalf. Allowable Values: 255 char max
encrypted_card_data.metadata array of objects Optional	Additional metadata related to the card details object. Allowable Values: Valid array of card details metadata objects
encrypted_card_data.metadata[].name string Required	Specifies the metadata attribute name, such as `CARD_ART_ID`, `MAX_TOKENS_PER_CARD`, and so on. Allowable Values: 255 char max
encrypted_card_data.metadata[].value string Required	Specifies the value of the metadata attribute. Allowable Values: 255 char max
card_token string Optional	Unique identifier of the card. Allowable Values: 1–36 chars
device_type string Optional	Specifies the type of device. Allowable Values: `APPLIANCE`, `GAMING_DEVICE`, `LAPTOP`, `MOBILE_PHONE`, `MOBILE_PHONE_OR_TABLET`, `PERSONAL_COMPUTER`, `TABLET`, `UNKNOWN`, `UNRECOGNIZED`, `VEHICLE`, `WATCH`
provisioning_app_version string Optional	Specifies the version of the application making the provisioning request. This field is used for debugging and fraud prevention. Allowable Values: 50 char max
wallet_user_id string Required	User’s Samsung Wallet account identifier, as provided by Samsung during the provisioning process. Allowable Values: 1–50 chars
device_id string Required	User’s Samsung device unique identifier, as provided by Samsung during the provisioning process. Allowable Values: 1–24 chars

Sample request body

Sample Samsung Pay request

JSON

{
  "encrypted_card_data": {
    "expiration": {
      "month": "01",
      "year": "2025"
    },
    "card_token": "card-token-811",
    "card_type": "CREDIT",
    "primary_account_number": "4111111111111111",
    "cardholder_info": {
      "first_name": "Jane",
      "last_name": "Liu",
      "cardholder_address": {
        "city": "Oakland",
        "state": "CA",
        "address_line_1": "180 Grand Ave",
        "address_line_2": "Floor 6",
        "postal_code": "94612",
        "country_code": "US"
      },
      "email_address": "marqetaTest@marqeta.com",
      "phone_number": "1234567890"
    }
  },
  "device_id": "W85OGhjZTk2dsr452dgsr51j",
  "wallet_user_id": "ae25OGhjZTk2dsr452dgsr51",
  "provisioning_app_version": "2.13.3"
}

Response body

Fields	Description
created_time datetime Returned	Date and time when the resource was created, in UTC. Allowable Values: date-time Format: yyyy-MM-ddThh:mm:ssZ
last_modified_time datetime Returned	Date and time when the resource was created, in UTC. Allowable Values: date-time Format: yyyy-MM-ddThh:mm:ssZ
card_token string Conditionally returned	Unique identifier of the card. Allowable Values: 1–36 chars
push_tokenize_request_data object Returned	Contains data pertaining to a Samsung push tokenization request. Allowable Values: `card_type`, `display_name`, `extra_provision_payload`, `last_digits`, `network`, `token_service_provider`
push_tokenize_request_data.display_name string Returned	Name of the card as displayed in the digital wallet, typically showing the card brand and last four digits of the primary account number (PAN). `Visa 5678`, for example. Allowable Values: 255 char max
push_tokenize_request_data.last_digits string Returned	Last four digits of the funding primary account number (FPAN), which is the primary account number of the physical or virtual card. Allowable Values: 4 chars
push_tokenize_request_data.network string Returned	Card network, as defined by Google; expected to align with the value of the `token_service_provider` field. Allowable Values: `Visa`, `Mastercard`
push_tokenize_request_data.token_service_provider string Returned	Token service provider, as defined Google; expected to align with the value of the `network` field. Allowable Values: `MC`, `VI`
push_tokenize_request_data.extra_provision_payload string Returned	Encrypted card or cardholder details. Allowable Values: Encrypted string
push_tokenize_request_data.card_type string Returned	Specifies the type of payment card. Allowable Values: `CREDIT`, `DEBIT`, `GIFT`, `LOYALTY`, `PAYMENT`

Sample response body

Sample Samsung Pay response

JSON

{
  "created_time": "2025-09-09T18:08:05Z",
  "last_modified_time": "2025-09-09T18:08:05Z",
  "card_token": "my_card_01",
  "push_tokenize_request_data": {
    "display_name": "Mastercard Card",
    "last_digits": "6591",
    "network": "Mastercard",
    "token_service_provider": "MC",
    "extra_provision_payload": "ewogICJjYXJkSW5mbyIgOiB7CiAgICAicHVibGl....",
    "card_type": "PAYMENT"
  }
}

List digital wallet tokens

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

Header parameter

Fields	Description
req-sys-id string Optional	Random pseudo-unique identifier of a request, used for troubleshooting between multiple parties. Usually a globally unique identifier (GUID). Allowable Values: 1–36 chars

URL query parameters

Fields	Description
count integer Optional	Number of resources to retrieve. Allowable Values: Any integer
start_index integer Optional	Sort order index of the first resource to retrieve. Allowable Values: Any integer
fields string Optional	Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields. Allowable Values: Comma-delimited list of fields, or blank
sort_by string Optional	Field on which to sort. Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`. Prefix the field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order. Allowable Values: `createdTime`, `lastModifiedTime`, or any field in the resource model
start_date string Optional	Date when the digital wallet token becomes active. Allowable Values: Format: yyyy-MM-dd
end_date string Optional	Expiration date of the digital wallet token. Allowable Values: Format: yyyy-MM-dd
pan_reference_id string Optional	Unique identifier of the digital wallet token’s primary account number (PAN) within the card network. This value may vary, depending on the digital wallet. For example, the `pan_reference_id` may be different in an Apple Wallet and a Google Wallet for the same digital wallet token. Allowable Values: 36 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. This is the primary identifier for Visa. Allowable Values: 36 char max
correlation_id string Optional	Unique value representing a tokenization request (Mastercard only). Allowable Values: 36 char max
device_id string Optional	Unique identifier of the user’s device, as provided by the digital wallet provider during the provisioning process. Allowable Values: 36 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	Optional embedded `user` object. Allowable Values: Existing `user` object

Response body

Fields	Description
count integer Returned	Number of resources returned. This field is returned if there are resources in your returned array. Allowable Values: Any integer
start_index integer Returned	Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer
end_index integer Returned	Sort order index of the last resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer
is_more boolean Conditionally returned	A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that no more unreturned resources exist. This field is returned if there are resources in your returned array. Allowable Values: `true`, `false`
data array of undefineds Conditionally returned	Array of digital wallet token objects. Allowable Values: Valid data array of one or more digital wallet token objects. Objects are returned as appropriate to your query.
data[].encrypted_data object Conditionally returned	Contains encrypted data about the token service provider, device, or address verification. Allowable Values: `address_verification`, `device`, `token_service_provider`
data[].encrypted_data.token_service_provider object Conditionally returned	Contains information held and provided by the token service provider (card network). This object is returned when relevant information is provided by the token service provider. Allowable Values: `correlation_id`, `pan_reference_id`, `token_assurance_level`, `token_eligibility_decision`, `token_pan`, `token_reference_id`, `token_requestor_id`, `token_requestor_name`, `token_score`, `token_type`
data[].encrypted_data.token_service_provider.pan_reference_id string Returned	Unique identifier of the digital wallet token’s PAN within the card network. This value may vary, depending on the digital wallet. For example, the `pan_reference_id` may be different in an Apple Wallet and a Google Wallet for the same digital wallet token. Allowable Values: 1–255 chars
data[].encrypted_data.token_service_provider.token_reference_id string Conditionally returned	Identifier that correlates the digital wallet token with the card network. This is the primary identifier for Visa. For Mastercard, this field is not populated until the token is active. Allowable Values: 255 char max
data[].encrypted_data.token_service_provider.correlation_id string Conditionally returned	Unique value representing a tokenization request (Mastercard only). Allowable Values: 14 char max
data[].encrypted_data.token_service_provider.token_requestor_id string Returned	Identifier of the token requestor. This identifier differs for each card network. Allowable Values: 1–50 chars
data[].encrypted_data.token_service_provider.token_requestor_name string Returned	Human-readable name for the token requestor. In your code, we recommend using the token requestor identifier instead, because it is immutable once it has been created. Allowable Values: 1–100 chars
data[].encrypted_data.token_service_provider.token_type string Returned	Comma-delimited list of digital wallet token types to display. Allowable Values: `DEVICE_CLOUD_BASED`, `DEVICE_SECURE_ELEMENT`, `ECOMMERCE_DIGITAL_WALLET`, `MERCHANT_CARD_ON_FILE`, `PSEUDO_ACCOUNT`
data[].encrypted_data.token_service_provider.token_assurance_level string Conditionally returned	Specifies the assurance level of the token-to-PAN binding as defined by the payment network. Represents a general risk value from `00` to `99`. Allowable Values: 2 char max
data[].encrypted_data.token_service_provider.token_pan string Conditionally returned	Digital wallet token primary account number (PAN), also known as the Digital Account Number, Token Number, or Digital PAN (DPAN). Token PAN appears in masked format. To view the token PAN in clear text, use the `/showtokenpan` endpoint. Allowable Values: 19 char max
data[].encrypted_data.token_service_provider.token_expiration string Conditionally returned	Expiration of the digital wallet token. Allowable Values: Format: MMyy
data[].encrypted_data.token_service_provider.token_score string Conditionally returned	Token score assigned by the token service provider. This value is provided when it is received by the token service provider. Allowable Values: 25 char max
data[].encrypted_data.token_service_provider.token_eligibility_decision string Conditionally returned	Token service provider’s recommendation as to whether the digital wallet token should be provisioned. Allowable Values: 50 char max
data[].encrypted_data.device object Conditionally returned	Contains data about the provisioned device. Allowable Values: `device_id`, `ip_address`, `language_code`, `location`, `name`, `phone_number`, `type`
data[].encrypted_data.device.type string Returned	Specifies the type of device being provisioned. This object is returned when relevant information is provided by the token service provider, typically for device-based digital wallets such as Google Wallet and Apple Wallet only. Allowable Values: `APPLIANCE`, `GAMING_DEVICE`, `LAPTOP`, `MOBILE_PHONE`, `MOBILE_PHONE_OR_TABLET`, `PERSONAL_COMPUTER`, `TABLET`, `UNKNOWN`, `UNRECOGNIZED`, `WATCH`, `VEHICLE`
data[].encrypted_data.device.device_id string Conditionally returned	Identity number of the device. This value is returned if it is available for a given digital wallet token. Allowable Values: 255 char max
data[].encrypted_data.device.phone_number string Conditionally returned	Telephone number of the device, as returned by the digital wallet provider. This value may be the full phone number, the last four digits, or null. Allowable Values: 20 char max
data[].encrypted_data.device.name string Conditionally returned	Name of the device, as returned by the digital wallet provider. Allowable Values: 128 char max
data[].encrypted_data.device.location string Conditionally returned	Geographic coordinates of the device at the time of the tokenization request, as returned by the digital wallet provider. Allowable Values: 25 char max
data[].encrypted_data.device.ip_address string Conditionally returned	IPv4 address, as returned by the digital wallet provider. Allowable Values: 25 char max
data[].encrypted_data.device.language_code string Conditionally returned	Language the device is configured to use, such as `eng` for English. Allowable Values: 36 char max
data[].encrypted_data.address_verification object Conditionally returned	Contains the name and address of the cardholder for address verification. Allowable Values: `name`, `postal_code`, `street_address`
data[].encrypted_data.address_verification.name string Conditionally returned	Name of the cardholder, as returned by the digital wallet provider. Allowable Values: 255 char max
data[].encrypted_data.address_verification.street_address string Conditionally returned	Street address of the cardholder, as returned by the digital wallet provider. Allowable Values: 255 char max
data[].encrypted_data.address_verification.postal_code string Conditionally returned	Postal code of the cardholder, such as a United States ZIP code, as returned by the digital wallet provider. Allowable Values: 50 char max
data[].card_token string Conditionally returned	Unique identifier of the card. Allowable Values: 1–36 chars
data[].created_time datetime Conditionally returned	Date and time when the resource was created, in UTC. Allowable Values: date-time Format: yyyy-MM-ddThh:mm:ssZ
data[].fulfillment_status string Conditionally returned	Digital wallet token’s provisioning status. Allowable Values: `DECISION_GREEN`, `DECISION_RED`, `DECISION_YELLOW`, `PROVISIONED`, `REJECTED`
data[].issuer_eligibility_decision string Conditionally returned	Card issuer’s recommendation as to whether the digital wallet token should be provisioned. Example values: `0000` (Approved), `invalid.cid`, `avs.decline`, `token.activation` Allowable Values: 255 char max
data[].last_modified_time datetime Conditionally returned	Date and time when the resource was created, in UTC. Allowable Values: date-time Format: yyyy-MM-ddThh:mm:ssZ
data[].state string Conditionally returned	Current state of the digital wallet token. Allowable Values: 1–255 chars
data[].state_reason string Conditionally returned	Descriptive reason for the current state of the digital wallet token. Allowable Values: 255 char max
data[].token string Conditionally returned	Unique identifier for the digital wallet token on the Marqeta platform. Allowable Values: 1–36 chars
data[].wallet_provider_profile object Conditionally returned	Contains information held and provided by the digital wallet provider. This object is returned when relevant information is provided by the digital wallet provider. Allowable Values: `account`, `device_score`, `obs_result`, `pan_source`, `reason_code`, `risk_assessment`
data[].wallet_provider_profile.account object Returned	Contains information related to the cardholder, as provided by the digital wallet provider. Allowable Values: `email_address`, `id`, `score`
data[].wallet_provider_profile.account.id string Returned	Digital wallet provider’s unique identity number for the cardholder. This identity number does not correlate with other information. Allowable Values: 1–255 chars
data[].wallet_provider_profile.account.email_address string Conditionally returned	Hashed version of the email address linked to the digital wallet. The exact hashing algorithm may vary, depending on the wallet and network. You can use this field to validate that email associated with digital wallet matches what is on file for the account. Data is `hexBinary` encoded. Allowable Values: Hex-encoded string
data[].wallet_provider_profile.account.score string Conditionally returned	Wallet provider’s account score, indicating the confidence level associated with the account. The scale ranges from 1 to 5, where 5 indicates the highest level of confidence. The value in this file may be presented with or without a leading 0. Allowable Values: 2 char max
data[].wallet_provider_profile.risk_assessment object Conditionally returned	Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token, as returned by the digital wallet provider. Allowable Values: `score`, `version`
data[].wallet_provider_profile.risk_assessment.score string Conditionally returned	Digital wallet provider’s decision as to whether the digital wallet token should be provisioned. Allowable Values: `DECISION_GREEN`, `DECISION_RED`, `DECISION_YELLOW`
data[].wallet_provider_profile.risk_assessment.version string Conditionally returned	Digital wallet provider’s risk version. NOTE: Changes in the version might indicate differences in other fields. Allowable Values: Version information, as provided by the wallet provider
data[].wallet_provider_profile.device_score string Conditionally returned	Wallet provider device score on a scale from 1 to 5, indicating the confidence level of the device, where 5 indicates the highest level of confidence. Allowable Values: 1 to 5
data[].wallet_provider_profile.pan_source string Returned	Source from which the digital wallet provider obtained the card primary account number (PAN), as returned by the digital wallet provider. Allowable Values: `CONTACTLESS_TAP`, `KEY_ENTERED`, `MOBILE_BANKING_APP`, `ON_FILE`
data[].wallet_provider_profile.reason_code string Conditionally returned	Comma-separated list of wallet provider reason codes, describing the reason for the wallet provider’s provisioning decision. NOTE: This list of reason codes is subject to change. Apple Wallet (Visa/Mastercard), Google Wallet/Samsung Wallet (Mastercard only) - 01 - Cardholder’s wallet account is too new relative to launch. - 02 - Cardholder’s wallet account is too new relative to provisioning request. - 03 - Cardholder’s wallet account/card pair is newer than date threshold. - 04 - Changes made to account data within the account threshold. - 05 - Suspicious transactions linked to this account. - 06 - Account has not had activity in the last year. - 07 - Suspended cards in the secure element. - 08 - Device was put in lost mode in the last seven days for longer than the duration threshold. - 09 - The number of provisioning attempts on this device in 24 hours exceeds threshold. - 0A - There have been more than the threshold number of different cards attempted at provisioning to this phone in 24 hours. - 0B - The card provisioning attempt contains a distinct name in excess of the threshold. - 0C - The device score is less than 3. - 0D - The account score is less than 4. - 0E - Device provisioning location outside of the cardholder’s wallet account home country. - 0G - Suspected fraud. - 0H - The phone number score is less than 3. Google Wallet/Samsung Wallet (Visa only) - A0 - Cardholder PAN associated with account within threshold days. - A1 - Wallet account holder name on file does not match cardholder entered name. - A2 - User’s account on device less than threshold days. - A3 - User account was created within threshold days. - A4 - Wallet account created within threshold days. - A5 - Changes made to account data within threshold days. - A6 - The number of provisioning attempts across all cards on this device in the last 24 hours exceeds the threshold. - A7 - The wallet account into which the card is being provisioned contains distinct names greater than threshold. - A8 - Device provisioning location outside of cardholder’s wallet account home country. - A9 - Suspended cards in the wallet account is greater than threshold. - AA - This account has not had activity within threshold period. - AB - Number of days since device was last reported lost is less than threshold days. - AC - Number of transactions in last 12 months less than threshold number. - AD - Number of active tokens greater than threshold. - AE - Number of devices with Same UserID with token is greater than threshold. - AF - Number of active tokens on all devices is greater than threshold. - AG - Issuer deferred ID&V decision. - AH - Issuer encrypted payment instrument data expired. - AI - User/device receiving encrypted payment instrument data is different than the one that is provisioning the token. - AL - Encrypted payment instrument data is pushed to a different device than the one that issuer application authenticated. - AM - Encrypted payment instrument data is pushed to a different user than the cardholder. - AN - Encrypted Payment Instrument Data is being pushed by the Issuer to the same device that the Issuer application authenticated, but without any upfront authentication. - AO - Encrypted Payment Instrument Data is being pushed by the Issuer to the same device that the Issuer application authenticated, but with successful upfront authentication. Allowable Values: 100 char max

Retrieve digital wallet token

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

Header parameter

Fields	Description
req-sys-id string Optional	Random pseudo-unique identifier of a request, used for troubleshooting between multiple parties. Usually a globally unique identifier (GUID). Allowable Values: 1–36 chars

URL path parameters

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

Response body

Fields	Description
encrypted_data object Conditionally returned	Contains encrypted data about the token service provider, device, or address verification. Allowable Values: `address_verification`, `device`, `token_service_provider`
encrypted_data.token_service_provider object Conditionally returned	Contains information held and provided by the token service provider (card network). This object is returned when relevant information is provided by the token service provider. Allowable Values: `correlation_id`, `pan_reference_id`, `token_assurance_level`, `token_eligibility_decision`, `token_pan`, `token_reference_id`, `token_requestor_id`, `token_requestor_name`, `token_score`, `token_type`
encrypted_data.token_service_provider.pan_reference_id string Returned	Unique identifier of the digital wallet token’s PAN within the card network. This value may vary, depending on the digital wallet. For example, the `pan_reference_id` may be different in an Apple Wallet and a Google Wallet for the same digital wallet token. Allowable Values: 1–255 chars
encrypted_data.token_service_provider.token_reference_id string Conditionally returned	Identifier that correlates the digital wallet token with the card network. This is the primary identifier for Visa. For Mastercard, this field is not populated until the token is active. Allowable Values: 255 char max
encrypted_data.token_service_provider.correlation_id string Conditionally returned	Unique value representing a tokenization request (Mastercard only). Allowable Values: 14 char max
encrypted_data.token_service_provider.token_requestor_id string Returned	Identifier of the token requestor. This identifier differs for each card network. Allowable Values: 1–50 chars
encrypted_data.token_service_provider.token_requestor_name string Returned	Human-readable name for the token requestor. In your code, we recommend using the token requestor identifier instead, because it is immutable once it has been created. Allowable Values: 1–100 chars
encrypted_data.token_service_provider.token_type string Returned	Comma-delimited list of digital wallet token types to display. Allowable Values: `DEVICE_CLOUD_BASED`, `DEVICE_SECURE_ELEMENT`, `ECOMMERCE_DIGITAL_WALLET`, `MERCHANT_CARD_ON_FILE`, `PSEUDO_ACCOUNT`
encrypted_data.token_service_provider.token_assurance_level string Conditionally returned	Specifies the assurance level of the token-to-PAN binding as defined by the payment network. Represents a general risk value from `00` to `99`. Allowable Values: 2 char max
encrypted_data.token_service_provider.token_pan string Conditionally returned	Digital wallet token primary account number (PAN), also known as the Digital Account Number, Token Number, or Digital PAN (DPAN). Token PAN appears in masked format. To view the token PAN in clear text, use the `/showtokenpan` endpoint. Allowable Values: 19 char max
encrypted_data.token_service_provider.token_expiration string Conditionally returned	Expiration of the digital wallet token. Allowable Values: Format: MMyy
encrypted_data.token_service_provider.token_score string Conditionally returned	Token score assigned by the token service provider. This value is provided when it is received by the token service provider. Allowable Values: 25 char max
encrypted_data.token_service_provider.token_eligibility_decision string Conditionally returned	Token service provider’s recommendation as to whether the digital wallet token should be provisioned. Allowable Values: 50 char max
encrypted_data.device object Conditionally returned	Contains data about the provisioned device. Allowable Values: `device_id`, `ip_address`, `language_code`, `location`, `name`, `phone_number`, `type`
encrypted_data.device.type string Returned	Specifies the type of device being provisioned. This object is returned when relevant information is provided by the token service provider, typically for device-based digital wallets such as Google Wallet and Apple Wallet only. Allowable Values: `APPLIANCE`, `GAMING_DEVICE`, `LAPTOP`, `MOBILE_PHONE`, `MOBILE_PHONE_OR_TABLET`, `PERSONAL_COMPUTER`, `TABLET`, `UNKNOWN`, `UNRECOGNIZED`, `WATCH`, `VEHICLE`
encrypted_data.device.device_id string Conditionally returned	Identity number of the device. This value is returned if it is available for a given digital wallet token. Allowable Values: 255 char max
encrypted_data.device.phone_number string Conditionally returned	Telephone number of the device, as returned by the digital wallet provider. This value may be the full phone number, the last four digits, or null. Allowable Values: 20 char max
encrypted_data.device.name string Conditionally returned	Name of the device, as returned by the digital wallet provider. Allowable Values: 128 char max
encrypted_data.device.location string Conditionally returned	Geographic coordinates of the device at the time of the tokenization request, as returned by the digital wallet provider. Allowable Values: 25 char max
encrypted_data.device.ip_address string Conditionally returned	IPv4 address, as returned by the digital wallet provider. Allowable Values: 25 char max
encrypted_data.device.language_code string Conditionally returned	Language the device is configured to use, such as `eng` for English. Allowable Values: 36 char max
encrypted_data.address_verification object Conditionally returned	Contains the name and address of the cardholder for address verification. Allowable Values: `name`, `postal_code`, `street_address`
encrypted_data.address_verification.name string Conditionally returned	Name of the cardholder, as returned by the digital wallet provider. Allowable Values: 255 char max
encrypted_data.address_verification.street_address string Conditionally returned	Street address of the cardholder, as returned by the digital wallet provider. Allowable Values: 255 char max
encrypted_data.address_verification.postal_code string Conditionally returned	Postal code of the cardholder, such as a United States ZIP code, as returned by the digital wallet provider. Allowable Values: 50 char max
card_token string Conditionally returned	Unique identifier of the card. Allowable Values: 1–36 chars
created_time datetime Conditionally returned	Date and time when the resource was created, in UTC. Allowable Values: date-time Format: yyyy-MM-ddThh:mm:ssZ
fulfillment_status string Conditionally returned	Digital wallet token’s provisioning status. Allowable Values: `DECISION_GREEN`, `DECISION_RED`, `DECISION_YELLOW`, `PROVISIONED`, `REJECTED`
issuer_eligibility_decision string Conditionally returned	Card issuer’s recommendation as to whether the digital wallet token should be provisioned. Example values: `0000` (Approved), `invalid.cid`, `avs.decline`, `token.activation` Allowable Values: 255 char max
last_modified_time datetime Conditionally returned	Date and time when the resource was created, in UTC. Allowable Values: date-time Format: yyyy-MM-ddThh:mm:ssZ
state string Conditionally returned	Current state of the digital wallet token. Allowable Values: 1–255 chars
state_reason string Conditionally returned	Descriptive reason for the current state of the digital wallet token. Allowable Values: 255 char max
token string Conditionally returned	Unique identifier for the digital wallet token on the Marqeta platform. Allowable Values: 1–36 chars
wallet_provider_profile object Conditionally returned	Contains information held and provided by the digital wallet provider. This object is returned when relevant information is provided by the digital wallet provider. Allowable Values: `account`, `device_score`, `obs_result`, `pan_source`, `reason_code`, `risk_assessment`
wallet_provider_profile.account object Returned	Contains information related to the cardholder, as provided by the digital wallet provider. Allowable Values: `email_address`, `id`, `score`
wallet_provider_profile.account.id string Returned	Digital wallet provider’s unique identity number for the cardholder. This identity number does not correlate with other information. Allowable Values: 1–255 chars
wallet_provider_profile.account.email_address string Conditionally returned	Hashed version of the email address linked to the digital wallet. The exact hashing algorithm may vary, depending on the wallet and network. You can use this field to validate that email associated with digital wallet matches what is on file for the account. Data is `hexBinary` encoded. Allowable Values: Hex-encoded string
wallet_provider_profile.account.score string Conditionally returned	Wallet provider’s account score, indicating the confidence level associated with the account. The scale ranges from 1 to 5, where 5 indicates the highest level of confidence. The value in this file may be presented with or without a leading 0. Allowable Values: 2 char max
wallet_provider_profile.risk_assessment object Conditionally returned	Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token, as returned by the digital wallet provider. Allowable Values: `score`, `version`
wallet_provider_profile.risk_assessment.score string Conditionally returned	Digital wallet provider’s decision as to whether the digital wallet token should be provisioned. Allowable Values: `DECISION_GREEN`, `DECISION_RED`, `DECISION_YELLOW`
wallet_provider_profile.risk_assessment.version string Conditionally returned	Digital wallet provider’s risk version. NOTE: Changes in the version might indicate differences in other fields. Allowable Values: Version information, as provided by the wallet provider
wallet_provider_profile.device_score string Conditionally returned	Wallet provider device score on a scale from 1 to 5, indicating the confidence level of the device, where 5 indicates the highest level of confidence. Allowable Values: 1 to 5
wallet_provider_profile.pan_source string Returned	Source from which the digital wallet provider obtained the card primary account number (PAN), as returned by the digital wallet provider. Allowable Values: `CONTACTLESS_TAP`, `KEY_ENTERED`, `MOBILE_BANKING_APP`, `ON_FILE`
wallet_provider_profile.reason_code string Conditionally returned	Comma-separated list of wallet provider reason codes, describing the reason for the wallet provider’s provisioning decision. NOTE: This list of reason codes is subject to change. Apple Wallet (Visa/Mastercard), Google Wallet/Samsung Wallet (Mastercard only) - 01 - Cardholder’s wallet account is too new relative to launch. - 02 - Cardholder’s wallet account is too new relative to provisioning request. - 03 - Cardholder’s wallet account/card pair is newer than date threshold. - 04 - Changes made to account data within the account threshold. - 05 - Suspicious transactions linked to this account. - 06 - Account has not had activity in the last year. - 07 - Suspended cards in the secure element. - 08 - Device was put in lost mode in the last seven days for longer than the duration threshold. - 09 - The number of provisioning attempts on this device in 24 hours exceeds threshold. - 0A - There have been more than the threshold number of different cards attempted at provisioning to this phone in 24 hours. - 0B - The card provisioning attempt contains a distinct name in excess of the threshold. - 0C - The device score is less than 3. - 0D - The account score is less than 4. - 0E - Device provisioning location outside of the cardholder’s wallet account home country. - 0G - Suspected fraud. - 0H - The phone number score is less than 3. Google Wallet/Samsung Wallet (Visa only) - A0 - Cardholder PAN associated with account within threshold days. - A1 - Wallet account holder name on file does not match cardholder entered name. - A2 - User’s account on device less than threshold days. - A3 - User account was created within threshold days. - A4 - Wallet account created within threshold days. - A5 - Changes made to account data within threshold days. - A6 - The number of provisioning attempts across all cards on this device in the last 24 hours exceeds the threshold. - A7 - The wallet account into which the card is being provisioned contains distinct names greater than threshold. - A8 - Device provisioning location outside of cardholder’s wallet account home country. - A9 - Suspended cards in the wallet account is greater than threshold. - AA - This account has not had activity within threshold period. - AB - Number of days since device was last reported lost is less than threshold days. - AC - Number of transactions in last 12 months less than threshold number. - AD - Number of active tokens greater than threshold. - AE - Number of devices with Same UserID with token is greater than threshold. - AF - Number of active tokens on all devices is greater than threshold. - AG - Issuer deferred ID&V decision. - AH - Issuer encrypted payment instrument data expired. - AI - User/device receiving encrypted payment instrument data is different than the one that is provisioning the token. - AL - Encrypted payment instrument data is pushed to a different device than the one that issuer application authenticated. - AM - Encrypted payment instrument data is pushed to a different user than the cardholder. - AN - Encrypted Payment Instrument Data is being pushed by the Issuer to the same device that the Issuer application authenticated, but without any upfront authentication. - AO - Encrypted Payment Instrument Data is being pushed by the Issuer to the same device that the Issuer application authenticated, but with successful upfront authentication. Allowable Values: 100 char max

Sample response body

JSON

{
  "token": "my_digital_wallet_token_01",
  "card_token": "my_card_01",
  "state": "ACTIVE",
  "state_reason": "Digital wallet token provisioned to digital wallet",
  "fulfillment_status": "PROVISIONED",
  "issuer_eligibility_decision": "0000",
  "created_time": "2022-06-16T22:24:02Z",
  "last_modified_time": "2022-09-04T20:12:10Z",
  "encrypted_data": {
    "token_service_provider": {
      "token_reference_id": "DNITHE343434343459",
      "pan_reference_id": "V-123343434343434",
      "token_requestor_id": "40010030273",
      "token_requestor_name": "APPLE_PAY",
      "token_type": "DEVICE_SECURE_ELEMENT",
      "token_pan": "4111111111111111",
      "token_expiration": "1225",
      "token_eligibility_decision": "DECISION_GREEN"
    },
    "device": {
      "type": "MOBILE_PHONE",
      "language_code": "eng",
      "device_id": "01111ABCB11100210111111111111E261D1AA1F11A1",
      "phone_number": "18000001111",
      "name": "My iPhone",
      "location": "+11.11/-11.11",
      "ip_address": "1.1.1.1"
    },
    "address_verification": {
      "street_address": "180 grand ave,",
      "zip": "94612"
    }
  },
  "wallet_provider_profile": {
    "account": {
      "id": "ABCD2345",
      "email_address": "F11AAAA1A011C11111111111A1AA111F4D3E31DB1111AE2C111211D7C11E11A",
      "score": "5"
    },
    "risk_assessment": {
      "score": "DECISION_GREEN",
      "version": "0001.00"
    },
    "device_score": "3",
    "pan_source": "ON_FILE"
  }
}

List digital wallet tokens by card

Action: GET Endpoint: /digitalwallettokens/card/{card_token} Use the digitalwallettokens/card/{card_token} endpoint to retrieve a list of digital wallet tokens for the specified card.

Header parameter

Fields	Description
req-sys-id string Optional	Random pseudo-unique identifier of a request, used for troubleshooting between multiple parties. Usually a globally unique identifier (GUID). Allowable Values: 1–36 chars

URL path parameters

Fields	Description
card_token string Required	Token that identifies the card and correlates it with the card issuer. This token is used to minimize the need to exchange card details during subsequent API calls, and also for troubleshooting. Use a globally unique identifier (GUID) or a pseudo-unique identifier for this token. Allowable Values: Existing card token

URL query parameters

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

Response body

Fields	Description
count integer Returned	Number of resources returned. This field is returned if there are resources in your returned array. Allowable Values: Any integer
start_index integer Returned	Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer
end_index integer Returned	Sort order index of the last resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer
is_more boolean Conditionally returned	A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that no more unreturned resources exist. This field is returned if there are resources in your returned array. Allowable Values: `true`, `false`
data array of undefineds Conditionally returned	Array of digital wallet token objects. Allowable Values: Valid data array of one or more digital wallet token objects. Objects are returned as appropriate to your query.
data[].encrypted_data object Conditionally returned	Contains encrypted data about the token service provider, device, or address verification. Allowable Values: `address_verification`, `device`, `token_service_provider`
data[].encrypted_data.token_service_provider object Conditionally returned	Contains information held and provided by the token service provider (card network). This object is returned when relevant information is provided by the token service provider. Allowable Values: `correlation_id`, `pan_reference_id`, `token_assurance_level`, `token_eligibility_decision`, `token_pan`, `token_reference_id`, `token_requestor_id`, `token_requestor_name`, `token_score`, `token_type`
data[].encrypted_data.token_service_provider.pan_reference_id string Returned	Unique identifier of the digital wallet token’s PAN within the card network. This value may vary, depending on the digital wallet. For example, the `pan_reference_id` may be different in an Apple Wallet and a Google Wallet for the same digital wallet token. Allowable Values: 1–255 chars
data[].encrypted_data.token_service_provider.token_reference_id string Conditionally returned	Identifier that correlates the digital wallet token with the card network. This is the primary identifier for Visa. For Mastercard, this field is not populated until the token is active. Allowable Values: 255 char max
data[].encrypted_data.token_service_provider.correlation_id string Conditionally returned	Unique value representing a tokenization request (Mastercard only). Allowable Values: 14 char max
data[].encrypted_data.token_service_provider.token_requestor_id string Returned	Identifier of the token requestor. This identifier differs for each card network. Allowable Values: 1–50 chars
data[].encrypted_data.token_service_provider.token_requestor_name string Returned	Human-readable name for the token requestor. In your code, we recommend using the token requestor identifier instead, because it is immutable once it has been created. Allowable Values: 1–100 chars
data[].encrypted_data.token_service_provider.token_type string Returned	Comma-delimited list of digital wallet token types to display. Allowable Values: `DEVICE_CLOUD_BASED`, `DEVICE_SECURE_ELEMENT`, `ECOMMERCE_DIGITAL_WALLET`, `MERCHANT_CARD_ON_FILE`, `PSEUDO_ACCOUNT`
data[].encrypted_data.token_service_provider.token_assurance_level string Conditionally returned	Specifies the assurance level of the token-to-PAN binding as defined by the payment network. Represents a general risk value from `00` to `99`. Allowable Values: 2 char max
data[].encrypted_data.token_service_provider.token_pan string Conditionally returned	Digital wallet token primary account number (PAN), also known as the Digital Account Number, Token Number, or Digital PAN (DPAN). Token PAN appears in masked format. To view the token PAN in clear text, use the `/showtokenpan` endpoint. Allowable Values: 19 char max
data[].encrypted_data.token_service_provider.token_expiration string Conditionally returned	Expiration of the digital wallet token. Allowable Values: Format: MMyy
data[].encrypted_data.token_service_provider.token_score string Conditionally returned	Token score assigned by the token service provider. This value is provided when it is received by the token service provider. Allowable Values: 25 char max
data[].encrypted_data.token_service_provider.token_eligibility_decision string Conditionally returned	Token service provider’s recommendation as to whether the digital wallet token should be provisioned. Allowable Values: 50 char max
data[].encrypted_data.device object Conditionally returned	Contains data about the provisioned device. Allowable Values: `device_id`, `ip_address`, `language_code`, `location`, `name`, `phone_number`, `type`
data[].encrypted_data.device.type string Returned	Specifies the type of device being provisioned. This object is returned when relevant information is provided by the token service provider, typically for device-based digital wallets such as Google Wallet and Apple Wallet only. Allowable Values: `APPLIANCE`, `GAMING_DEVICE`, `LAPTOP`, `MOBILE_PHONE`, `MOBILE_PHONE_OR_TABLET`, `PERSONAL_COMPUTER`, `TABLET`, `UNKNOWN`, `UNRECOGNIZED`, `WATCH`, `VEHICLE`
data[].encrypted_data.device.device_id string Conditionally returned	Identity number of the device. This value is returned if it is available for a given digital wallet token. Allowable Values: 255 char max
data[].encrypted_data.device.phone_number string Conditionally returned	Telephone number of the device, as returned by the digital wallet provider. This value may be the full phone number, the last four digits, or null. Allowable Values: 20 char max
data[].encrypted_data.device.name string Conditionally returned	Name of the device, as returned by the digital wallet provider. Allowable Values: 128 char max
data[].encrypted_data.device.location string Conditionally returned	Geographic coordinates of the device at the time of the tokenization request, as returned by the digital wallet provider. Allowable Values: 25 char max
data[].encrypted_data.device.ip_address string Conditionally returned	IPv4 address, as returned by the digital wallet provider. Allowable Values: 25 char max
data[].encrypted_data.device.language_code string Conditionally returned	Language the device is configured to use, such as `eng` for English. Allowable Values: 36 char max
data[].encrypted_data.address_verification object Conditionally returned	Contains the name and address of the cardholder for address verification. Allowable Values: `name`, `postal_code`, `street_address`
data[].encrypted_data.address_verification.name string Conditionally returned	Name of the cardholder, as returned by the digital wallet provider. Allowable Values: 255 char max
data[].encrypted_data.address_verification.street_address string Conditionally returned	Street address of the cardholder, as returned by the digital wallet provider. Allowable Values: 255 char max
data[].encrypted_data.address_verification.postal_code string Conditionally returned	Postal code of the cardholder, such as a United States ZIP code, as returned by the digital wallet provider. Allowable Values: 50 char max
data[].card_token string Conditionally returned	Unique identifier of the card. Allowable Values: 1–36 chars
data[].created_time datetime Conditionally returned	Date and time when the resource was created, in UTC. Allowable Values: date-time Format: yyyy-MM-ddThh:mm:ssZ
data[].fulfillment_status string Conditionally returned	Digital wallet token’s provisioning status. Allowable Values: `DECISION_GREEN`, `DECISION_RED`, `DECISION_YELLOW`, `PROVISIONED`, `REJECTED`
data[].issuer_eligibility_decision string Conditionally returned	Card issuer’s recommendation as to whether the digital wallet token should be provisioned. Example values: `0000` (Approved), `invalid.cid`, `avs.decline`, `token.activation` Allowable Values: 255 char max
data[].last_modified_time datetime Conditionally returned	Date and time when the resource was created, in UTC. Allowable Values: date-time Format: yyyy-MM-ddThh:mm:ssZ
data[].state string Conditionally returned	Current state of the digital wallet token. Allowable Values: 1–255 chars
data[].state_reason string Conditionally returned	Descriptive reason for the current state of the digital wallet token. Allowable Values: 255 char max
data[].token string Conditionally returned	Unique identifier for the digital wallet token on the Marqeta platform. Allowable Values: 1–36 chars
data[].wallet_provider_profile object Conditionally returned	Contains information held and provided by the digital wallet provider. This object is returned when relevant information is provided by the digital wallet provider. Allowable Values: `account`, `device_score`, `obs_result`, `pan_source`, `reason_code`, `risk_assessment`
data[].wallet_provider_profile.account object Returned	Contains information related to the cardholder, as provided by the digital wallet provider. Allowable Values: `email_address`, `id`, `score`
data[].wallet_provider_profile.account.id string Returned	Digital wallet provider’s unique identity number for the cardholder. This identity number does not correlate with other information. Allowable Values: 1–255 chars
data[].wallet_provider_profile.account.email_address string Conditionally returned	Hashed version of the email address linked to the digital wallet. The exact hashing algorithm may vary, depending on the wallet and network. You can use this field to validate that email associated with digital wallet matches what is on file for the account. Data is `hexBinary` encoded. Allowable Values: Hex-encoded string
data[].wallet_provider_profile.account.score string Conditionally returned	Wallet provider’s account score, indicating the confidence level associated with the account. The scale ranges from 1 to 5, where 5 indicates the highest level of confidence. The value in this file may be presented with or without a leading 0. Allowable Values: 2 char max
data[].wallet_provider_profile.risk_assessment object Conditionally returned	Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token, as returned by the digital wallet provider. Allowable Values: `score`, `version`
data[].wallet_provider_profile.risk_assessment.score string Conditionally returned	Digital wallet provider’s decision as to whether the digital wallet token should be provisioned. Allowable Values: `DECISION_GREEN`, `DECISION_RED`, `DECISION_YELLOW`
data[].wallet_provider_profile.risk_assessment.version string Conditionally returned	Digital wallet provider’s risk version. NOTE: Changes in the version might indicate differences in other fields. Allowable Values: Version information, as provided by the wallet provider
data[].wallet_provider_profile.device_score string Conditionally returned	Wallet provider device score on a scale from 1 to 5, indicating the confidence level of the device, where 5 indicates the highest level of confidence. Allowable Values: 1 to 5
data[].wallet_provider_profile.pan_source string Returned	Source from which the digital wallet provider obtained the card primary account number (PAN), as returned by the digital wallet provider. Allowable Values: `CONTACTLESS_TAP`, `KEY_ENTERED`, `MOBILE_BANKING_APP`, `ON_FILE`
data[].wallet_provider_profile.reason_code string Conditionally returned	Comma-separated list of wallet provider reason codes, describing the reason for the wallet provider’s provisioning decision. NOTE: This list of reason codes is subject to change. Apple Wallet (Visa/Mastercard), Google Wallet/Samsung Wallet (Mastercard only) - 01 - Cardholder’s wallet account is too new relative to launch. - 02 - Cardholder’s wallet account is too new relative to provisioning request. - 03 - Cardholder’s wallet account/card pair is newer than date threshold. - 04 - Changes made to account data within the account threshold. - 05 - Suspicious transactions linked to this account. - 06 - Account has not had activity in the last year. - 07 - Suspended cards in the secure element. - 08 - Device was put in lost mode in the last seven days for longer than the duration threshold. - 09 - The number of provisioning attempts on this device in 24 hours exceeds threshold. - 0A - There have been more than the threshold number of different cards attempted at provisioning to this phone in 24 hours. - 0B - The card provisioning attempt contains a distinct name in excess of the threshold. - 0C - The device score is less than 3. - 0D - The account score is less than 4. - 0E - Device provisioning location outside of the cardholder’s wallet account home country. - 0G - Suspected fraud. - 0H - The phone number score is less than 3. Google Wallet/Samsung Wallet (Visa only) - A0 - Cardholder PAN associated with account within threshold days. - A1 - Wallet account holder name on file does not match cardholder entered name. - A2 - User’s account on device less than threshold days. - A3 - User account was created within threshold days. - A4 - Wallet account created within threshold days. - A5 - Changes made to account data within threshold days. - A6 - The number of provisioning attempts across all cards on this device in the last 24 hours exceeds the threshold. - A7 - The wallet account into which the card is being provisioned contains distinct names greater than threshold. - A8 - Device provisioning location outside of cardholder’s wallet account home country. - A9 - Suspended cards in the wallet account is greater than threshold. - AA - This account has not had activity within threshold period. - AB - Number of days since device was last reported lost is less than threshold days. - AC - Number of transactions in last 12 months less than threshold number. - AD - Number of active tokens greater than threshold. - AE - Number of devices with Same UserID with token is greater than threshold. - AF - Number of active tokens on all devices is greater than threshold. - AG - Issuer deferred ID&V decision. - AH - Issuer encrypted payment instrument data expired. - AI - User/device receiving encrypted payment instrument data is different than the one that is provisioning the token. - AL - Encrypted payment instrument data is pushed to a different device than the one that issuer application authenticated. - AM - Encrypted payment instrument data is pushed to a different user than the cardholder. - AN - Encrypted Payment Instrument Data is being pushed by the Issuer to the same device that the Issuer application authenticated, but without any upfront authentication. - AO - Encrypted Payment Instrument Data is being pushed by the Issuer to the same device that the Issuer application authenticated, but with successful upfront authentication. Allowable Values: 100 char max

Retrieve digital wallet token with PAN visible

Action: GET Endpoint: /digitalwallettokens/{token}/showtokenpan Use the /digitalwallettokens/{token}/showtokenpan endpoint to retrieve a digital wallet token with the entire primary account number (PAN) displayed. The PAN returned is of the digital wallet token, and not of the card. For security reasons, the PAN is not fully visible on the digital wallet token returned by GET /digitalwallettokens/{token}.

Header parameter

Fields	Description
req-sys-id string Optional	Random pseudo-unique identifier of a request, used for troubleshooting between multiple parties. Usually a globally unique identifier (GUID). Allowable Values: 1–36 chars

URL path parameters

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

Response body

Fields	Description
encrypted_data object Conditionally returned	Contains encrypted data about the token service provider, device, or address verification. Allowable Values: `address_verification`, `device`, `token_service_provider`
encrypted_data.token_service_provider object Conditionally returned	Contains information held and provided by the token service provider (card network). This object is returned when relevant information is provided by the token service provider. Allowable Values: `correlation_id`, `pan_reference_id`, `token_assurance_level`, `token_eligibility_decision`, `token_pan`, `token_reference_id`, `token_requestor_id`, `token_requestor_name`, `token_score`, `token_type`
encrypted_data.token_service_provider.pan_reference_id string Returned	Unique identifier of the digital wallet token’s PAN within the card network. This value may vary, depending on the digital wallet. For example, the `pan_reference_id` may be different in an Apple Wallet and a Google Wallet for the same digital wallet token. Allowable Values: 1–255 chars
encrypted_data.token_service_provider.token_reference_id string Conditionally returned	Identifier that correlates the digital wallet token with the card network. This is the primary identifier for Visa. For Mastercard, this field is not populated until the token is active. Allowable Values: 255 char max
encrypted_data.token_service_provider.correlation_id string Conditionally returned	Unique value representing a tokenization request (Mastercard only). Allowable Values: 14 char max
encrypted_data.token_service_provider.token_requestor_id string Returned	Identifier of the token requestor. This identifier differs for each card network. Allowable Values: 1–50 chars
encrypted_data.token_service_provider.token_requestor_name string Returned	Human-readable name for the token requestor. In your code, we recommend using the token requestor identifier instead, because it is immutable once it has been created. Allowable Values: 1–100 chars
encrypted_data.token_service_provider.token_type string Returned	Comma-delimited list of digital wallet token types to display. Allowable Values: `DEVICE_CLOUD_BASED`, `DEVICE_SECURE_ELEMENT`, `ECOMMERCE_DIGITAL_WALLET`, `MERCHANT_CARD_ON_FILE`, `PSEUDO_ACCOUNT`
encrypted_data.token_service_provider.token_assurance_level string Conditionally returned	Specifies the assurance level of the token-to-PAN binding as defined by the payment network. Represents a general risk value from `00` to `99`. Allowable Values: 2 char max
encrypted_data.token_service_provider.token_pan string Conditionally returned	Digital wallet token primary account number (PAN), also known as the Digital Account Number, Token Number, or Digital PAN (DPAN). Token PAN appears in masked format. To view the token PAN in clear text, use the `/showtokenpan` endpoint. Allowable Values: 19 char max
encrypted_data.token_service_provider.token_expiration string Conditionally returned	Expiration of the digital wallet token. Allowable Values: Format: MMyy
encrypted_data.token_service_provider.token_score string Conditionally returned	Token score assigned by the token service provider. This value is provided when it is received by the token service provider. Allowable Values: 25 char max
encrypted_data.token_service_provider.token_eligibility_decision string Conditionally returned	Token service provider’s recommendation as to whether the digital wallet token should be provisioned. Allowable Values: 50 char max
encrypted_data.device object Conditionally returned	Contains data about the provisioned device. Allowable Values: `device_id`, `ip_address`, `language_code`, `location`, `name`, `phone_number`, `type`
encrypted_data.device.type string Returned	Specifies the type of device being provisioned. This object is returned when relevant information is provided by the token service provider, typically for device-based digital wallets such as Google Wallet and Apple Wallet only. Allowable Values: `APPLIANCE`, `GAMING_DEVICE`, `LAPTOP`, `MOBILE_PHONE`, `MOBILE_PHONE_OR_TABLET`, `PERSONAL_COMPUTER`, `TABLET`, `UNKNOWN`, `UNRECOGNIZED`, `WATCH`, `VEHICLE`
encrypted_data.device.device_id string Conditionally returned	Identity number of the device. This value is returned if it is available for a given digital wallet token. Allowable Values: 255 char max
encrypted_data.device.phone_number string Conditionally returned	Telephone number of the device, as returned by the digital wallet provider. This value may be the full phone number, the last four digits, or null. Allowable Values: 20 char max
encrypted_data.device.name string Conditionally returned	Name of the device, as returned by the digital wallet provider. Allowable Values: 128 char max
encrypted_data.device.location string Conditionally returned	Geographic coordinates of the device at the time of the tokenization request, as returned by the digital wallet provider. Allowable Values: 25 char max
encrypted_data.device.ip_address string Conditionally returned	IPv4 address, as returned by the digital wallet provider. Allowable Values: 25 char max
encrypted_data.device.language_code string Conditionally returned	Language the device is configured to use, such as `eng` for English. Allowable Values: 36 char max
encrypted_data.address_verification object Conditionally returned	Contains the name and address of the cardholder for address verification. Allowable Values: `name`, `postal_code`, `street_address`
encrypted_data.address_verification.name string Conditionally returned	Name of the cardholder, as returned by the digital wallet provider. Allowable Values: 255 char max
encrypted_data.address_verification.street_address string Conditionally returned	Street address of the cardholder, as returned by the digital wallet provider. Allowable Values: 255 char max
encrypted_data.address_verification.postal_code string Conditionally returned	Postal code of the cardholder, such as a United States ZIP code, as returned by the digital wallet provider. Allowable Values: 50 char max
card_token string Conditionally returned	Unique identifier of the card. Allowable Values: 1–36 chars
created_time datetime Conditionally returned	Date and time when the resource was created, in UTC. Allowable Values: date-time Format: yyyy-MM-ddThh:mm:ssZ
fulfillment_status string Conditionally returned	Digital wallet token’s provisioning status. Allowable Values: `DECISION_GREEN`, `DECISION_RED`, `DECISION_YELLOW`, `PROVISIONED`, `REJECTED`
issuer_eligibility_decision string Conditionally returned	Card issuer’s recommendation as to whether the digital wallet token should be provisioned. Example values: `0000` (Approved), `invalid.cid`, `avs.decline`, `token.activation` Allowable Values: 255 char max
last_modified_time datetime Conditionally returned	Date and time when the resource was created, in UTC. Allowable Values: date-time Format: yyyy-MM-ddThh:mm:ssZ
state string Conditionally returned	Current state of the digital wallet token. Allowable Values: 1–255 chars
state_reason string Conditionally returned	Descriptive reason for the current state of the digital wallet token. Allowable Values: 255 char max
token string Conditionally returned	Unique identifier for the digital wallet token on the Marqeta platform. Allowable Values: 1–36 chars
wallet_provider_profile object Conditionally returned	Contains information held and provided by the digital wallet provider. This object is returned when relevant information is provided by the digital wallet provider. Allowable Values: `account`, `device_score`, `obs_result`, `pan_source`, `reason_code`, `risk_assessment`
wallet_provider_profile.account object Returned	Contains information related to the cardholder, as provided by the digital wallet provider. Allowable Values: `email_address`, `id`, `score`
wallet_provider_profile.account.id string Returned	Digital wallet provider’s unique identity number for the cardholder. This identity number does not correlate with other information. Allowable Values: 1–255 chars
wallet_provider_profile.account.email_address string Conditionally returned	Hashed version of the email address linked to the digital wallet. The exact hashing algorithm may vary, depending on the wallet and network. You can use this field to validate that email associated with digital wallet matches what is on file for the account. Data is `hexBinary` encoded. Allowable Values: Hex-encoded string
wallet_provider_profile.account.score string Conditionally returned	Wallet provider’s account score, indicating the confidence level associated with the account. The scale ranges from 1 to 5, where 5 indicates the highest level of confidence. The value in this file may be presented with or without a leading 0. Allowable Values: 2 char max
wallet_provider_profile.risk_assessment object Conditionally returned	Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token, as returned by the digital wallet provider. Allowable Values: `score`, `version`
wallet_provider_profile.risk_assessment.score string Conditionally returned	Digital wallet provider’s decision as to whether the digital wallet token should be provisioned. Allowable Values: `DECISION_GREEN`, `DECISION_RED`, `DECISION_YELLOW`
wallet_provider_profile.risk_assessment.version string Conditionally returned	Digital wallet provider’s risk version. NOTE: Changes in the version might indicate differences in other fields. Allowable Values: Version information, as provided by the wallet provider
wallet_provider_profile.device_score string Conditionally returned	Wallet provider device score on a scale from 1 to 5, indicating the confidence level of the device, where 5 indicates the highest level of confidence. Allowable Values: 1 to 5
wallet_provider_profile.pan_source string Returned	Source from which the digital wallet provider obtained the card primary account number (PAN), as returned by the digital wallet provider. Allowable Values: `CONTACTLESS_TAP`, `KEY_ENTERED`, `MOBILE_BANKING_APP`, `ON_FILE`
wallet_provider_profile.reason_code string Conditionally returned	Comma-separated list of wallet provider reason codes, describing the reason for the wallet provider’s provisioning decision. NOTE: This list of reason codes is subject to change. Apple Wallet (Visa/Mastercard), Google Wallet/Samsung Wallet (Mastercard only) - 01 - Cardholder’s wallet account is too new relative to launch. - 02 - Cardholder’s wallet account is too new relative to provisioning request. - 03 - Cardholder’s wallet account/card pair is newer than date threshold. - 04 - Changes made to account data within the account threshold. - 05 - Suspicious transactions linked to this account. - 06 - Account has not had activity in the last year. - 07 - Suspended cards in the secure element. - 08 - Device was put in lost mode in the last seven days for longer than the duration threshold. - 09 - The number of provisioning attempts on this device in 24 hours exceeds threshold. - 0A - There have been more than the threshold number of different cards attempted at provisioning to this phone in 24 hours. - 0B - The card provisioning attempt contains a distinct name in excess of the threshold. - 0C - The device score is less than 3. - 0D - The account score is less than 4. - 0E - Device provisioning location outside of the cardholder’s wallet account home country. - 0G - Suspected fraud. - 0H - The phone number score is less than 3. Google Wallet/Samsung Wallet (Visa only) - A0 - Cardholder PAN associated with account within threshold days. - A1 - Wallet account holder name on file does not match cardholder entered name. - A2 - User’s account on device less than threshold days. - A3 - User account was created within threshold days. - A4 - Wallet account created within threshold days. - A5 - Changes made to account data within threshold days. - A6 - The number of provisioning attempts across all cards on this device in the last 24 hours exceeds the threshold. - A7 - The wallet account into which the card is being provisioned contains distinct names greater than threshold. - A8 - Device provisioning location outside of cardholder’s wallet account home country. - A9 - Suspended cards in the wallet account is greater than threshold. - AA - This account has not had activity within threshold period. - AB - Number of days since device was last reported lost is less than threshold days. - AC - Number of transactions in last 12 months less than threshold number. - AD - Number of active tokens greater than threshold. - AE - Number of devices with Same UserID with token is greater than threshold. - AF - Number of active tokens on all devices is greater than threshold. - AG - Issuer deferred ID&V decision. - AH - Issuer encrypted payment instrument data expired. - AI - User/device receiving encrypted payment instrument data is different than the one that is provisioning the token. - AL - Encrypted payment instrument data is pushed to a different device than the one that issuer application authenticated. - AM - Encrypted payment instrument data is pushed to a different user than the cardholder. - AN - Encrypted Payment Instrument Data is being pushed by the Issuer to the same device that the Issuer application authenticated, but without any upfront authentication. - AO - Encrypted Payment Instrument Data is being pushed by the Issuer to the same device that the Issuer application authenticated, but with successful upfront authentication. Allowable Values: 100 char max

Sample response body

JSON

{
  "token": "my_digital_wallet_token_01",
  "card_token": "my_card_01",
  "state": "ACTIVE",
  "state_reason": "Digital wallet token provisioned to digital wallet",
  "fulfillment_status": "PROVISIONED",
  "issuer_eligibility_decision": "0000",
  "created_time": "2022-06-16T22:24:02Z",
  "last_modified_time": "2022-09-04T20:12:10Z",
  "encrypted_data": {
    "token_service_provider": {
      "token_reference_id": "DNITHE343434343459",
      "pan_reference_id": "V-123343434343434",
      "token_requestor_id": "40010030273",
      "token_requestor_name": "APPLE_PAY",
      "token_type": "DEVICE_SECURE_ELEMENT",
      "token_pan": "4111111111111111",
      "token_expiration": "1225",
      "token_eligibility_decision": "DECISION_GREEN"
    },
    "device": {
      "type": "MOBILE_PHONE",
      "language_code": "eng",
      "device_id": "01111ABCB11100210111111111111E261D1AA1F11A1",
      "phone_number": "18000001111",
      "name": "My iPhone",
      "location": "+11.11/-11.11",
      "ip_address": "1.1.1.1"
    },
    "address_verification": {
      "street_address": "180 Grand Ave",
      "zip": "94612"
    }
  },
  "wallet_provider_profile": {
    "account": {
      "id": "ABCD2345",
      "email_address": "F11AAAA1A011C11111111111A1AA111F4D3E31DB1111AE2C111211D7C11E11A",
      "score": "5"
    },
    "risk_assessment": {
      "score": "DECISION_GREEN",
      "version": "0001.00"
    },
    "device_score": "3",
    "pan_source": "ON_FILE"
  }
}

Create digital wallet token transition

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

Header parameter

Fields	Description
req-sys-id string Optional	Random pseudo-unique identifier of a request, used for troubleshooting between multiple parties. Usually a globally unique identifier (GUID). Allowable Values: 1–36 chars

Request body

Fields	Description
token string Optional	Unique identifier of the digital wallet token transition, and not the identifier of the digital wallet token itself. If you do not include a value for the token field, the system will generate one automatically. This value is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated. Allowable Values: 1–36 chars
reason_code string Required	Code describing the reason for the transition. Marqeta does not validate what is provided, although Marqeta-sourced changes use standard codes. Allowable Values: 1–255 chars
token_reference_id string Optional	Unique identifier of the digital wallet token within the card network. `token_reference_id` is unique at the card network level. This is the primary identifier for Visa. Allowable Values: 1–255 chars
channel string Required	Mechanism by which the transition was initiated. `API`, for example. Allowable Values: `ADMIN`, `API`, `DIGITAL_WALLET`, `FRAUD`, `IVR`, `MARQETA_DASHBOARD`, `SYSTEM`, `TOKEN_SERVICE_PROVIDER`
state string Required	Specifies the state to which the digital wallet token transitions. Allowable Values: `ACTIVE`, `REQUESTED`, `REQUEST_DECLINED`, `SUSPENDED`, `TERMINATED`
digital_wallet_token object Required	Hashed version of Marqeta’s unique identifier for the digital wallet tokens. Allowable Values: `token`
digital_wallet_token.token string Required	Marqeta’s unique identifier for the digital wallet token. Allowable Values: 1–36 chars
reason string Optional	Descriptive reason for the transition. Allowable Values: 255 char max

Sample request body

Activate token request

JSON

{
  "state": "ACTIVE",
  "reason_code": "01",
  "reason": "Customer Request",
  "digital_wallet_token": {
    "token": "my_digital_wallet_token_01"
  },
  "channel": "API"
}

Response body

Fields	Description
token string Returned	Unique identifier for the digital wallet token transition. Allowable Values: 1–36 chars
digital_wallet_token object Returned	Hashed version of Marqeta’s unique identifier for the digital wallet tokens. Allowable Values: `token`
digital_wallet_token.token string Returned	Marqeta’s unique identifier for the digital wallet token. Allowable Values: 1–36 chars
type string Returned	Type of digital wallet token transition. `state.activated`, for example. Allowable Values: `card.swap`, `state.activated`, `state.reinstated`, `state.suspended`, `state.terminated`
channel string Returned	Mechanism by which the transition was initiated. Allowable Values: `API`
state string Returned	Specifies the state to which the digital wallet token transitions. Allowable Values: `ACTIVE`, `SUSPENDED`, `TERMINATED`
fulfillment_status string Returned	Digital wallet token’s provisioning status. Allowable Values: `DECISION_GREEN`, `DECISION_RED`, `DECISION_YELLOW`, `PROVISIONED`, `REJECTED`
reason string Conditionally returned	Descriptive reason for the transition. Allowable Values: 255 char max
reason_code string Returned	Code describing the reason for the transition. Marqeta does not validate what is provided, although Marqeta-sourced changes use standard codes. Allowable Values: 1–255 chars
created_time datetime Returned	Date and time when the resource was created, in UTC. Allowable Values: date-time Format: yyyy-MM-ddThh:mm:ssZ

Sample response body

JSON

{
  "token": "my_dwt_transition_01",
  "digital_wallet_token": {
    "token": "my_digital_wallet_token_01"
  },
  "type": "state.activated",
  "channel": "API",
  "state": "ACTIVE",
  "fulfillment_status": "PROVISIONED",
  "reason": "Customer Request",
  "reason_code": "01",
  "created_time": "2025-09-10T06:30:20Z"
}

List digital wallet token transitions

Action: GET Endpoint: /digitalwallettokentransitions/digitalwallettoken/{token} Use the /digitalwallettokentransitions/digitalwallettoken/{token} endpoint to return an array of all transitions for a particular digital wallet token. This endpoint supports field filtering, pagination, and sorting.

Header parameter

Fields	Description
req-sys-id string Optional	Random pseudo-unique identifier of a request, used for troubleshooting between multiple parties. Usually a globally unique identifier (GUID). Allowable Values: 1–36 chars

URL path parameters

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

URL query parameters

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

Response body

Fields	Description
count integer Returned	Number of resources returned. This field is returned if there are resources in your returned array. Allowable Values: Any integer
start_index integer Returned	Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer
end_index integer Returned	Sort order index of the last resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer
is_more boolean Conditionally returned	A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that no more unreturned resources exist. This field is returned if there are resources in your returned array. Allowable Values: `true`, `false`
data array of objects Conditionally returned	Array of digital wallet token transition objects. Objects are returned as appropriate to your query. Allowable Values: Valid array of one or more digital wallet token transition objects
data[].token string Returned	Unique identifier of the digital wallet token transition, and not the identifier of the digital wallet token itself. Allowable Values: 1–36 chars
data[].digital_wallet_token object Returned	Hashed version of Marqeta’s unique identifier for the digital wallet tokens. Allowable Values: `token`
data[].digital_wallet_token.token string Returned	Marqeta’s unique identifier for the digital wallet token. Allowable Values: 1–36 chars
data[].card_swap object Conditionally returned	Hashed version of the `card_swap` object. Specifies the old and new payment card tokens that were swapped. Allowable Values: `newCardToken`, `previousCardToken`
data[].card_swap.previousCardToken string Returned	Unique identifier of the old card from which the digital wallet tokens are transferred. Allowable Values: 1–36 chars
data[].card_swap.newCardToken string Returned	Unique identifier of the new card to which the digital wallet tokens are transferred. Allowable Values: 1–36 chars
data[].type string Returned	Type of digital wallet token transition. `state.activated`, for example. Allowable Values: `card.swap`, `fulfillment.requested`, `state.activated`, `state.reinstated`, `state.request_declined`, `state.suspended`, `state.terminated`
data[].channel string Returned	Mechanism by which the transition was initiated. `API`, for example. Allowable Values: `ADMIN`, `API`, `DIGITAL_WALLET`, `FRAUD`, `IVR`, `MARQETA_DASHBOARD`, `SYSTEM`, `TOKEN_SERVICE_PROVIDER`
data[].state string Returned	Specifies the state to which to transition the digital wallet token. Allowable Values: `ACTIVE`, `REQUESTED`, `REQUEST_DECLINED`, `SUSPENDED`, `TERMINATED`
data[].fulfillment_status string Returned	Digital wallet token’s provisioning status. Allowable Values: `DECISION_GREEN`, `DECISION_RED`, `DECISION_YELLOW`, `PROVISIONED`, `REJECTED`
data[].reason string Conditionally returned	Descriptive reason for the transition. Allowable Values: 255 char max
data[].reason_code string Returned	Code describing the reason for the transition. Marqeta does not validate what is provided, although Marqeta-sourced changes use standard codes. Allowable Values: 1–255 chars
data[].created_time datetime Returned	Date and time when the resource was created, in UTC. Allowable Values: date-time Format: yyyy-MM-ddThh:mm:ssZ

Retrieve digital wallet token transition

Action: GET Endpoint: /digitalwallettokentransitions/{token} Use the /digitalwallettokentransitions/{token} endpoint to retrieve a specific digital wallet transition.

Header parameter

Fields	Description
req-sys-id string Optional	Random pseudo-unique identifier of a request, used for troubleshooting between multiple parties. Usually a globally unique identifier (GUID). Allowable Values: 1–36 chars

URL path parameters

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

URL query parameters

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

Response body

Fields	Description
token string Returned	Unique identifier of the digital wallet token transition, and not the identifier of the digital wallet token itself. Allowable Values: 1–36 chars
digital_wallet_token object Returned	Hashed version of Marqeta’s unique identifier for the digital wallet tokens. Allowable Values: `token`
digital_wallet_token.token string Returned	Marqeta’s unique identifier for the digital wallet token. Allowable Values: 1–36 chars
card_swap object Conditionally returned	Hashed version of the `card_swap` object. Specifies the old and new payment card tokens that were swapped. Allowable Values: `newCardToken`, `previousCardToken`
card_swap.previousCardToken string Returned	Unique identifier of the old card from which the digital wallet tokens are transferred. Allowable Values: 1–36 chars
card_swap.newCardToken string Returned	Unique identifier of the new card to which the digital wallet tokens are transferred. Allowable Values: 1–36 chars
type string Returned	Type of digital wallet token transition. `state.activated`, for example. Allowable Values: `card.swap`, `fulfillment.requested`, `state.activated`, `state.reinstated`, `state.request_declined`, `state.suspended`, `state.terminated`
channel string Returned	Mechanism by which the transition was initiated. `API`, for example. Allowable Values: `ADMIN`, `API`, `DIGITAL_WALLET`, `FRAUD`, `IVR`, `MARQETA_DASHBOARD`, `SYSTEM`, `TOKEN_SERVICE_PROVIDER`
state string Returned	Specifies the state to which to transition the digital wallet token. Allowable Values: `ACTIVE`, `REQUESTED`, `REQUEST_DECLINED`, `SUSPENDED`, `TERMINATED`
fulfillment_status string Returned	Digital wallet token’s provisioning status. Allowable Values: `DECISION_GREEN`, `DECISION_RED`, `DECISION_YELLOW`, `PROVISIONED`, `REJECTED`
reason string Conditionally returned	Descriptive reason for the transition. Allowable Values: 255 char max
reason_code string Returned	Code describing the reason for the transition. Marqeta does not validate what is provided, although Marqeta-sourced changes use standard codes. Allowable Values: 1–255 chars
created_time datetime Returned	Date and time when the resource was created, in UTC. Allowable Values: date-time Format: yyyy-MM-ddThh:mm:ssZ

Sample response body

Token in requested state

JSON

{
  "token": "bb50c999-9c4e-3f99-90a0-a12ab30fe81b",
  "digital_wallet_token": {
    "token": "c45c201-ad5e-3f23-76a0-a08cb36fa90a"
  },
  "type": "fulfillment.requested",
  "channel": "TOKEN_SERVICE_PROVIDER",
  "state": "REQUESTED",
  "fulfillment_status": "DECISION_GREEN",
  "reason": "Token creation",
  "reason_code": "21",
  "created_time": "2025-09-06T22:52:13Z"
}

Card swap transition

JSON

{
  "token": "cb40c400-ba4f-3f97-80b0-c09ab30fe63d",
  "digital_wallet_token": {
    "token": "cb45c201-ad5e-3f23-76a0-a08cb36fa90a"
  },
  "card_swap": {
    "previousCardToken": "card-token-1",
    "newCardToken": "card-token-2"
  },
  "type": "card.swap",
  "channel": "SYSTEM",
  "state": "ACTIVE",
  "fulfillment_status": "PROVISIONED",
  "reason": "New card",
  "reason_code": "14",
  "created_time": "2025-09-10T06:29:30Z"
}

Update expiry dates

Action: PUT Endpoint: /cardactions/updateexpiration Use the /cardactions/updateexpiration endpoint to update the expiry dates of a digital wallet token.

Header parameter

Fields	Description
req-sys-id string Optional	Random pseudo-unique identifier of a request, used for troubleshooting between multiple parties. Usually a globally unique identifier (GUID). Allowable Values: 1–36 chars

Request body

Fields	Description
encrypted_card_data object Required	Specifies details for updating digital wallet token expiration dates. Allowable Values: `new_card_token`, `new_pan_expiry`, `old_card_token`, `old_pan_expiry`, `primary_account_number`
encrypted_card_data.primary_account_number string Required	Account number of the card being tokenized. Allowable Values: 12–19 chars
encrypted_card_data.old_card_token string Required	Unique identifier of the card. Allowable Values: 1–36 chars
encrypted_card_data.old_pan_expiry object Required	Specifies the expiry date for the card. Allowable Values: `month`, `year`
encrypted_card_data.old_pan_expiry.month string Required	Specifies the expiry month for the card in MM format. `01`, for example. Allowable Values: Format: MM
encrypted_card_data.old_pan_expiry.year string Required	Specifies the expiry year for the card in yyyy format. `2024`, for example. Allowable Values: Format: yyyy
encrypted_card_data.new_card_token string Required	Unique identifier of the card. Allowable Values: 1–36 chars
encrypted_card_data.new_pan_expiry object Required	Specifies the expiry date for the card. Allowable Values: `month`, `year`
encrypted_card_data.new_pan_expiry.month string Required	Specifies the expiry month for the card in MM format. `01`, for example. Allowable Values: Format: MM
encrypted_card_data.new_pan_expiry.year string Required	Specifies the expiry year for the card in yyyy format. `2024`, for example. Allowable Values: Format: yyyy

Response body

Fields	Description
success boolean Conditionally returned	Indicates success if `true`, failure if `false`. Allowable Values: `true`, `false`

Transfer digital wallet tokens

Action: PUT Endpoint: /cardactions/cardswap Use the /cardactions/cardswap endpoint to transfer digital wallet tokens to a new card with a different primary account number (PAN).

Header parameter

Fields	Description
req-sys-id string Optional	Random pseudo-unique identifier of a request, used for troubleshooting between multiple parties. Usually a globally unique identifier (GUID). Allowable Values: 1–36 chars

Request body

Fields	Description
encrypted_card_data object Required	Contains details about the cards to be swapped. Allowable Values: `new_card_token`, `new_pan_expiry`, `new_primary_account_number`, `old_card_token`, `old_pan_expiry`, `old_primary_account_number`
encrypted_card_data.old_primary_account_number string Required	Primary account number for the existing payment card from which the digital wallet tokens are transferred. Allowable Values: 12–19 chars
encrypted_card_data.old_pan_expiry object Required	Specifies the expiry date for the card. Allowable Values: `month`, `year`
encrypted_card_data.old_pan_expiry.month string Required	Specifies the expiry month for the card in MM format. `01`, for example. Allowable Values: Format: MM
encrypted_card_data.old_pan_expiry.year string Required	Specifies the expiry year for the card in yyyy format. `2024`, for example. Allowable Values: Format: yyyy
encrypted_card_data.old_card_token string Required	Unique identifier of the card. Allowable Values: 1–36 chars
encrypted_card_data.new_primary_account_number string Required	Primary account number of the new card to which the digital wallet token are transferred. Allowable Values: 12–19 chars
encrypted_card_data.new_pan_expiry object Required	Specifies the expiry date for the card. Allowable Values: `month`, `year`
encrypted_card_data.new_pan_expiry.month string Required	Specifies the expiry month for the card in MM format. `01`, for example. Allowable Values: Format: MM
encrypted_card_data.new_pan_expiry.year string Required	Specifies the expiry year for the card in yyyy format. `2024`, for example. Allowable Values: Format: yyyy
encrypted_card_data.new_card_token string Required	Unique identifier of the new payment card token to which the digital wallet tokens are transferred. Allowable Values: 1–36 chars

Response body

Fields	Description
success boolean Conditionally returned	Indicates success if `true`, failure if `false`. Allowable Values: `true`, `false`

Create webhooks

Action: POST Endpoint: /webhooks/{event_type} Use the /webhooks/{event_type} endpoint to send a batch of events to a webhook.

Header parameter

Fields	Description
req-sys-id string Optional	Random pseudo-unique identifier of a request, used for troubleshooting between multiple parties. Usually a globally unique identifier (GUID). Allowable Values: 1–36 chars

URL path parameters

Fields	Description
event_type string Required	Digital wallet token event type. Allowable Values: `digitalwallettoken`, `digitalwallettokentransition`

Sample request body

Digital Wallet Token Webhooks

JSON

{
  "digitalwallettokens": [
    {
      "token": "my_webhook_event_01",
      "event_type": "digitalwallettoken.provisioningrequest",
      "webhook_details": {
        "token": "my_provisioning_request_01",
        "card_token": "my_card_01",
        "state": "REQUEST_DECLINED",
        "fulfillment_status": "REJECTED",
        "issuer_eligibility_decision": "avs.decline",
        "created_time": "2025-09-11T00:20:23Z",
        "last_modified_time": "2025-09-11T00:20:23Z",
        "encrypted_data": {
          "card_data": {
            "primary_account_number": "41111199999",
            "expiration_date": {
              "month": "01",
              "year": "2024"
            }
          },
          "token_service_provider": {
            "token_reference_id": "DNITHE343434343459",
            "pan_reference_id": "V-123343434343434",
            "token_requestor_id": "40010083275",
            "token_requestor_name": "UNKNOWN",
            "token_type": "MERCHANT_CARD_ON_FILE",
            "token_eligibility_decision": "DECISION_GREEN"
          },
          "device": {
            "language_code": "eng"
          },
          "address_verification": {
            "street_address": "180 Grand Ave",
            "zip": "94612"
          }
        },
        "wallet_provider_profile": {
          "account": {
            "id": "40010083275",
            "email_address": "A11AAAA1A011C11111111111A1AA111F...."
          },
          "risk_assessment": {},
          "pan_source": "KEY_ENTERED"
        }
      }
    }
  ]
}

Digital Wallet Token Transition Webhooks

JSON

{
  "digitalwallettokentransitions": [
    {
      "token": "my_webhook_event_02",
      "event_type": "digitalWalletTokenTransition.requested",
      "webhook_details": {
        "token": "my_digital_wallet_token_transition_01",
        "digital_wallet_token": {
          "token": "my_digital_wallet_token_01"
        },
        "type": "fulfillment.requested",
        "channel": "TOKEN_SERVICE_PROVIDER",
        "state": "REQUESTED",
        "fulfillment_status": "DECISION_GREEN",
        "reason": "Token creation",
        "reason_code": "21",
        "created_time": "2025-09-06T22:52:13Z"
      }
    },
    {
      "token": "my_webhook_event_03",
      "event_type": "digitalWalletTokenTransition.terminated",
      "webhook_details": {
        "token": "my_digital_wallet_transition_token_02",
        "digital_wallet_token": {
          "token": "my_digital_wallet_token_02"
        },
        "type": "fulfillment.requested",
        "channel": "TOKEN_SERVICE_PROVIDER",
        "state": "REQUESTED",
        "fulfillment_status": "DECISION_GREEN",
        "reason": "Token creation",
        "reason_code": "21",
        "created_time": "2025-09-06T22:52:13Z"
      }
    }
  ]
}

​Create digital wallet provisioning request for Apple Wallet

​Header parameter

​Request body

​Sample request body

​Response body

​Sample response body

​Create digital wallet provisioning request for Google Wallet

​Header parameter

​Request body

​Sample request body

​Response body

​Sample response body

​Create a digital wallet provisioning request for Google Wallet (UPP)

​Header parameter

​Request body

​Sample request body

​Response body

​Sample response body

​Error responses

​Sample error response body

​Create digital wallet provisioning request for Samsung Wallet

​Header parameter

​Request body

​Sample request body

​Response body

​Sample response body

​List digital wallet tokens

​Header parameter

​URL query parameters

​Response body

​Retrieve digital wallet token

​Header parameter

​URL path parameters

​Response body

​Sample response body

​List digital wallet tokens by card

​Header parameter

​URL path parameters

​URL query parameters

​Response body

​Retrieve digital wallet token with PAN visible

​Header parameter

​URL path parameters

​Response body

​Sample response body

​Create digital wallet token transition

​Header parameter

​Request body

​Sample request body

​Response body

​Sample response body

​List digital wallet token transitions

​Header parameter

​URL path parameters

​URL query parameters

​Response body

​Retrieve digital wallet token transition

​Header parameter

​URL path parameters

​URL query parameters

​Response body

​Sample response body

​Update expiry dates

​Header parameter

​Request body

​Response body

​Transfer digital wallet tokens

​Header parameter

​Request body

​Response body

​Create webhooks

​Header parameter

​URL path parameters

​Sample request body

Create digital wallet provisioning request for Apple Wallet

Header parameter

Request body

Sample request body

Response body

Sample response body

Create digital wallet provisioning request for Google Wallet

Header parameter

Request body

Sample request body

Response body

Sample response body

Create a digital wallet provisioning request for Google Wallet (UPP)

Header parameter

Request body

Sample request body

Response body

Sample response body

Error responses

Sample error response body

Create digital wallet provisioning request for Samsung Wallet

Header parameter

Request body

Sample request body

Response body

Sample response body

List digital wallet tokens

Header parameter

URL query parameters

Response body

Retrieve digital wallet token

Header parameter

URL path parameters

Response body

Sample response body

List digital wallet tokens by card

Header parameter

URL path parameters

URL query parameters

Response body

Retrieve digital wallet token with PAN visible

Header parameter

URL path parameters

Response body

Sample response body

Create digital wallet token transition

Header parameter

Request body

Sample request body

Response body

Sample response body

List digital wallet token transitions

Header parameter

URL path parameters

URL query parameters

Response body

Retrieve digital wallet token transition

Header parameter

URL path parameters

URL query parameters

Response body

Sample response body

Update expiry dates

Header parameter

Request body

Response body

Transfer digital wallet tokens

Header parameter

Request body

Response body

Create webhooks

Header parameter

URL path parameters

Sample request body