/
95 minute read
April 29, 2023

Digital Wallets Management

The Marqeta platform facilitates the use of digital wallets for storing tokenized cards and making payments. The API provides endpoints that enable mobile applications to provision tokens into a digital wallet. It also provides endpoints for retrieving digital wallet tokens and for managing their lifecycle through state transitions.

For an overview of digital wallet tokens, see Digital Wallets and Tokenization.

Create digital wallet token provisioning request for Apple Wallet

Action: POST
Endpoint: /digitalwalletprovisionrequests/applepay

Use this endpoint to return card data for use in provisioning a digital wallet token into Apple Wallet.

The returned card data is encrypted using the digital wallet provider’s encryption key, thereby reducing your PCI compliance overhead.

Request body

Fields Description

card_token

string
Required

Unique identifier of the card resource to use for the provisioning request.

Allowable Values:

1–36 chars

certificates

array of strings
Required

Base64-encoded leaf and sub-CA certificates provided by Apple.

The first element of the array should be the leaf certificate, followed by the sub-CA.

Allowable Values:

An array of one or more certificates provided by Apple

device_type

string
Required

Type of device into which the digital wallet token will be provisioned.

Allowable Values:

MOBILE_PHONE, WATCH, TABLET

nonce

string
Required

One-time-use nonce provided by Apple for security purposes.

Allowable Values:

Base64-encoded nonce from Apple

nonce_signature

string
Required

Apple-provided signature to the nonce.

Allowable Values:

Base64-encoded nonce signature from Apple

provisioning_app_version

string
Required

Version of the application making the provisioning request. Used for debugging and fraud prevention.

Allowable Values:

1–50 chars

Sample request body

JSON
Copied

Is this helpful?

Yes
No

Response body

Fields Description

activation_data

string
Returned

Cryptographic one-time passcode conforming to the payment network operator or service provider specifications.

Allowable Values:

Any value

card_token

string
Returned

Unique identifier of the card resource to use for the provisioning request.

Allowable Values:

1–36 chars

created_time

datetime
Returned

Date and time when the digital wallet provisioning request was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

encrypted_pass_data

string
Returned

Payload encrypted with a shared key derived from the Apple Public Certificates and the generated ephemeral private key.

Allowable Values:

Any value

ephemeral_public_key

string
Returned

Ephemeral public key used for the provisioning attempt.

Allowable Values:

Any value

last_modified_time

datetime
Returned

Date and time when the digital wallet token provisioning request was last updated, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Create digital wallet token provisioning request for Google Wallet

Action: POST
Endpoint: /digitalwalletprovisionrequests/androidpay

Use this endpoint to return card data for use in provisioning a digital wallet token into Google Wallet.

The returned card data is encrypted using the digital wallet provider’s encryption key, thereby reducing your PCI compliance overhead.

Request body

Fields Description

card_token

string
Required

Unique identifier of the card resource to use for the provisioning request.

Allowable Values:

1–36 chars

device_id

string
Required

Unique identifier of the user’s Google device, as provided by Google during the provisioning process.

Allowable Values:

1–24 chars

device_type

string
Required

Type of device into which the digital wallet token will be provisioned.

Allowable Values:

MOBILE_PHONE, TABLET, WATCH

provisioning_app_version

string
Required

Version of the application making the provisioning request. Used for debugging and fraud prevention.

Allowable Values:

1–50 chars

wallet_account_id

string
Required

User’s Google Wallet account ID, as provided by Google during the provisioning process.

Allowable Values:

1–50 chars

Sample request body

JSON
Copied

Is this helpful?

Yes
No

Response body

Fields Description

card_token

string
Returned

Unique identifier of the card resource to use for the provisioning request.

Allowable Values:

1–36 chars

created_time

datetime
Returned

Date and time when the digital wallet provisioning request was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

last_modified_time

datetime
Returned

Date and time when the digital wallet token provisioning request was last updated, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

push_tokenize_request_data

object
Returned

Contains details about a card tokenization push request.

Allowable Values:

card_type, display_name, opaque_payment_card, last_digits, network, token_service_provider

push_tokenize_request_data.display_name

string
Conditionally returned

Name of the card as displayed in the digital wallet, typically showing the card brand and last four digits of the primary account number (PAN). Visa 5678, for example.

Allowable Values:

Any value

push_tokenize_request_data.opaque_payment_card

string
Conditionally returned

Encrypted data field created by the issuer and passed to Google Wallet during the push provisioning process.

Allowable Values:

Any value

push_tokenize_request_data.last_digits

string
Conditionally returned

Last four digits of the primary account number of the physical or virtual card.

Allowable Values:

4 chars

push_tokenize_request_data.network

string
Conditionally returned

Specifies the card network of the physical or virtual card.

Allowable Values:

Visa, Mastercard

push_tokenize_request_data.token_service_provider

string
Conditionally returned

Specifies the network that provides the digital wallet token service.

Allowable Values:

TOKEN_PROVIDER_VISA, TOKEN_PROVIDER_MASTERCARD

push_tokenize_request_data.user_address

object
Conditionally returned

Specifies the cardholder address.

Allowable Values:

name, address1, address2, city, state, postal_code, country, phone

push_tokenize_request_data.user_address.name

string
Returned

Name of the cardholder.

Allowable Values:

Any value

push_tokenize_request_data.user_address.address1

string
Returned

Street address of the cardholder.

Allowable Values:

Any value

push_tokenize_request_data.user_address.address2

string
Returned

Additional address information for the cardholder, such as a suite or apartment number.

Suite 600, for example.

Allowable Values:

Any value

push_tokenize_request_data.user_address.city

string
Returned

City of the cardholder.

Allowable Values:

Any value

push_tokenize_request_data.user_address.state

string
Returned

Two-character state or province code. CA, for example.

Allowable Values:

Any value

push_tokenize_request_data.user_address.postal_code

string
Returned

Postal code of the cardholder, such as a United States ZIP code. 94612, for example.

Allowable Values:

255 char max

push_tokenize_request_data.user_address.country

string
Returned

Two-character ISO alpha-2 country code. US, for example.

Allowable Values:

255 char max

push_tokenize_request_data.user_address.phone

string
Returned

Telephone number of the cardholder.

Allowable Values:

255 char max

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Create digital wallet token provisioning request for Samsung Wallet

Action: POST
Endpoint: /digitalwalletprovisionrequests/samsungpay

Note
This endpoint is limited in availability. For more information, contact your Marqeta representative.

Use this endpoint to return card data for use in provisioning a digital wallet token into Samsung Wallet.

The returned card data is encrypted using the digital wallet provider’s encryption key, thereby reducing your PCI compliance overhead.

Request body

Fields Description

card_token

string
Required

Unique identifier of the card resource to use for the provisioning request.

Allowable Values:

1–36 chars

device_id

string
Required

User’s Samsung device unique identifier, as provided by Samsung during the provisioning process.

Allowable Values:

1–24 chars

device_type

string
Required

Type of device into which the digital wallet token will be provisioned.

Allowable Values:

MOBILE_PHONE, TABLET, WATCH

provisioning_app_version

string
Required

Version of the application making the provisioning request. Used for debugging and fraud prevention.

Allowable Values:

1–50 chars

wallet_user_id

string
Required

User’s Samsung Wallet account ID, as provided by Samsung during the provisioning process.

Allowable Values:

1–50 chars

Response body

Fields Description

card_token

string
Returned

Unique identifier of the card resource to use for the provisioning request.

Allowable Values:

1–36 chars

created_time

datetime
Returned

Date and time when the digital wallet provisioning request was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

last_modified_time

datetime
Returned

Date and time when the digital wallet token provisioning request was last updated, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

push_tokenize_request_data

object
Conditionally returned

Contains details about a card tokenization push request.

Allowable Values:

card_type, display_name, extra_provision_payload, last_digits, network, token_service_provider

push_tokenize_request_data.card_type

string
Conditionally returned

Specifies the type of card.

Allowable Values:

PAYMENT, DEBIT, CREDIT, LOYALTY, GIFT

push_tokenize_request_data.display_name

string
Conditionally returned

Name of the card as displayed in the digital wallet, typically showing the card brand and last four digits of the primary account number (PAN). Visa 5678, for example.

Allowable Values:

Any value

push_tokenize_request_data.extra_provision_payload

string
Conditionally returned

Encrypted card or cardholder details.

Allowable Values:

Any value

push_tokenize_request_data.last_digits

string
Conditionally returned

Last four digits of the primary account number of the physical or virtual card.

Allowable Values:

4 chars

push_tokenize_request_data.network

string
Conditionally returned

Specifies the card network of the physical or virtual card.

Allowable Values:

Visa, Mastercard

push_tokenize_request_data.token_service_provider

string
Conditionally returned

Specifies the network that provides the digital wallet token service, as determined by the Samsung Wallet library.

Allowable Values:

VI, MC

Create digital wallet token provisioning request for XPay

Action: POST
Endpoint: /digitalwalletprovisionrequests/xpay

Note
This endpoint is limited in availability. For more information, contact your Marqeta representative.

Use this endpoint to return card data for use in provisioning a digital wallet token into an XPay digital wallet.

The returned card data is encrypted using the digital wallet provider’s encryption key, thereby reducing your PCI compliance overhead.

Request body

Fields Description

card_token

string
Required

Unique identifier of the card resource to use for the provisioning request.

Allowable Values:

1–36 chars

device_id

string
Required

Unique identifier of the user’s XPay device, as provided by XPay during the provisioning process.

Allowable Values:

1–24 chars

device_type

string
Required

Type of device into which the digital wallet token will be provisioned.

Allowable Values:

MOBILE_PHONE, TABLET, WATCH

provisioning_app_version

string
Required

Version of the application making the provisioning request. Used for debugging and fraud prevention.

Allowable Values:

1–50 chars

token_requestor_id

string
Required

Unique numerical identifier of the digital wallet token requestor within the card network. These ID numbers map to token_requestor_name field values as follows:

Mastercard

  • 50110030273 – APPLE_PAY

  • 50120834693 – ANDROID_PAY

  • 50139059239 – SAMSUNG_PAY

Visa

  • 40010030273 – APPLE_PAY

  • 40010075001 – ANDROID_PAY

  • 40010043095 – SAMSUNG_PAY

  • 40010075196 – MICROSOFT_PAY

  • 40010075338 – VISA_CHECKOUT

  • 40010075449 – FACEBOOK

  • 40010075839 – NETFLIX

  • 40010077056 – FITBIT_PAY

  • 40010069887 – GARMIN_PAY

Allowable Values:

11 char max

Example Values:

  • Mastercard – 50110030273, 50120834693, 50139059239

  • Visa – 40010030273, 40010075001, 40010075338, 40010075449, 40010075839, 40010043095

wallet_account_id

string
Required

User’s XPay account identifier, as provided by XPay during the provisioning process.

Allowable Values:

1–50 chars

Response body

Fields Description

card_token

string
Returned

Unique identifier of the card resource to use for the provisioning request.

Allowable Values:

1–36 chars

created_time

datetime
Returned

Date and time when the digital wallet provisioning request was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

last_modified_time

datetime
Returned

Date and time when the digital wallet token provisioning request was last updated, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

push_tokenize_request_data

object
Conditionally returned

Contains details about a card tokenization push request.

Allowable Values:

card_type, display_name, extra_provision_payload, last_digits, network, token_service_provider

push_tokenize_request_data.card_type

string
Conditionally returned

Specifies the type of card.

Allowable Values:

PAYMENT, DEBIT, CREDIT, LOYALTY, GIFT

push_tokenize_request_data.display_name

string
Conditionally returned

Name of the card as displayed in the digital wallet, typically showing the card brand and last four digits of the primary account number (PAN). Visa 5678, for example.

Allowable Values:

Any value

push_tokenize_request_data.extra_provision_payload

string
Conditionally returned

Encrypted card or cardholder details.

Allowable Values:

Any value

push_tokenize_request_data.last_digits

string
Conditionally returned

Last four digits of the primary account number of the physical or virtual card.

Allowable Values:

4 chars

push_tokenize_request_data.network

string
Conditionally returned

Specifies the card network of the physical or virtual card.

Allowable Values:

Visa, Mastercard

push_tokenize_request_data.token_service_provider

string
Conditionally returned

Specifies the network that provides the digital wallet token service.

Allowable Values:

TOKEN_PROVIDER_VISA, TOKEN_PROVIDER_MASTERCARD

Create digital wallet token transition

Action: POST
Endpoint: /digitalwallettokentransitions

Use this endpoint to transition a digital wallet token from one state to another.

Request body

Fields Description

channel

string
Optional

Mechanism by which the transition was initiated.

Allowable Values:

TOKEN_SERVICE_PROVIDER, TOKEN_SERVICE_PROVIDER_API, DIGITAL_WALLET, API, IVR, FRAUD, ADMIN, SYSTEM

digital_wallet_token

object
Required

Contains identifiers of the digital wallet token resource and the card resource.

Allowable Values:

Unique identifiers of the digital wallet token resource and the card resource

digital_wallet_token.token

string
Required

Unique identifier of the digital wallet token resource.

Allowable Values:

1–36 chars

digital_wallet_token.card_token

string
Optional

Unique identifier of the card resource to use for the provisioning request.

Allowable Values:

1–36 chars

reason

string
Optional

The reason for the transition.

Allowable Values:

255 char max

reason_code

string
Optional

Standard code describing the reason for the transition.

NOTE: This field is required if your program uses v2 of the user_card_state_version, which is a program-specific configuration value that is managed by Marqeta and cannot be accessed via the API. To learn more about the user_card_state_version program configuration, contact your Marqeta representative.

  • 00: Object activated for the first time

  • 01: Requested by you

  • 02: Inactivity over time

  • 03: This address cannot accept mail or the addressee is unknown

  • 04: Negative account balance

  • 05: Account under review

  • 06: Suspicious activity was identified

  • 07: Activity outside the program parameters was identified

  • 08: Confirmed fraud was identified

  • 09: Matched with an Office of Foreign Assets Control list

  • 10: Card was reported lost

  • 11: Card information was cloned

  • 12: Account or card information was compromised

  • 13: Temporary status change while on hold/leave

  • 14: Initiated by Marqeta

  • 15: Initiated by issuer

  • 16: Card expired

  • 17: Failed KYC

  • 18: Changed to ACTIVE because information was properly validated

  • 19: Changed to ACTIVE because account activity was properly validated

  • 20: Change occurred prior to the normalization of reason codes

  • 21: Initiated by a third party, often a digital wallet provider

  • 22: PIN retry limit reached

  • 23: Card was reported stolen

  • 24: Address issue

  • 25: Name issue

  • 26: SSN issue

  • 27: DOB issue

  • 28: Email issue

  • 29: Phone issue

  • 30: Account/fulfillment mismatch

  • 31: Other reason

Allowable Values:

00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31

state

string
Required

Specifies the state to which the digital wallet token will transition.

The original state is REQUESTED. You cannot modify the state if its current value is either REQUEST_DECLINED or TERMINATED.

Allowable Values:

ACTIVE, SUSPENDED, TERMINATED

token

string
Optional

The unique identifier of the digital wallet token transition (not the identifier of the digital wallet token itself).

If you do not include a value for the token field, the system will generate one automatically. This value is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.

Allowable Values:

1–36 chars

token_reference_id

string
Optional

The unique identifier of the digital wallet token within the card network. The token_reference_id is unique at the card network level.

Allowable Values:

255 char max

Sample request body

JSON
Copied

Is this helpful?

Yes
No

Response body

Fields Description

card_swap

object
Conditionally returned

Contains identifiers for swapping digital wallet tokens between cards.

Allowable Values:

new_card_token, previous_card_token

card_swap.new_card_token

string
Returned

Unique identifier of the new card resource to which the digital wallet tokens are assigned.

Allowable Values:

1–36 chars

card_swap.previous_card_token

string
Returned

Unique identifier of the existing card resource that has digital wallet tokens assigned to it.

Allowable Values:

1–36 chars

channel

string
Returned

Mechanism by which the transition was initiated.

Allowable Values:

TOKEN_SERVICE_PROVIDER, DIGITAL_WALLET, API, IVR, FRAUD, ADMIN, SYSTEM, TOKEN_SERVICE_PROVIDER_API

created_time

datetime
Conditionally returned

Date and time when the digital wallet provisioning request was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

digital_wallet_token

object
Returned

Contains identifiers of the digital wallet token resource and the card resource.

Allowable Values:

Unique identifiers of the digital wallet token resource and the card resource

digital_wallet_token.token

string
Returned

Unique identifier of the digital wallet token resource.

Allowable Values:

1–36 chars

digital_wallet_token.card_token

string
Conditionally returned

Unique identifier of the card resource to use for the provisioning request.

Allowable Values:

1–36 chars

fulfillment_status

string
Returned

Provisioning status of the digital wallet token.

Allowable Values:

DECISION_RED, DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED

reason

string
Conditionally returned

Reason for the transition.

Allowable Values:

255 char max

reason_code

string
Conditionally returned

Standard code describing the reason for the transition:

  • 00: Object activated for the first time

  • 01: Requested by you

  • 02: Inactivity over time

  • 03: This address cannot accept mail or the addressee is unknown

  • 04: Negative account balance

  • 05: Account under review

  • 06: Suspicious activity was identified

  • 07: Activity outside the program parameters was identified

  • 08: Confirmed fraud was identified

  • 09: Matched with an Office of Foreign Assets Control list

  • 10: Card was reported lost

  • 11: Card information was cloned

  • 12: Account or card information was compromised

  • 13: Temporary status change while on hold/leave

  • 14: Initiated by Marqeta

  • 15: Initiated by issuer

  • 16: Card expired

  • 17: Failed KYC

  • 18: Changed to ACTIVE because information was properly validated

  • 19: Changed to ACTIVE because account activity was properly validated

  • 20: Change occurred prior to the normalization of reason codes

  • 21: Initiated by a third party, often a digital wallet provider

  • 22: PIN retry limit reached

  • 23: Card was reported stolen

  • 24: Address issue

  • 25: Name issue

  • 26: SSN issue

  • 27: DOB issue

  • 28: Email issue

  • 29: Phone issue

  • 30: Account/fulfillment mismatch

  • 31: Other reason

Allowable Values:

00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31

state

string
Returned

Specifies the state to which the digital wallet token is transitioning.

Allowable Values:

REQUESTED, REQUEST_DECLINED, ACTIVE, SUSPENDED, TERMINATED

token

string
Returned

Unique identifier of the digital wallet token transition, and not the identifier of the digital wallet token itself.

Allowable Values:

1–36 chars

type

string
Returned

Type of digital wallet token transition. state.activated, for example.

Allowable Values:

36 char max

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Retrieve digital wallet token transition

Action: GET
Endpoint: /digitalwallettokentransitions/{token}

Use this endpoint to retrieve a specific digital wallet token transition.

This endpoint supports field filtering.

URL path parameters

Fields Description

token

string
Required

Unique identifier of the digital wallet token (DWT) transition.

Allowable Values:

Existing DWT transition token

URL query parameters

Fields Description

fields

string
Optional

Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.

Allowable Values:

Comma-delimited list of fields, or blank

Response body

Fields Description

card_swap

object
Conditionally returned

Contains identifiers for swapping digital wallet tokens between cards.

Allowable Values:

new_card_token, previous_card_token

card_swap.new_card_token

string
Returned

Unique identifier of the new card resource to which the digital wallet tokens are assigned.

Allowable Values:

1–36 chars

card_swap.previous_card_token

string
Returned

Unique identifier of the existing card resource that has digital wallet tokens assigned to it.

Allowable Values:

1–36 chars

channel

string
Returned

Mechanism by which the transition was initiated.

Allowable Values:

TOKEN_SERVICE_PROVIDER, DIGITAL_WALLET, API, IVR, FRAUD, ADMIN, SYSTEM, TOKEN_SERVICE_PROVIDER_API

created_time

datetime
Conditionally returned

Date and time when the digital wallet provisioning request was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

digital_wallet_token

object
Returned

Contains identifiers of the digital wallet token resource and the card resource.

Allowable Values:

Unique identifiers of the digital wallet token resource and the card resource

digital_wallet_token.token

string
Returned

Unique identifier of the digital wallet token resource.

Allowable Values:

1–36 chars

digital_wallet_token.card_token

string
Conditionally returned

Unique identifier of the card resource to use for the provisioning request.

Allowable Values:

1–36 chars

fulfillment_status

string
Returned

Provisioning status of the digital wallet token.

Allowable Values:

DECISION_RED, DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED

reason

string
Conditionally returned

Reason for the transition.

Allowable Values:

255 char max

reason_code

string
Conditionally returned

Standard code describing the reason for the transition:

  • 00: Object activated for the first time

  • 01: Requested by you

  • 02: Inactivity over time

  • 03: This address cannot accept mail or the addressee is unknown

  • 04: Negative account balance

  • 05: Account under review

  • 06: Suspicious activity was identified

  • 07: Activity outside the program parameters was identified

  • 08: Confirmed fraud was identified

  • 09: Matched with an Office of Foreign Assets Control list

  • 10: Card was reported lost

  • 11: Card information was cloned

  • 12: Account or card information was compromised

  • 13: Temporary status change while on hold/leave

  • 14: Initiated by Marqeta

  • 15: Initiated by issuer

  • 16: Card expired

  • 17: Failed KYC

  • 18: Changed to ACTIVE because information was properly validated

  • 19: Changed to ACTIVE because account activity was properly validated

  • 20: Change occurred prior to the normalization of reason codes

  • 21: Initiated by a third party, often a digital wallet provider

  • 22: PIN retry limit reached

  • 23: Card was reported stolen

  • 24: Address issue

  • 25: Name issue

  • 26: SSN issue

  • 27: DOB issue

  • 28: Email issue

  • 29: Phone issue

  • 30: Account/fulfillment mismatch

  • 31: Other reason

Allowable Values:

00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31

state

string
Returned

Specifies the state to which the digital wallet token is transitioning.

Allowable Values:

REQUESTED, REQUEST_DECLINED, ACTIVE, SUSPENDED, TERMINATED

token

string
Returned

Unique identifier of the digital wallet token transition, and not the identifier of the digital wallet token itself.

Allowable Values:

1–36 chars

type

string
Returned

Type of digital wallet token transition. state.activated, for example.

Allowable Values:

36 char max

Sample response body

JSON
Copied

Is this helpful?

Yes
No

List transitions for digital wallet token

Action: GET
Endpoint: /digitalwallettokentransitions/digitalwallettoken/{token}

Use this endpoint to return an array of all transitions for a particular digital wallet token.

This endpoint supports field filtering, pagination, and sorting.

URL path parameters

Fields Description

token

string
Required

Unique identifier of the digital wallet token (DWT).

Allowable Values:

Existing DWT token

URL query parameters

Fields Description

count

integer
Optional

Number of digital wallet transitions to retrieve.

Allowable Values:

Any integer

Default value:
5

start_index

integer
Optional

The sort order index of the first digital wallet token in the returned array.

Allowable Values:

Any integer

Default value:
0

fields

string
Optional

Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.

Allowable Values:

Comma-delimited list of fields, or blank

sort_by

string
Optional

Field on which to sort. Use any field in the resource model, or one of the system fields lastModifiedTime or createdTime. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.

Allowable Values:

createdTime, lastModifiedTime, or any field in the resource model

Default value:
-id

Response body

Fields Description

count

integer
Conditionally returned

Number of resources returned.

This field is returned if there are resources in your returned array.

Allowable Values:

Any integer

data

array of objects
Conditionally returned

Array of digital wallet token transition resources.

Resources are returned as appropriate to your query.

Allowable Values:

One or more digital wallet token transition resources

data[].card_swap

object
Conditionally returned

Contains identifiers for swapping digital wallet tokens between cards.

Allowable Values:

new_card_token, previous_card_token

data[].card_swap.new_card_token

string
Returned

Unique identifier of the new card resource to which the digital wallet tokens are assigned.

Allowable Values:

1–36 chars

data[].card_swap.previous_card_token

string
Returned

Unique identifier of the existing card resource that has digital wallet tokens assigned to it.

Allowable Values:

1–36 chars

data[].channel

string
Returned

Mechanism by which the transition was initiated.

Allowable Values:

TOKEN_SERVICE_PROVIDER, DIGITAL_WALLET, API, IVR, FRAUD, ADMIN, SYSTEM, TOKEN_SERVICE_PROVIDER_API

data[].created_time

datetime
Conditionally returned

Date and time when the digital wallet provisioning request was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

data[].digital_wallet_token

object
Returned

Contains identifiers of the digital wallet token resource and the card resource.

Allowable Values:

Unique identifiers of the digital wallet token resource and the card resource

data[].digital_wallet_token.token

string
Returned

Unique identifier of the digital wallet token resource.

Allowable Values:

1–36 chars

data[].digital_wallet_token.card_token

string
Conditionally returned

Unique identifier of the card resource to use for the provisioning request.

Allowable Values:

1–36 chars

data[].fulfillment_status

string
Returned

Provisioning status of the digital wallet token.

Allowable Values:

DECISION_RED, DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED

data[].reason

string
Conditionally returned

Reason for the transition.

Allowable Values:

255 char max

data[].reason_code

string
Conditionally returned

Standard code describing the reason for the transition:

  • 00: Object activated for the first time

  • 01: Requested by you

  • 02: Inactivity over time

  • 03: This address cannot accept mail or the addressee is unknown

  • 04: Negative account balance

  • 05: Account under review

  • 06: Suspicious activity was identified

  • 07: Activity outside the program parameters was identified

  • 08: Confirmed fraud was identified

  • 09: Matched with an Office of Foreign Assets Control list

  • 10: Card was reported lost

  • 11: Card information was cloned

  • 12: Account or card information was compromised

  • 13: Temporary status change while on hold/leave

  • 14: Initiated by Marqeta

  • 15: Initiated by issuer

  • 16: Card expired

  • 17: Failed KYC

  • 18: Changed to ACTIVE because information was properly validated

  • 19: Changed to ACTIVE because account activity was properly validated

  • 20: Change occurred prior to the normalization of reason codes

  • 21: Initiated by a third party, often a digital wallet provider

  • 22: PIN retry limit reached

  • 23: Card was reported stolen

  • 24: Address issue

  • 25: Name issue

  • 26: SSN issue

  • 27: DOB issue

  • 28: Email issue

  • 29: Phone issue

  • 30: Account/fulfillment mismatch

  • 31: Other reason

Allowable Values:

00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31

data[].state

string
Returned

Specifies the state to which the digital wallet token is transitioning.

Allowable Values:

REQUESTED, REQUEST_DECLINED, ACTIVE, SUSPENDED, TERMINATED

data[].token

string
Returned

Unique identifier of the digital wallet token transition, and not the identifier of the digital wallet token itself.

Allowable Values:

1–36 chars

data[].type

string
Returned

Type of digital wallet token transition. state.activated, for example.

Allowable Values:

36 char max

end_index

integer
Conditionally returned

Sort order index of the last resource in the returned array.

This field is returned if there are resources in your returned array.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist. A value of false indicates that no more unreturned resources exist.

This field is returned if there are resources in your returned array.

Allowable Values:

true, false

start_index

integer
Conditionally returned

Sort order index of the first resource in the returned array.

This field is returned if there are resources in your returned array.

Allowable Values:

Any integer

Sample response body

JSON
Copied

Is this helpful?

Yes
No

List digital wallet tokens

Action: GET
Endpoint: /digitalwallettokens

Use this endpoint to retrieve a list of digital wallet tokens.

URL query parameters

Fields Description

count

integer
Optional

Number of digital wallet token resources to retrieve.

Allowable Values:

Any integer

Default value:
10

start_index

integer
Optional

Sort order index of the first digital wallet token resource in the returned array.

Allowable Values:

Any integer

Default value:
0

fields

string
Optional

Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.

Allowable Values:

Comma-delimited list of fields, or blank

sort_by

string
Optional

Field on which to sort. Use any field in the resource model, or one of the system fields lastModifiedTime or createdTime. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.

Allowable Values:

createdTime, lastModifiedTime, or any field in the resource model

Default value:
-createdTime

start_date

string
Optional

Date when the digital wallet token becomes active.

Allowable Values:

Format: yyyy-MM-dd

end_date

string
Optional

Expiration date of the digital wallet token.

Allowable Values:

Format: yyyy-MM-dd

pan_reference_id

string
Optional

Unique identifier of the digital wallet token primary account number (PAN) within the card network. This value may vary, depending on the digital wallet. For example, the pan_reference_id may be different in Apple Wallet and Google Wallet for the same digital wallet token.

Allowable Values:

255 char max

token_reference_id

string
Optional

Unique identifier of the digital wallet token within the card network. The token_reference_id is unique at the card network level.

Allowable Values:

255 char max

correlation_id

string
Optional

Unique value representing a tokenization request (Mastercard only).

Allowable Values:

255 char max

token_type

string
Optional

Comma-delimited list of digital wallet token types to display.

Allowable Values:

255 char max

Example Values: DEVICE_SECURE_ELEMENT, MERCHANT_CARD_ON_FILE, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET, PSEUDO_ACCOUNT.

token_requestor_name

string
Optional

Name of the token requestor within the card network.

NOTE: The list of example values for this field is maintained by the card networks and is subject to change.

Allowable Values:

255 char max

Example Values:

  • MastercardAPPLE_PAY, ANDROID_PAY, SAMSUNG_PAY

  • VisaAPPLE_PAY, ANDROID_PAY, SAMSUNG_PAY, MICROSOFT_PAY, VISA_CHECKOUT, FACEBOOK, NETFLIX, FITBIT_PAY, GARMIN_PAY

state

string
Optional

Comma-delimited list of digital wallet token states to display.

Allowable Values:

255 char max

Example Values: REQUESTED, REQUEST_DECLINED, TERMINATED, SUSPENDED, ACTIVE

embed

string
Optional

An optional embedded user object.

Allowable Values:

user

Response body

Fields Description

count

integer
Conditionally returned

Number of resources returned.

This field is returned if there are resources in your returned array.

Allowable Values:

Any integer

data

array of objects
Conditionally returned

Array of digital wallet token resources.

Resources are returned as appropriate to your query.

Allowable Values:

Valid array of one or more digital wallet token resources

data[].address_verification

object
Conditionally returned

Contains address verification information.

Allowable Values:

name, postal_code, street_address, zip

data[].address_verification.name

string
Conditionally returned

Name of the cardholder.

Allowable Values:

40 char max

data[].address_verification.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

data[].address_verification.street_address

string
Conditionally returned

Street address provided by the cardholder.

Allowable Values:

40 char max

data[].address_verification.zip

string
Conditionally returned

United States ZIP code.

Allowable Values:

10 char max

data[].card_token

string
Conditionally returned

Unique identifier of the card.

Allowable Values:

Existing card token

data[].created_time

datetime
Conditionally returned

Date and time when the digital wallet token object was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

data[].device

object
Conditionally returned

Contains information related to the device being provisioned.

Allowable Values:

device_id, ip_address, language_code, location, name, phone_number, token, type

data[].device.device_id

string
Conditionally returned

Identity number of the device.

Allowable Values:

20 char max

data[].device.ip_address

string
Conditionally returned

Device’s IP address.

Allowable Values:

IP address format, 50 char max

data[].device.language_code

string
Conditionally returned

Language the device is configured to use.

Allowable Values:

50 char max

data[].device.location

string
Conditionally returned

Geographic coordinates of the device.

Allowable Values:

Latitude and longitude in DDD.DD/DDD.DD format.

NOTE: Both the longitude and latitude are prefixed with either a + or - symbol, for example: +42.29/-71.07.

data[].device.name

string
Conditionally returned

Name of the device.

Allowable Values:

50 char max

data[].device.phone_number

string
Conditionally returned

Device’s telephone number.

Allowable Values:

50 char max

data[].device.token

string
Conditionally returned

Unique identifier of the device object.

Allowable Values:

36 char max

data[].device.type

string
Conditionally returned

Type of device being provisioned.

Allowable Values:

MOBILE_PHONE, WATCH, TABLET, MOBILE_PHONE_OR_TABLET, VEHICLE, APPLIANCE, LAPTOP, GAMING_DEVICE, UNKNOWN

data[].fulfillment_status

string
Conditionally returned

Digital wallet token’s provisioning status.

For fulfillment status descriptions, see Create digital wallet token transition.

Allowable Values:

DECISION_RED, DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED

data[].issuer_eligibility_decision

string
Conditionally returned

The Marqeta platform’s decision as to whether the digital wallet token should be provisioned.

  • 0000 – The token should be provisioned.

  • token.activation.verification.required – Provisioning is pending; further action is required for completion.

For all other values, check the value of the fulfillment_status field to definitively ascertain the provisioning outcome.

NOTE: The value invalid.cid indicates an invalid CVV2 number.

Allowable Values:

0000, cardaccount.verified, card.suspicious, token.activation.verification.required, token.activation-request.decline, card.not.active, invalid.cid, card.expired, card.suspended, cardholder.not.active

data[].last_modified_time

datetime
Conditionally returned

Date and time when the digital wallet token object was last modified, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

data[].metadata

object
Conditionally returned

Contains additional information about the digital wallet token.

Allowable Values:

cardproduct_preferred_notification_language, issuer_product_config_id

data[].metadata.cardproduct_preferred_notification_language

string
Conditionally returned

Language specified in the config.transaction_controls.notification_language field of the card product: ces (Czech), deu (German), eng (English), fra (French), ita (Italian), pol (Polish), spa (Spanish), swe (Swedish)

Allowable Values:

ces, deu, eng, fra, ita, pol, spa, swe

data[].metadata.issuer_product_config_id

string
Conditionally returned

Unique identifier of the product configuration on the Marqeta platform.

Allowable Values:

255 char max

data[].state

string
Conditionally returned

State of the digital wallet token.

For state descriptions, see Transitioning Token States.

Allowable Values:

REQUESTED, REQUEST_DECLINED, ACTIVE, SUSPENDED, TERMINATED

data[].state_reason

string
Conditionally returned

Reason why the digital wallet token transitioned to its current state.

Allowable Values:

255 char max

data[].token

string
Conditionally returned

Unique identifier of the digital wallet token.

Allowable Values:

Existing digital wallet token.

data[].token_service_provider

object
Conditionally returned

Contains information held and provided by the token service provider (card network).

Allowable Values:

correlation_id, pan_reference_id, token_assurance_level, token_eligibility_decision, token_expiration, token_pan, token_reference_id, token_requestor_id, token_requestor_name, token_score, token_type

data[].token_service_provider.correlation_id

string
Conditionally returned

Unique value representing a tokenization request (Mastercard only).

Allowable Values:

Existing correlation identifier

data[].token_service_provider.pan_reference_id

string
Returned

Unique identifier of the digital wallet token primary account number (PAN) within the card network.

Allowable Values:

Existing PAN Reference ID

data[].token_service_provider.token_assurance_level

string
Conditionally returned

(Mastercard only) Represents the confidence level in the digital wallet token.

Allowable Values:

0-99

data[].token_service_provider.token_eligibility_decision

string
Conditionally returned

Digital wallet’s decision as to whether the digital wallet token should be provisioned.

Allowable Values:

DECISION_RED, DECISION_YELLOW, DECISION_GREEN

data[].token_service_provider.token_expiration

string
Conditionally returned

Expiration date of the digital wallet token.

Allowable Values:

Format: MMyy

data[].token_service_provider.token_pan

string
Conditionally returned

Primary account number (PAN) of the digital wallet token.

Allowable Values:

16 char max

data[].token_service_provider.token_reference_id

string
Conditionally returned

Unique identifier of the digital wallet token within the card network.

Allowable Values:

Existing Token Reference ID

data[].token_service_provider.token_requestor_id

string
Conditionally returned

Unique numerical identifier of the token requestor within the card network. These ID numbers map to token_requestor_name field values as follows:

Mastercard

  • 50110030273 – APPLE_PAY

  • 50120834693 – ANDROID_PAY

  • 50139059239 – SAMSUNG_PAY

Visa

  • 40010030273 – APPLE_PAY

  • 40010075001 – ANDROID_PAY

  • 40010043095 – SAMSUNG_PAY

  • 40010075196 – MICROSOFT_PAY

  • 40010075338 – VISA_CHECKOUT

  • 40010075449 – FACEBOOK

  • 40010075839 – NETFLIX

  • 40010077056 – FITBIT_PAY

  • 40010069887 – GARMIN_PAY

Allowable Values:

11 char max

Example Values:

  • Mastercard – 50110030273, 50120834693, 50139059239

  • Visa – 40010030273, 40010075001, 40010075338, 40010075449, 40010075839, 40010043095

data[].token_service_provider.token_requestor_name

string
Conditionally returned

Name of the token requestor within the card network.

NOTE: The list of example values for this field is maintained by the card networks and is subject to change.

Allowable Values:

255 char max

Example Values:

  • MastercardAPPLE_PAY, ANDROID_PAY, SAMSUNG_PAY

  • VisaAPPLE_PAY, ANDROID_PAY, SAMSUNG_PAY, MICROSOFT_PAY, VISA_CHECKOUT, FACEBOOK, NETFLIX, FITBIT_PAY, GARMIN_PAY

data[].token_service_provider.token_score

string
Conditionally returned

Token score assigned by the digital wallet.

Allowable Values:

25 char max

data[].token_service_provider.token_type

string
Conditionally returned

Type of the digital wallet token.

Allowable Values:

MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET

data[].user

object
Conditionally returned

Contains information about a cardholder.

Allowable Values:

account_holder_group_token, active, address1, address2, authentication, birth_date, business_token, city, company, corporate_card_holder, country, created_time, email, first_name, gender, honorific, id_card_expiration_date, id_card_number, identifications, ip_address, last_modified_time, last_name, metadata, middle_name, nationality, notes, parent_token, passport_expiration_date, passport_number, password, phone, postal_code, ssn, state, status, token, uses_parent_account, zip

data[].user.account_holder_group_token

string
Conditionally returned

Associates the specified account holder group with the cardholder.

Allowable Values:

36 char max

data[].user.active

boolean
Conditionally returned

Specifies if the cardholder is in the ACTIVE state on the Marqeta platform.

Allowable Values:

true, false

data[].user.address1

string
Conditionally returned

Cardholder’s address.

Allowable Values:

255 char max

data[].user.address2

string
Conditionally returned

Additional address information for the cardholder.

Allowable Values:

255 char max

data[].user.authentication

object
Conditionally returned

Contains the cardholder’s email address and password information.

Allowable Values:

email_verified, email_verified_time, last_password_update_channel, last_password_update_time

data[].user.authentication.email_verified

boolean
Conditionally returned

Specifies whether the email address has been verified.

Allowable Values:

true, false

data[].user.authentication.email_verified_time

datetime
Conditionally returned

Date and time when the email address was verified.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

data[].user.authentication.last_password_update_channel

string
Conditionally returned

Specifies the channel through which the password was last changed.

Allowable Values:

USER_CHANGE, USER_RESET

data[].user.authentication.last_password_update_time

datetime
Conditionally returned

Date and time when the password was last changed.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

data[].user.birth_date

string
Conditionally returned

Cardholder’s date of birth.

Allowable Values:

Format: yyyy-MM-dd

data[].user.business_token

string
Conditionally returned

Unique identifier of the business resource.

Allowable Values:

Existing business resource token

data[].user.city

string
Conditionally returned

City where the cardholder resides.

Allowable Values:

40 char max

data[].user.company

string
Conditionally returned

Company name.

Allowable Values:

255 char max

data[].user.corporate_card_holder

boolean
Conditionally returned

Specifies if the cardholder holds a corporate card.

Allowable Values:

true, false

data[].user.country

string
Conditionally returned

Country where the cardholder resides.

Allowable Values:

40 char max

data[].user.created_time

datetime
Returned

Date and time when the resource was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

data[].user.email

string
Conditionally returned

Valid email address of the cardholder.

Allowable Values:

1–255 chars

data[].user.first_name

string
Conditionally returned

Cardholder’s first name.

Allowable Values:

40 char max

data[].user.gender

string
Conditionally returned

Gender of the cardholder.

Allowable Values:

F, M

data[].user.honorific

string
Conditionally returned

Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on.

Allowable Values:

10 char max

data[].user.id_card_expiration_date

string
Conditionally returned

Expiration date of the cardholder’s identification.

Allowable Values:

Format: yyyy-MM-dd

data[].user.id_card_number

string
Conditionally returned

Cardholder’s identification card number.

Allowable Values:

255 char max

data[].user.identifications

array of objects
Conditionally returned

One or more objects containing identifications associated with the cardholder.

Allowable Values:

Valid array of one or more identifications objects

data[].user.identifications[].expiration_date

string
Conditionally returned

Expiration date for the identification, if applicable.

Allowable Values:

Format: yyyy-MM-dd

data[].user.identifications[].type

string
Conditionally returned

Type of identification.

Allowable Values:

SSN, TIN, SIN, NIN, PASSPORT_NUMBER, DRIVERS_LICENSE, BUSINESS_NUMBER, BUSINESS_TAX_ID, TAXPAYER_REFERENCE

data[].user.identifications[].value

string
Conditionally returned

Number associated with the identification.

Allowable Values:

255 char max

data[].user.ip_address

string
Conditionally returned

Cardholder’s IP address.

Allowable Values:

39 char max

data[].user.last_modified_time

datetime
Returned

Date and time when the resource was last updated, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

data[].user.last_name

string
Conditionally returned

Cardholder’s last name.

Allowable Values:

40 char max

data[].user.metadata

object
Conditionally returned

Associates any additional metadata you provide with the cardholder.

Allowable Values:

You can define the names and values of up to 20 fields in the format "my_name_1": "my_value_1"

data[].user.middle_name

string
Conditionally returned

Cardholder’s middle name.

Allowable Values:

40 char max

data[].user.nationality

string
Conditionally returned

Cardholder’s nationality.

Allowable Values:

255 char max

data[].user.notes

string
Conditionally returned

Any additional information pertaining to the cardholder.

Allowable Values:

255 char max

data[].user.parent_token

string
Conditionally returned

Unique identifier of the parent user or business resource.

Allowable Values:

1–36 chars

data[].user.passport_expiration_date

string
Conditionally returned

Expiration date of the cardholder’s passport.

Allowable Values:

Format: yyyy-MM-dd

data[].user.passport_number

string
Conditionally returned

Cardholder’s passport number.

Allowable Values:

40 char max

data[].user.password

string
Conditionally returned

Password to the cardholder’s user account on the Marqeta platform.

Allowable Values:

1–255 chars

data[].user.phone

string
Conditionally returned

Cardholder’s telephone number.

Allowable Values:

255 char max

data[].user.postal_code

string
Conditionally returned

Postal code of the cardholder’s address.

Allowable Values:

10 char max

data[].user.ssn

string
Conditionally returned

Cardholder’s Social Security Number (SSN).

Allowable Values:

Nine digits only, no delimiters.

data[].user.state

string
Conditionally returned

State or province where the cardholder resides.

Allowable Values:

2 char max

data[].user.status

string
Conditionally returned

Specifies the status of the cardholder on the Marqeta platform.

Allowable Values:

UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED

data[].user.token

string
Conditionally returned

Unique identifier of the cardholder.

Allowable Values:

1–36 chars

data[].user.uses_parent_account

boolean
Conditionally returned

Indicates whether the child shares balances with the parent (true), or the child’s balances are independent of the parent (false).

Allowable Values:

true, false

data[].user.zip

string
Conditionally returned

United States ZIP code of the cardholder’s address.

Allowable Values:

10 char max

data[].wallet_provider_profile

object
Conditionally returned

Contains information held and provided by the digital wallet provider.

Allowable Values:

account, device_score, pan_source, reason_code, recommendation_reasons, risk_assessment

data[].wallet_provider_profile.account

object
Conditionally returned

Contains information related to the cardholder and provided by the digital wallet provider.

Allowable Values:

email_address, id, score

data[].wallet_provider_profile.account.email_address

string
Conditionally returned

Digital wallet provider’s email address for the cardholder.

Allowable Values:

255 char max

data[].wallet_provider_profile.account.id

string
Conditionally returned

Digital wallet provider’s identity number for the cardholder.

Allowable Values:

20 char max

data[].wallet_provider_profile.account.score

string
Conditionally returned

Score from the digital wallet provider.

Allowable Values:

50 char max

data[].wallet_provider_profile.device_score

string
Conditionally returned

Score from the device.

Allowable Values:

50 char max

data[].wallet_provider_profile.pan_source

string
Conditionally returned

Source from which the digital wallet provider obtained the card primary account number (PAN).

Allowable Values:

KEY_ENTERED, ON_FILE, MOBILE_BANKING_APP

data[].wallet_provider_profile.reason_code

string
Conditionally returned

Reason for the wallet provider’s provisioning decision.

  • 01 – Cardholder’s wallet account is too new relative to launch.

  • 02 – Cardholder’s wallet account is too new relative to provisioning request.

  • 03 – Cardholder’s wallet account/card pair is newer than date threshold.

  • 04 – Changes made to account data within the account threshold.

  • 05 – Suspicious transactions linked to this account.

  • 06 – Account has not had activity in the last year.

  • 07 – Suspended cards in the secure element.

  • 08 – Device was put in lost mode in the last seven days for longer than the duration threshold.

  • 09 – The number of provisioning attempts on this device in 24 hours exceeds threshold.

  • 0A – There have been more than the threshold number of different cards attempted at provisioning to this phone in 24 hours.

  • 0B – The card provisioning attempt contains a distinct name in excess of the threshold.

  • 0C – The device score is less than 3.

  • 0D – The account score is less than 4.

  • 0E – Device provisioning location outside of the cardholder’s wallet account home country.

  • 0G – Suspect fraud.

Allowable Values:

01, 02, 03, 04, 05, 06, 07, 08, 09, 0A, 0B, 0C, 0D, 0E, 0G

data[].wallet_provider_profile.recommendation_reasons

array of strings
Conditionally returned

Array of recommendation reasons from the digital wallet provider.

Allowable Values:

Valid array of one or more recommendation reasons

data[].wallet_provider_profile.risk_assessment

object
Conditionally returned

Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token.

Allowable Values:

score, version

data[].wallet_provider_profile.risk_assessment.score

string
Conditionally returned

Wallet provider’s decision as to whether the digital wallet token should be provisioned.

Allowable Values:

DECISION_RED, DECISION_YELLOW, DECISION_GREEN

data[].wallet_provider_profile.risk_assessment.version

string
Conditionally returned

Wallet provider’s risk assessment version.

Allowable Values:

Version information, as provided by the wallet provider

end_index

integer
Conditionally returned

Sort order index of the last resource in the returned array.

This field is returned if there are resources in your returned array.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist. A value of false indicates that no more unreturned resources exist.

This field is returned if there are resources in your returned array.

Allowable Values:

true, false

start_index

integer
Conditionally returned

Sort order index of the first resource in the returned array.

This field is returned if there are resources in your returned array.

Allowable Values:

Any integer

Retrieve digital wallet token

Action: GET
Endpoint: /digitalwallettokens/{token}

Use this endpoint to retrieve a specific digital wallet token.

URL path parameters

Fields Description

token

string
Required

Unique identifier of the digital wallet token (DWT).

Allowable Values:

Existing DWT token

Response body

Fields Description

address_verification

object
Conditionally returned

Contains address verification information.

Allowable Values:

name, postal_code, street_address, zip

address_verification.name

string
Conditionally returned

Name of the cardholder.

Allowable Values:

40 char max

address_verification.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

address_verification.street_address

string
Conditionally returned

Street address provided by the cardholder.

Allowable Values:

40 char max

address_verification.zip

string
Conditionally returned

United States ZIP code.

Allowable Values:

10 char max

card_token

string
Conditionally returned

Unique identifier of the card.

Allowable Values:

Existing card token

created_time

datetime
Conditionally returned

Date and time when the digital wallet token object was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

device

object
Conditionally returned

Contains information related to the device being provisioned.

Allowable Values:

device_id, ip_address, language_code, location, name, phone_number, token, type

device.device_id

string
Conditionally returned

Identity number of the device.

Allowable Values:

20 char max

device.ip_address

string
Conditionally returned

Device’s IP address.

Allowable Values:

IP address format, 50 char max

device.language_code

string
Conditionally returned

Language the device is configured to use.

Allowable Values:

50 char max

device.location

string
Conditionally returned

Geographic coordinates of the device.

Allowable Values:

Latitude and longitude in DDD.DD/DDD.DD format.

NOTE: Both the longitude and latitude are prefixed with either a + or - symbol, for example: +42.29/-71.07.

device.name

string
Conditionally returned

Name of the device.

Allowable Values:

50 char max

device.phone_number

string
Conditionally returned

Device’s telephone number.

Allowable Values:

50 char max

device.token

string
Conditionally returned

Unique identifier of the device object.

Allowable Values:

36 char max

device.type

string
Conditionally returned

Type of device being provisioned.

Allowable Values:

MOBILE_PHONE, WATCH, TABLET, MOBILE_PHONE_OR_TABLET, VEHICLE, APPLIANCE, LAPTOP, GAMING_DEVICE, UNKNOWN

fulfillment_status

string
Conditionally returned

Digital wallet token’s provisioning status.

For fulfillment status descriptions, see Create digital wallet token transition.

Allowable Values:

DECISION_RED, DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED

issuer_eligibility_decision

string
Conditionally returned

The Marqeta platform’s decision as to whether the digital wallet token should be provisioned.

  • 0000 – The token should be provisioned.

  • token.activation.verification.required – Provisioning is pending; further action is required for completion.

For all other values, check the value of the fulfillment_status field to definitively ascertain the provisioning outcome.

NOTE: The value invalid.cid indicates an invalid CVV2 number.

Allowable Values:

0000, cardaccount.verified, card.suspicious, token.activation.verification.required, token.activation-request.decline, card.not.active, invalid.cid, card.expired, card.suspended, cardholder.not.active

last_modified_time

datetime
Conditionally returned

Date and time when the digital wallet token object was last modified, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

metadata

object
Conditionally returned

Contains additional information about the digital wallet token.

Allowable Values:

cardproduct_preferred_notification_language, issuer_product_config_id

metadata.cardproduct_preferred_notification_language

string
Conditionally returned

Language specified in the config.transaction_controls.notification_language field of the card product: ces (Czech), deu (German), eng (English), fra (French), ita (Italian), pol (Polish), spa (Spanish), swe (Swedish)

Allowable Values:

ces, deu, eng, fra, ita, pol, spa, swe

metadata.issuer_product_config_id

string
Conditionally returned

Unique identifier of the product configuration on the Marqeta platform.

Allowable Values:

255 char max

state

string
Conditionally returned

State of the digital wallet token.

For state descriptions, see Transitioning Token States.

Allowable Values:

REQUESTED, REQUEST_DECLINED, ACTIVE, SUSPENDED, TERMINATED

state_reason

string
Conditionally returned

Reason why the digital wallet token transitioned to its current state.

Allowable Values:

255 char max

token

string
Conditionally returned

Unique identifier of the digital wallet token.

Allowable Values:

Existing digital wallet token.

token_service_provider

object
Conditionally returned

Contains information held and provided by the token service provider (card network).

Allowable Values:

correlation_id, pan_reference_id, token_assurance_level, token_eligibility_decision, token_expiration, token_pan, token_reference_id, token_requestor_id, token_requestor_name, token_score, token_type

token_service_provider.correlation_id

string
Conditionally returned

Unique value representing a tokenization request (Mastercard only).

Allowable Values:

Existing correlation identifier

token_service_provider.pan_reference_id

string
Returned

Unique identifier of the digital wallet token primary account number (PAN) within the card network.

Allowable Values:

Existing PAN Reference ID

token_service_provider.token_assurance_level

string
Conditionally returned

(Mastercard only) Represents the confidence level in the digital wallet token.

Allowable Values:

0-99

token_service_provider.token_eligibility_decision

string
Conditionally returned

Digital wallet’s decision as to whether the digital wallet token should be provisioned.

Allowable Values:

DECISION_RED, DECISION_YELLOW, DECISION_GREEN

token_service_provider.token_expiration

string
Conditionally returned

Expiration date of the digital wallet token.

Allowable Values:

Format: MMyy

token_service_provider.token_pan

string
Conditionally returned

Primary account number (PAN) of the digital wallet token.

Allowable Values:

16 char max

token_service_provider.token_reference_id

string
Conditionally returned

Unique identifier of the digital wallet token within the card network.

Allowable Values:

Existing Token Reference ID

token_service_provider.token_requestor_id

string
Conditionally returned

Unique numerical identifier of the token requestor within the card network. These ID numbers map to token_requestor_name field values as follows:

Mastercard

  • 50110030273 – APPLE_PAY

  • 50120834693 – ANDROID_PAY

  • 50139059239 – SAMSUNG_PAY

Visa

  • 40010030273 – APPLE_PAY

  • 40010075001 – ANDROID_PAY

  • 40010043095 – SAMSUNG_PAY

  • 40010075196 – MICROSOFT_PAY

  • 40010075338 – VISA_CHECKOUT

  • 40010075449 – FACEBOOK

  • 40010075839 – NETFLIX

  • 40010077056 – FITBIT_PAY

  • 40010069887 – GARMIN_PAY

Allowable Values:

11 char max

Example Values:

  • Mastercard – 50110030273, 50120834693, 50139059239

  • Visa – 40010030273, 40010075001, 40010075338, 40010075449, 40010075839, 40010043095

token_service_provider.token_requestor_name

string
Conditionally returned

Name of the token requestor within the card network.

NOTE: The list of example values for this field is maintained by the card networks and is subject to change.

Allowable Values:

255 char max

Example Values:

  • MastercardAPPLE_PAY, ANDROID_PAY, SAMSUNG_PAY

  • VisaAPPLE_PAY, ANDROID_PAY, SAMSUNG_PAY, MICROSOFT_PAY, VISA_CHECKOUT, FACEBOOK, NETFLIX, FITBIT_PAY, GARMIN_PAY

token_service_provider.token_score

string
Conditionally returned

Token score assigned by the digital wallet.

Allowable Values:

25 char max

token_service_provider.token_type

string
Conditionally returned

Type of the digital wallet token.

Allowable Values:

MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET

user

object
Conditionally returned

Contains information about a cardholder.

Allowable Values:

account_holder_group_token, active, address1, address2, authentication, birth_date, business_token, city, company, corporate_card_holder, country, created_time, email, first_name, gender, honorific, id_card_expiration_date, id_card_number, identifications, ip_address, last_modified_time, last_name, metadata, middle_name, nationality, notes, parent_token, passport_expiration_date, passport_number, password, phone, postal_code, ssn, state, status, token, uses_parent_account, zip

user.account_holder_group_token

string
Conditionally returned

Associates the specified account holder group with the cardholder.

Allowable Values:

36 char max

user.active

boolean
Conditionally returned

Specifies if the cardholder is in the ACTIVE state on the Marqeta platform.

Allowable Values:

true, false

user.address1

string
Conditionally returned

Cardholder’s address.

Allowable Values:

255 char max

user.address2

string
Conditionally returned

Additional address information for the cardholder.

Allowable Values:

255 char max

user.authentication

object
Conditionally returned

Contains the cardholder’s email address and password information.

Allowable Values:

email_verified, email_verified_time, last_password_update_channel, last_password_update_time

user.authentication.email_verified

boolean
Conditionally returned

Specifies whether the email address has been verified.

Allowable Values:

true, false

user.authentication.email_verified_time

datetime
Conditionally returned

Date and time when the email address was verified.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

user.authentication.last_password_update_channel

string
Conditionally returned

Specifies the channel through which the password was last changed.

Allowable Values:

USER_CHANGE, USER_RESET

user.authentication.last_password_update_time

datetime
Conditionally returned

Date and time when the password was last changed.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

user.birth_date

string
Conditionally returned

Cardholder’s date of birth.

Allowable Values:

Format: yyyy-MM-dd

user.business_token

string
Conditionally returned

Unique identifier of the business resource.

Allowable Values:

Existing business resource token

user.city

string
Conditionally returned

City where the cardholder resides.

Allowable Values:

40 char max

user.company

string
Conditionally returned

Company name.

Allowable Values:

255 char max

user.corporate_card_holder

boolean
Conditionally returned

Specifies if the cardholder holds a corporate card.

Allowable Values:

true, false

user.country

string
Conditionally returned

Country where the cardholder resides.

Allowable Values:

40 char max

user.created_time

datetime
Returned

Date and time when the resource was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

user.email

string
Conditionally returned

Valid email address of the cardholder.

Allowable Values:

1–255 chars

user.first_name

string
Conditionally returned

Cardholder’s first name.

Allowable Values:

40 char max

user.gender

string
Conditionally returned

Gender of the cardholder.

Allowable Values:

F, M

user.honorific

string
Conditionally returned

Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on.

Allowable Values:

10 char max

user.id_card_expiration_date

string
Conditionally returned

Expiration date of the cardholder’s identification.

Allowable Values:

Format: yyyy-MM-dd

user.id_card_number

string
Conditionally returned

Cardholder’s identification card number.

Allowable Values:

255 char max

user.identifications

array of objects
Conditionally returned

One or more objects containing identifications associated with the cardholder.

Allowable Values:

Valid array of one or more identifications objects

user.identifications[].expiration_date

string
Conditionally returned

Expiration date for the identification, if applicable.

Allowable Values:

Format: yyyy-MM-dd

user.identifications[].type

string
Conditionally returned

Type of identification.

Allowable Values:

SSN, TIN, SIN, NIN, PASSPORT_NUMBER, DRIVERS_LICENSE, BUSINESS_NUMBER, BUSINESS_TAX_ID, TAXPAYER_REFERENCE

user.identifications[].value

string
Conditionally returned

Number associated with the identification.

Allowable Values:

255 char max

user.ip_address

string
Conditionally returned

Cardholder’s IP address.

Allowable Values:

39 char max

user.last_modified_time

datetime
Returned

Date and time when the resource was last updated, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

user.last_name

string
Conditionally returned

Cardholder’s last name.

Allowable Values:

40 char max

user.metadata

object
Conditionally returned

Associates any additional metadata you provide with the cardholder.

Allowable Values:

You can define the names and values of up to 20 fields in the format "my_name_1": "my_value_1"

user.middle_name

string
Conditionally returned

Cardholder’s middle name.

Allowable Values:

40 char max

user.nationality

string
Conditionally returned

Cardholder’s nationality.

Allowable Values:

255 char max

user.notes

string
Conditionally returned

Any additional information pertaining to the cardholder.

Allowable Values:

255 char max

user.parent_token

string
Conditionally returned

Unique identifier of the parent user or business resource.

Allowable Values:

1–36 chars

user.passport_expiration_date

string
Conditionally returned

Expiration date of the cardholder’s passport.

Allowable Values:

Format: yyyy-MM-dd

user.passport_number

string
Conditionally returned

Cardholder’s passport number.

Allowable Values:

40 char max

user.password

string
Conditionally returned

Password to the cardholder’s user account on the Marqeta platform.

Allowable Values:

1–255 chars

user.phone

string
Conditionally returned

Cardholder’s telephone number.

Allowable Values:

255 char max

user.postal_code

string
Conditionally returned

Postal code of the cardholder’s address.

Allowable Values:

10 char max

user.ssn

string
Conditionally returned

Cardholder’s Social Security Number (SSN).

Allowable Values:

Nine digits only, no delimiters.

user.state

string
Conditionally returned

State or province where the cardholder resides.

Allowable Values:

2 char max

user.status

string
Conditionally returned

Specifies the status of the cardholder on the Marqeta platform.

Allowable Values:

UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED

user.token

string
Conditionally returned

Unique identifier of the cardholder.

Allowable Values:

1–36 chars

user.uses_parent_account

boolean
Conditionally returned

Indicates whether the child shares balances with the parent (true), or the child’s balances are independent of the parent (false).

Allowable Values:

true, false

user.zip

string
Conditionally returned

United States ZIP code of the cardholder’s address.

Allowable Values:

10 char max

wallet_provider_profile

object
Conditionally returned

Contains information held and provided by the digital wallet provider.

Allowable Values:

account, device_score, pan_source, reason_code, recommendation_reasons, risk_assessment

wallet_provider_profile.account

object
Conditionally returned

Contains information related to the cardholder and provided by the digital wallet provider.

Allowable Values:

email_address, id, score

wallet_provider_profile.account.email_address

string
Conditionally returned

Digital wallet provider’s email address for the cardholder.

Allowable Values:

255 char max

wallet_provider_profile.account.id

string
Conditionally returned

Digital wallet provider’s identity number for the cardholder.

Allowable Values:

20 char max

wallet_provider_profile.account.score

string
Conditionally returned

Score from the digital wallet provider.

Allowable Values:

50 char max

wallet_provider_profile.device_score

string
Conditionally returned

Score from the device.

Allowable Values:

50 char max

wallet_provider_profile.pan_source

string
Conditionally returned

Source from which the digital wallet provider obtained the card primary account number (PAN).

Allowable Values:

KEY_ENTERED, ON_FILE, MOBILE_BANKING_APP

wallet_provider_profile.reason_code

string
Conditionally returned

Reason for the wallet provider’s provisioning decision.

  • 01 – Cardholder’s wallet account is too new relative to launch.

  • 02 – Cardholder’s wallet account is too new relative to provisioning request.

  • 03 – Cardholder’s wallet account/card pair is newer than date threshold.

  • 04 – Changes made to account data within the account threshold.

  • 05 – Suspicious transactions linked to this account.

  • 06 – Account has not had activity in the last year.

  • 07 – Suspended cards in the secure element.

  • 08 – Device was put in lost mode in the last seven days for longer than the duration threshold.

  • 09 – The number of provisioning attempts on this device in 24 hours exceeds threshold.

  • 0A – There have been more than the threshold number of different cards attempted at provisioning to this phone in 24 hours.

  • 0B – The card provisioning attempt contains a distinct name in excess of the threshold.

  • 0C – The device score is less than 3.

  • 0D – The account score is less than 4.

  • 0E – Device provisioning location outside of the cardholder’s wallet account home country.

  • 0G – Suspect fraud.

Allowable Values:

01, 02, 03, 04, 05, 06, 07, 08, 09, 0A, 0B, 0C, 0D, 0E, 0G

wallet_provider_profile.recommendation_reasons

array of strings
Conditionally returned

Array of recommendation reasons from the digital wallet provider.

Allowable Values:

Valid array of one or more recommendation reasons

wallet_provider_profile.risk_assessment

object
Conditionally returned

Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token.

Allowable Values:

score, version

wallet_provider_profile.risk_assessment.score

string
Conditionally returned

Wallet provider’s decision as to whether the digital wallet token should be provisioned.

Allowable Values:

DECISION_RED, DECISION_YELLOW, DECISION_GREEN

wallet_provider_profile.risk_assessment.version

string
Conditionally returned

Wallet provider’s risk assessment version.

Allowable Values:

Version information, as provided by the wallet provider

Sample response body

JSON
Copied

Is this helpful?

Yes
No

List digital wallet tokens for card

Action: GET
Endpoint: /digitalwallettokens/card/{card_token}

Use this endpoint to return an array of all digital wallet tokens for a particular card.

This endpoint supports pagination.

URL path parameters

Fields Description

card_token

string
Required

Unique identifier of the card. Used to minimize the need to exchange card details during subsequent calls, and also for troubleshooting.

Allowable Values:

Existing card token

URL query parameters

Fields Description

count

integer
Optional

Number of digital wallet token resources to retrieve.

Allowable Values:

Any integer

Default value:
5

start_index

integer
Optional

Sort order index of the first digital wallet token resource in the returned array.

Allowable Values:

Any integer

Default value:
0

sort_by

string
Optional

Field on which to sort. Use any field in the resource model, or one of the system fields lastModifiedTime or createdTime. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.

Allowable Values:

createdTime, lastModifiedTime, or any field in the resource model

Default value:
-createdTime

Response body

Fields Description

count

integer
Conditionally returned

Number of resources returned.

This field is returned if there are resources in your returned array.

Allowable Values:

Any integer

data

array of objects
Conditionally returned

Array of digital wallet token resources.

Resources are returned as appropriate to your query.

Allowable Values:

Valid array of one or more digital wallet token resources

data[].address_verification

object
Conditionally returned

Contains address verification information.

Allowable Values:

name, postal_code, street_address, zip

data[].address_verification.name

string
Conditionally returned

Name of the cardholder.

Allowable Values:

40 char max

data[].address_verification.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

data[].address_verification.street_address

string
Conditionally returned

Street address provided by the cardholder.

Allowable Values:

40 char max

data[].address_verification.zip

string
Conditionally returned

United States ZIP code.

Allowable Values:

10 char max

data[].card_token

string
Conditionally returned

Unique identifier of the card.

Allowable Values:

Existing card token

data[].created_time

datetime
Conditionally returned

Date and time when the digital wallet token object was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

data[].device

object
Conditionally returned

Contains information related to the device being provisioned.

Allowable Values:

device_id, ip_address, language_code, location, name, phone_number, token, type

data[].device.device_id

string
Conditionally returned

Identity number of the device.

Allowable Values:

20 char max

data[].device.ip_address

string
Conditionally returned

Device’s IP address.

Allowable Values:

IP address format, 50 char max

data[].device.language_code

string
Conditionally returned

Language the device is configured to use.

Allowable Values:

50 char max

data[].device.location

string
Conditionally returned

Geographic coordinates of the device.

Allowable Values:

Latitude and longitude in DDD.DD/DDD.DD format.

NOTE: Both the longitude and latitude are prefixed with either a + or - symbol, for example: +42.29/-71.07.

data[].device.name

string
Conditionally returned

Name of the device.

Allowable Values:

50 char max

data[].device.phone_number

string
Conditionally returned

Device’s telephone number.

Allowable Values:

50 char max

data[].device.token

string
Conditionally returned

Unique identifier of the device object.

Allowable Values:

36 char max

data[].device.type

string
Conditionally returned

Type of device being provisioned.

Allowable Values:

MOBILE_PHONE, WATCH, TABLET, MOBILE_PHONE_OR_TABLET, VEHICLE, APPLIANCE, LAPTOP, GAMING_DEVICE, UNKNOWN

data[].fulfillment_status

string
Conditionally returned

Digital wallet token’s provisioning status.

For fulfillment status descriptions, see Create digital wallet token transition.

Allowable Values:

DECISION_RED, DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED

data[].issuer_eligibility_decision

string
Conditionally returned

The Marqeta platform’s decision as to whether the digital wallet token should be provisioned.

  • 0000 – The token should be provisioned.

  • token.activation.verification.required – Provisioning is pending; further action is required for completion.

For all other values, check the value of the fulfillment_status field to definitively ascertain the provisioning outcome.

NOTE: The value invalid.cid indicates an invalid CVV2 number.

Allowable Values:

0000, cardaccount.verified, card.suspicious, token.activation.verification.required, token.activation-request.decline, card.not.active, invalid.cid, card.expired, card.suspended, cardholder.not.active

data[].last_modified_time

datetime
Conditionally returned

Date and time when the digital wallet token object was last modified, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

data[].metadata

object
Conditionally returned

Contains additional information about the digital wallet token.

Allowable Values:

cardproduct_preferred_notification_language, issuer_product_config_id

data[].metadata.cardproduct_preferred_notification_language

string
Conditionally returned

Language specified in the config.transaction_controls.notification_language field of the card product: ces (Czech), deu (German), eng (English), fra (French), ita (Italian), pol (Polish), spa (Spanish), swe (Swedish)

Allowable Values:

ces, deu, eng, fra, ita, pol, spa, swe

data[].metadata.issuer_product_config_id

string
Conditionally returned

Unique identifier of the product configuration on the Marqeta platform.

Allowable Values:

255 char max

data[].state

string
Conditionally returned

State of the digital wallet token.

For state descriptions, see Transitioning Token States.

Allowable Values:

REQUESTED, REQUEST_DECLINED, ACTIVE, SUSPENDED, TERMINATED

data[].state_reason

string
Conditionally returned

Reason why the digital wallet token transitioned to its current state.

Allowable Values:

255 char max

data[].token

string
Conditionally returned

Unique identifier of the digital wallet token.

Allowable Values:

Existing digital wallet token.

data[].token_service_provider

object
Conditionally returned

Contains information held and provided by the token service provider (card network).

Allowable Values:

correlation_id, pan_reference_id, token_assurance_level, token_eligibility_decision, token_expiration, token_pan, token_reference_id, token_requestor_id, token_requestor_name, token_score, token_type

data[].token_service_provider.correlation_id

string
Conditionally returned

Unique value representing a tokenization request (Mastercard only).

Allowable Values:

Existing correlation identifier

data[].token_service_provider.pan_reference_id

string
Returned

Unique identifier of the digital wallet token primary account number (PAN) within the card network.

Allowable Values:

Existing PAN Reference ID

data[].token_service_provider.token_assurance_level

string
Conditionally returned

(Mastercard only) Represents the confidence level in the digital wallet token.

Allowable Values:

0-99

data[].token_service_provider.token_eligibility_decision

string
Conditionally returned

Digital wallet’s decision as to whether the digital wallet token should be provisioned.

Allowable Values:

DECISION_RED, DECISION_YELLOW, DECISION_GREEN

data[].token_service_provider.token_expiration

string
Conditionally returned

Expiration date of the digital wallet token.

Allowable Values:

Format: MMyy

data[].token_service_provider.token_pan

string
Conditionally returned

Primary account number (PAN) of the digital wallet token.

Allowable Values:

16 char max

data[].token_service_provider.token_reference_id

string
Conditionally returned

Unique identifier of the digital wallet token within the card network.

Allowable Values:

Existing Token Reference ID

data[].token_service_provider.token_requestor_id

string
Conditionally returned

Unique numerical identifier of the token requestor within the card network. These ID numbers map to token_requestor_name field values as follows:

Mastercard

  • 50110030273 – APPLE_PAY

  • 50120834693 – ANDROID_PAY

  • 50139059239 – SAMSUNG_PAY

Visa

  • 40010030273 – APPLE_PAY

  • 40010075001 – ANDROID_PAY

  • 40010043095 – SAMSUNG_PAY

  • 40010075196 – MICROSOFT_PAY

  • 40010075338 – VISA_CHECKOUT

  • 40010075449 – FACEBOOK

  • 40010075839 – NETFLIX

  • 40010077056 – FITBIT_PAY

  • 40010069887 – GARMIN_PAY

Allowable Values:

11 char max

Example Values:

  • Mastercard – 50110030273, 50120834693, 50139059239

  • Visa – 40010030273, 40010075001, 40010075338, 40010075449, 40010075839, 40010043095

data[].token_service_provider.token_requestor_name

string
Conditionally returned

Name of the token requestor within the card network.

NOTE: The list of example values for this field is maintained by the card networks and is subject to change.

Allowable Values:

255 char max

Example Values:

  • MastercardAPPLE_PAY, ANDROID_PAY, SAMSUNG_PAY

  • VisaAPPLE_PAY, ANDROID_PAY, SAMSUNG_PAY, MICROSOFT_PAY, VISA_CHECKOUT, FACEBOOK, NETFLIX, FITBIT_PAY, GARMIN_PAY

data[].token_service_provider.token_score

string
Conditionally returned

Token score assigned by the digital wallet.

Allowable Values:

25 char max

data[].token_service_provider.token_type

string
Conditionally returned

Type of the digital wallet token.

Allowable Values:

MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET

data[].user

object
Conditionally returned

Contains information about a cardholder.

Allowable Values:

account_holder_group_token, active, address1, address2, authentication, birth_date, business_token, city, company, corporate_card_holder, country, created_time, email, first_name, gender, honorific, id_card_expiration_date, id_card_number, identifications, ip_address, last_modified_time, last_name, metadata, middle_name, nationality, notes, parent_token, passport_expiration_date, passport_number, password, phone, postal_code, ssn, state, status, token, uses_parent_account, zip

data[].user.account_holder_group_token

string
Conditionally returned

Associates the specified account holder group with the cardholder.

Allowable Values:

36 char max

data[].user.active

boolean
Conditionally returned

Specifies if the cardholder is in the ACTIVE state on the Marqeta platform.

Allowable Values:

true, false

data[].user.address1

string
Conditionally returned

Cardholder’s address.

Allowable Values:

255 char max

data[].user.address2

string
Conditionally returned

Additional address information for the cardholder.

Allowable Values:

255 char max

data[].user.authentication

object
Conditionally returned

Contains the cardholder’s email address and password information.

Allowable Values:

email_verified, email_verified_time, last_password_update_channel, last_password_update_time

data[].user.authentication.email_verified

boolean
Conditionally returned

Specifies whether the email address has been verified.

Allowable Values:

true, false

data[].user.authentication.email_verified_time

datetime
Conditionally returned

Date and time when the email address was verified.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

data[].user.authentication.last_password_update_channel

string
Conditionally returned

Specifies the channel through which the password was last changed.

Allowable Values:

USER_CHANGE, USER_RESET

data[].user.authentication.last_password_update_time

datetime
Conditionally returned

Date and time when the password was last changed.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

data[].user.birth_date

string
Conditionally returned

Cardholder’s date of birth.

Allowable Values:

Format: yyyy-MM-dd

data[].user.business_token

string
Conditionally returned

Unique identifier of the business resource.

Allowable Values:

Existing business resource token

data[].user.city

string
Conditionally returned

City where the cardholder resides.

Allowable Values:

40 char max

data[].user.company

string
Conditionally returned

Company name.

Allowable Values:

255 char max

data[].user.corporate_card_holder

boolean
Conditionally returned

Specifies if the cardholder holds a corporate card.

Allowable Values:

true, false

data[].user.country

string
Conditionally returned

Country where the cardholder resides.

Allowable Values:

40 char max

data[].user.created_time

datetime
Returned

Date and time when the resource was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

data[].user.email

string
Conditionally returned

Valid email address of the cardholder.

Allowable Values:

1–255 chars

data[].user.first_name

string
Conditionally returned

Cardholder’s first name.

Allowable Values:

40 char max

data[].user.gender

string
Conditionally returned

Gender of the cardholder.

Allowable Values:

F, M

data[].user.honorific

string
Conditionally returned

Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on.

Allowable Values:

10 char max

data[].user.id_card_expiration_date

string
Conditionally returned

Expiration date of the cardholder’s identification.

Allowable Values:

Format: yyyy-MM-dd

data[].user.id_card_number

string
Conditionally returned

Cardholder’s identification card number.

Allowable Values:

255 char max

data[].user.identifications

array of objects
Conditionally returned

One or more objects containing identifications associated with the cardholder.

Allowable Values:

Valid array of one or more identifications objects

data[].user.identifications[].expiration_date

string
Conditionally returned

Expiration date for the identification, if applicable.

Allowable Values:

Format: yyyy-MM-dd

data[].user.identifications[].type

string
Conditionally returned

Type of identification.

Allowable Values:

SSN, TIN, SIN, NIN, PASSPORT_NUMBER, DRIVERS_LICENSE, BUSINESS_NUMBER, BUSINESS_TAX_ID, TAXPAYER_REFERENCE

data[].user.identifications[].value

string
Conditionally returned

Number associated with the identification.

Allowable Values:

255 char max

data[].user.ip_address

string
Conditionally returned

Cardholder’s IP address.

Allowable Values:

39 char max

data[].user.last_modified_time

datetime
Returned

Date and time when the resource was last updated, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

data[].user.last_name

string
Conditionally returned

Cardholder’s last name.

Allowable Values:

40 char max

data[].user.metadata

object
Conditionally returned

Associates any additional metadata you provide with the cardholder.

Allowable Values:

You can define the names and values of up to 20 fields in the format "my_name_1": "my_value_1"

data[].user.middle_name

string
Conditionally returned

Cardholder’s middle name.

Allowable Values:

40 char max

data[].user.nationality

string
Conditionally returned

Cardholder’s nationality.

Allowable Values:

255 char max

data[].user.notes

string
Conditionally returned

Any additional information pertaining to the cardholder.

Allowable Values:

255 char max

data[].user.parent_token

string
Conditionally returned

Unique identifier of the parent user or business resource.

Allowable Values:

1–36 chars

data[].user.passport_expiration_date

string
Conditionally returned

Expiration date of the cardholder’s passport.

Allowable Values:

Format: yyyy-MM-dd

data[].user.passport_number

string
Conditionally returned

Cardholder’s passport number.

Allowable Values:

40 char max

data[].user.password

string
Conditionally returned

Password to the cardholder’s user account on the Marqeta platform.

Allowable Values:

1–255 chars

data[].user.phone

string
Conditionally returned

Cardholder’s telephone number.

Allowable Values:

255 char max

data[].user.postal_code

string
Conditionally returned

Postal code of the cardholder’s address.

Allowable Values:

10 char max

data[].user.ssn

string
Conditionally returned

Cardholder’s Social Security Number (SSN).

Allowable Values:

Nine digits only, no delimiters.

data[].user.state

string
Conditionally returned

State or province where the cardholder resides.

Allowable Values:

2 char max

data[].user.status

string
Conditionally returned

Specifies the status of the cardholder on the Marqeta platform.

Allowable Values:

UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED

data[].user.token

string
Conditionally returned

Unique identifier of the cardholder.

Allowable Values:

1–36 chars

data[].user.uses_parent_account

boolean
Conditionally returned

Indicates whether the child shares balances with the parent (true), or the child’s balances are independent of the parent (false).

Allowable Values:

true, false

data[].user.zip

string
Conditionally returned

United States ZIP code of the cardholder’s address.

Allowable Values:

10 char max

data[].wallet_provider_profile

object
Conditionally returned

Contains information held and provided by the digital wallet provider.

Allowable Values:

account, device_score, pan_source, reason_code, recommendation_reasons, risk_assessment

data[].wallet_provider_profile.account

object
Conditionally returned

Contains information related to the cardholder and provided by the digital wallet provider.

Allowable Values:

email_address, id, score

data[].wallet_provider_profile.account.email_address

string
Conditionally returned

Digital wallet provider’s email address for the cardholder.

Allowable Values:

255 char max

data[].wallet_provider_profile.account.id

string
Conditionally returned

Digital wallet provider’s identity number for the cardholder.

Allowable Values:

20 char max

data[].wallet_provider_profile.account.score

string
Conditionally returned

Score from the digital wallet provider.

Allowable Values:

50 char max

data[].wallet_provider_profile.device_score

string
Conditionally returned

Score from the device.

Allowable Values:

50 char max

data[].wallet_provider_profile.pan_source

string
Conditionally returned

Source from which the digital wallet provider obtained the card primary account number (PAN).

Allowable Values:

KEY_ENTERED, ON_FILE, MOBILE_BANKING_APP

data[].wallet_provider_profile.reason_code

string
Conditionally returned

Reason for the wallet provider’s provisioning decision.

  • 01 – Cardholder’s wallet account is too new relative to launch.

  • 02 – Cardholder’s wallet account is too new relative to provisioning request.

  • 03 – Cardholder’s wallet account/card pair is newer than date threshold.

  • 04 – Changes made to account data within the account threshold.

  • 05 – Suspicious transactions linked to this account.

  • 06 – Account has not had activity in the last year.

  • 07 – Suspended cards in the secure element.

  • 08 – Device was put in lost mode in the last seven days for longer than the duration threshold.

  • 09 – The number of provisioning attempts on this device in 24 hours exceeds threshold.

  • 0A – There have been more than the threshold number of different cards attempted at provisioning to this phone in 24 hours.

  • 0B – The card provisioning attempt contains a distinct name in excess of the threshold.

  • 0C – The device score is less than 3.

  • 0D – The account score is less than 4.

  • 0E – Device provisioning location outside of the cardholder’s wallet account home country.

  • 0G – Suspect fraud.

Allowable Values:

01, 02, 03, 04, 05, 06, 07, 08, 09, 0A, 0B, 0C, 0D, 0E, 0G

data[].wallet_provider_profile.recommendation_reasons

array of strings
Conditionally returned

Array of recommendation reasons from the digital wallet provider.

Allowable Values:

Valid array of one or more recommendation reasons

data[].wallet_provider_profile.risk_assessment

object
Conditionally returned

Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token.

Allowable Values:

score, version

data[].wallet_provider_profile.risk_assessment.score

string
Conditionally returned

Wallet provider’s decision as to whether the digital wallet token should be provisioned.

Allowable Values:

DECISION_RED, DECISION_YELLOW, DECISION_GREEN

data[].wallet_provider_profile.risk_assessment.version

string
Conditionally returned

Wallet provider’s risk assessment version.

Allowable Values:

Version information, as provided by the wallet provider

end_index

integer
Conditionally returned

Sort order index of the last resource in the returned array.

This field is returned if there are resources in your returned array.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist. A value of false indicates that no more unreturned resources exist.

This field is returned if there are resources in your returned array.

Allowable Values:

true, false

start_index

integer
Conditionally returned

Sort order index of the first resource in the returned array.

This field is returned if there are resources in your returned array.

Allowable Values:

Any integer

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Retrieve digital wallet token PAN

Action: GET
Endpoint: /digitalwallettokens/{token}/showtokenpan

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

Warning
Sending a request to this endpoint requires PCI DSS compliance. You must comply with PCI DSS data security requirements if you want to store, transmit, or process sensitive card data such as the cardholder’s primary account number (PAN), personal identification number (PIN), and card expiration date.

URL path parameters

Fields Description

token

string
Required

Unique identifier of the digital wallet token (DWT).

Allowable Values:

Existing DWT token

Response body

Fields Description

address_verification

object
Conditionally returned

Contains address verification information.

Allowable Values:

name, postal_code, street_address, zip

address_verification.name

string
Conditionally returned

Name of the cardholder.

Allowable Values:

40 char max

address_verification.postal_code

string
Conditionally returned

Postal code.

Allowable Values:

10 char max

address_verification.street_address

string
Conditionally returned

Street address provided by the cardholder.

Allowable Values:

40 char max

address_verification.zip

string
Conditionally returned

United States ZIP code.

Allowable Values:

10 char max

card_token

string
Conditionally returned

Unique identifier of the card.

Allowable Values:

Existing card token

created_time

datetime
Conditionally returned

Date and time when the digital wallet token object was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

device

object
Conditionally returned

Contains information related to the device being provisioned.

Allowable Values:

device_id, ip_address, language_code, location, name, phone_number, token, type

device.device_id

string
Conditionally returned

Identity number of the device.

Allowable Values:

20 char max

device.ip_address

string
Conditionally returned

Device’s IP address.

Allowable Values:

IP address format, 50 char max

device.language_code

string
Conditionally returned

Language the device is configured to use.

Allowable Values:

50 char max

device.location

string
Conditionally returned

Geographic coordinates of the device.

Allowable Values:

Latitude and longitude in DDD.DD/DDD.DD format.

NOTE: Both the longitude and latitude are prefixed with either a + or - symbol, for example: +42.29/-71.07.

device.name

string
Conditionally returned

Name of the device.

Allowable Values:

50 char max

device.phone_number

string
Conditionally returned

Device’s telephone number.

Allowable Values:

50 char max

device.token

string
Conditionally returned

Unique identifier of the device object.

Allowable Values:

36 char max

device.type

string
Conditionally returned

Type of device being provisioned.

Allowable Values:

MOBILE_PHONE, WATCH, TABLET, MOBILE_PHONE_OR_TABLET, VEHICLE, APPLIANCE, LAPTOP, GAMING_DEVICE, UNKNOWN

fulfillment_status

string
Conditionally returned

Digital wallet token’s provisioning status.

For fulfillment status descriptions, see Create digital wallet token transition.

Allowable Values:

DECISION_RED, DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED

issuer_eligibility_decision

string
Conditionally returned

The Marqeta platform’s decision as to whether the digital wallet token should be provisioned.

  • 0000 – The token should be provisioned.

  • token.activation.verification.required – Provisioning is pending; further action is required for completion.

For all other values, check the value of the fulfillment_status field to definitively ascertain the provisioning outcome.

NOTE: The value invalid.cid indicates an invalid CVV2 number.

Allowable Values:

0000, cardaccount.verified, card.suspicious, token.activation.verification.required, token.activation-request.decline, card.not.active, invalid.cid, card.expired, card.suspended, cardholder.not.active

last_modified_time

datetime
Conditionally returned

Date and time when the digital wallet token object was last modified, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

metadata

object
Conditionally returned

Contains additional information about the digital wallet token.

Allowable Values:

cardproduct_preferred_notification_language, issuer_product_config_id

metadata.cardproduct_preferred_notification_language

string
Conditionally returned

Language specified in the config.transaction_controls.notification_language field of the card product: ces (Czech), deu (German), eng (English), fra (French), ita (Italian), pol (Polish), spa (Spanish), swe (Swedish)

Allowable Values:

ces, deu, eng, fra, ita, pol, spa, swe

metadata.issuer_product_config_id

string
Conditionally returned

Unique identifier of the product configuration on the Marqeta platform.

Allowable Values:

255 char max

state

string
Conditionally returned

State of the digital wallet token.

For state descriptions, see Transitioning Token States.

Allowable Values:

REQUESTED, REQUEST_DECLINED, ACTIVE, SUSPENDED, TERMINATED

state_reason

string
Conditionally returned

Reason why the digital wallet token transitioned to its current state.

Allowable Values:

255 char max

token

string
Conditionally returned

Unique identifier of the digital wallet token.

Allowable Values:

Existing digital wallet token.

token_service_provider

object
Conditionally returned

Contains information held and provided by the token service provider (card network).

Allowable Values:

correlation_id, pan_reference_id, token_assurance_level, token_eligibility_decision, token_expiration, token_pan, token_reference_id, token_requestor_id, token_requestor_name, token_score, token_type

token_service_provider.correlation_id

string
Conditionally returned

Unique value representing a tokenization request (Mastercard only).

Allowable Values:

Existing correlation identifier

token_service_provider.pan_reference_id

string
Returned

Unique identifier of the digital wallet token primary account number (PAN) within the card network.

Allowable Values:

Existing PAN Reference ID

token_service_provider.token_assurance_level

string
Conditionally returned

(Mastercard only) Represents the confidence level in the digital wallet token.

Allowable Values:

0-99

token_service_provider.token_eligibility_decision

string
Conditionally returned

Digital wallet’s decision as to whether the digital wallet token should be provisioned.

Allowable Values:

DECISION_RED, DECISION_YELLOW, DECISION_GREEN

token_service_provider.token_expiration

string
Conditionally returned

Expiration date of the digital wallet token.

Allowable Values:

Format: MMyy

token_service_provider.token_pan

string
Conditionally returned

Primary account number (PAN) of the digital wallet token.

Allowable Values:

16 char max

token_service_provider.token_reference_id

string
Conditionally returned

Unique identifier of the digital wallet token within the card network.

Allowable Values:

Existing Token Reference ID

token_service_provider.token_requestor_id

string
Conditionally returned

Unique numerical identifier of the token requestor within the card network. These ID numbers map to token_requestor_name field values as follows:

Mastercard

  • 50110030273 – APPLE_PAY

  • 50120834693 – ANDROID_PAY

  • 50139059239 – SAMSUNG_PAY

Visa

  • 40010030273 – APPLE_PAY

  • 40010075001 – ANDROID_PAY

  • 40010043095 – SAMSUNG_PAY

  • 40010075196 – MICROSOFT_PAY

  • 40010075338 – VISA_CHECKOUT

  • 40010075449 – FACEBOOK

  • 40010075839 – NETFLIX

  • 40010077056 – FITBIT_PAY

  • 40010069887 – GARMIN_PAY

Allowable Values:

11 char max

Example Values:

  • Mastercard – 50110030273, 50120834693, 50139059239

  • Visa – 40010030273, 40010075001, 40010075338, 40010075449, 40010075839, 40010043095

token_service_provider.token_requestor_name

string
Conditionally returned

Name of the token requestor within the card network.

NOTE: The list of example values for this field is maintained by the card networks and is subject to change.

Allowable Values:

255 char max

Example Values:

  • MastercardAPPLE_PAY, ANDROID_PAY, SAMSUNG_PAY

  • VisaAPPLE_PAY, ANDROID_PAY, SAMSUNG_PAY, MICROSOFT_PAY, VISA_CHECKOUT, FACEBOOK, NETFLIX, FITBIT_PAY, GARMIN_PAY

token_service_provider.token_score

string
Conditionally returned

Token score assigned by the digital wallet.

Allowable Values:

25 char max

token_service_provider.token_type

string
Conditionally returned

Type of the digital wallet token.

Allowable Values:

MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET