/
95 minute read
October 20, 2022

Tokenization-as-a-Service (Beta)

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

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

  • Use the /digitalwallettokens endpoint to retrieve digital wallet tokens by list, by card, or by individual token.

  • Use the /digitalwallettokentransitions endpoint to create or retrieve digital wallet token transitions.

  • Use the /digitalwalletprovisionrequests endpoints to instantly issue new virtual cards and provision digital wallets.

  • Use the /cardactions endpoint to transfer digital wallet tokens to new cards, or update the expiry date of a digital wallet token.

  • Use the /webhooks endpoint to send optional customer notifications for system events.

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

The number of digital wallet tokens to retrieve.

Allowable Values:

1-10

start_index

integer
Optional

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

Allowable Values:

Any integer

fields

string
Optional

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

Allowable Values:

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

lastModifiedTime, createdTime, or any field in the resource model

start_date

string
Optional

The date when the digital wallet token can be active.

Allowable Values:

Format: yyyy-MM-dd

end_date

string
Optional

The expiration date of the digital wallet token.

Allowable Values:

Format: yyyy-MM-dd

pan_reference_id

string
Optional

The unique identifier of the digital wallet token PAN within the card network. This value may vary on a per-digital wallet basis. For example, the pan_reference_id may be different in Apple Pay and Google Wallet for the same digital wallet token.

Allowable Values:

An existing PAN reference identifier

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. This is the primary identifier for Visa.

Allowable Values:

An existing token reference identifier

correlation_id

string
Optional

The unique value representing a tokenization request (Mastercard only).

Allowable Values:

An existing correlation identifier

token_type

string
Optional

Comma-delimited list of digital wallet token types to display. Example values: DEVICE_SECURE_ELEMENT, MERCHANT_CARD_ON_FILE, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET, PSEUDO_ACCOUNT.

Allowable Values:

An existing token type

token_requestor_name

string
Optional

Comma-delimited list of digital wallet token wallet providers to display. Example values: APPLE_PAY, ANDROID_PAY, SAMSUNG_PAY, MICROSOFT_PAY, VISA_CHECKOUT, FACEBOOK, NETFLIX, UNKNOWN.

Allowable Values:

An existing token requestor name

state

string
Optional

Comma-delimited list of digital wallet token states to display. Example values: REQUESTED, REQUEST_DECLINED, TERMINATED, SUSPENDED, ACTIVE.

Allowable Values:

An existing state

embed

string
Optional

An optional embedded object, such as a card or a user.

Allowable Values:

An existing embed object

Response body
Fields Description

count

integer
Returned

The number of resources returned.

Allowable Values:

Any integer

start_index

integer
Returned

The sort order index of the first resource in the returned array.

Allowable Values:

Any integer

end_index

integer
Returned

The sort order index of the last resource in the returned array.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist.

Allowable Values:

true, false

data

array of objects
Conditionally returned

Contains the returned resources.

Allowable Values:

A valid data array

data[].token

string
Returned

The Marqeta unique identifier for the digital wallet token.

Allowable Values:

36 char max

data[].card_token

string
Returned

The token that identifies the card and correlates it with the card issuer.

Allowable Values:

An existing card token

data[].state

string
Conditionally returned

The current state of the digital wallet token. For example, ACTIVE, REQUESTED, REQUEST_DECLINED, TERMINATED, SUSPENDED, ACTIVE.

Allowable Values:

255 char max

data[].state_reason

string
Conditionally returned

A descriptive reason for the current state of the digital wallet token.

Allowable Values:

255 char max

data[].fulfillment_status

string
Conditionally returned

The digital wallet token’s provisioning status. Example values: DECISION_RED, DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED.

Allowable Values:

255 char max

data[].issuer_eligibility_decision

string
Conditionally returned

The Marqeta platform’s recommendation as to whether the digital wallet token should be provisioned. Example values: 0000 (Approved), invalid.cid, avs.decline, token.activation.

Allowable Values:

255 char max

data[].wallet_provider_profile

object
Conditionally returned

Contains information held and provided by the digital wallet provider. This object is returned when relevant information is provided by the digital wallet provider.

Allowable Values:

A valid wallet_provider_profile object

data[].wallet_provider_profile.account

object
Returned

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

Allowable Values:

A valid wallet_provider_profile.account object

data[].wallet_provider_profile.account.id

string
Returned

The digital wallet provider’s unique identity number for the cardholder. This identity number does not correlate with other information.

Allowable Values:

255 char max

data[].wallet_provider_profile.account.email_address

string
Conditionally returned

A hashed version of the email address linked to the digital wallet.

Allowable Values:

255 char max

data[].wallet_provider_profile.account.score

string
Conditionally returned

The score from the digital wallet provider. This value is returned if it is provided by the digital wallet provider.

Allowable Values:

255 char max

data[].wallet_provider_profile.risk_assessment

object
Conditionally returned

Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token, as returned by the digital wallet provider.

Allowable Values:

An existing wallet_provider_profile.risk_assessment object

data[].wallet_provider_profile.risk_assessment.score

string
Conditionally returned

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

Allowable Values:

DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED

data[].wallet_provider_profile.risk_assessment.version

string
Conditionally returned

The digital wallet provider’s risk version. Changes in the version may indicate differences in other fields.

Allowable Values:

255 char max

data[].wallet_provider_profile.device_score

string
Conditionally returned

The score from the device, as returned by the digital wallet provider.

Allowable Values:

255 char max

data[].wallet_provider_profile.pan_source

string
Returned

The source from which the digital wallet provider obtained the card PAN, as returned by the digital wallet provider.

Allowable Values:

KEY_ENTERED, ON_FILE, MOBILE_BANKING_APP

data[].wallet_provider_profile.reason_code

string
Conditionally returned

The reason for the digital wallet provider’s provisioning decision.

Allowable Values:

100 char max

data[].wallet_provider_profile.recommendation_reasons

array of strings
Conditionally returned

Provisioning decision recommendations, from Mastercard only.

Allowable Values:

A valid digital_wallet_provider.recommendation_reasons array

data[].created_time

datetime
Conditionally returned

The date and time when the resource was created, in UTC. 2020-10-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

data[].last_modified_time

datetime
Conditionally returned

The date and time when the resource was last modified, in UTC. 2020-10-26T20:03:10Z, for example.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

data[].encrypted_data

object
Conditionally returned

The encrypted_data object contains encrypted versions of the token_service_provider, device, and address_verification objects.

Allowable Values:

An existing encrypted_data object

data[].encrypted_data.token_service_provider

object
Conditionally returned

Contains information held and provided by the token service provider (card network). This object is returned when relevant information is provided by the token service provider.

Allowable Values:

An existing encrypted_data.token_service_provider object

data[].encrypted_data.token_service_provider.pan_reference_id

string
Returned

The unique identifier of the digital wallet token PAN within the card network. This value may vary on a per-digital wallet basis. For example, the pan_reference_id may be different in Apple Pay and Google Wallet for the same digital wallet token.

Allowable Values:

An existing encrypted_data.pan_reference_id object

data[].encrypted_data.token_service_provider.token_reference_id

string
Conditionally returned

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

Allowable Values:

An existing encrypted_data.token_reference_id object

data[].encrypted_data.token_service_provider.correlation_id

string
Conditionally returned

The unique identifier of the digital wallet token within the Mastercard card network.

Allowable Values:

An existing encrypted_data.token_service_provider.correlation_id object

data[].encrypted_data.token_service_provider.token_requestor_id

string
Returned

The unique numerical identifier of the token requestor within the card network. The token_requestor_id is unique at the card network level.

Allowable Values:

50 char max

data[].encrypted_data.token_service_provider.token_requestor_name

string
Returned

Specifies the name of the token requestor. Example values: APPLE_PAY, ANDROID_PAY, SAMSUNG_PAY.

Allowable Values:

100 char max

data[].encrypted_data.token_service_provider.token_type

string
Returned

The name of the token requestor within the card network.

Allowable Values:

MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET, PSEUDO_ACCOUNT

data[].encrypted_data.token_service_provider.token_pan

string
Conditionally returned

The digital wallet token primary account number (PAN), also known as Digital Account Number, Token Number, or Digital PAN (DPAN). These are unique only at a given point in time and are subject to reuse. This value is provided after a token is activated.

The token PAN appears in masked format. To view the token PAN in clear text, use the /showtokenpan endpoint.

Allowable Values:

A valid encrypted_data.token_service_provider.token_pan

data[].encrypted_data.token_service_provider.token_expiration

string
Conditionally returned

The expiration date of the digital wallet token in MMyy format. This value is provided after a token is activated.

Allowable Values:

4 char max

data[].encrypted_data.token_service_provider.token_assurance_level

string
Conditionally returned

Specifies the assurance level of the token-to-PAN binding as defined by the payment network. Represents a general risk value from 00 to 99.

Allowable Values:

2 char max

data[].encrypted_data.token_service_provider.token_score

string
Conditionally returned

The token score assigned by the token service provider. This value is provided when it is received by the token service provider.

Allowable Values:

25 char max

data[].encrypted_data.token_service_provider.token_eligibility_decision

string
Conditionally returned

The token service provider’s recommendation as to whether the digital wallet token should be provisioned.

Allowable Values:

50 char max

data[].encrypted_data.device

object
Conditionally returned

Contains information related to the device being provisioned. This object is returned when relevant information is provided by the token service provider, typically for device-based digital wallets such as Google Wallet and Apple Pay only.

Allowable Values:

An existing encrypted_data.device object

data[].encrypted_data.device.type

string
Returned

The type of device being provisioned.

Allowable Values:

MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET, PSEUDO_ACCOUNT

data[].encrypted_data.device.device_id

string
Conditionally returned

The identity number of the device. This value is returned if it is available for a given digital wallet token.

Allowable Values:

255 char max

data[].encrypted_data.device.phone_number

string
Conditionally returned

The telephone number of the device, as returned by the digital wallet provider. This value may be the full phone number, or just the last four digits.

Allowable Values:

20 char max

data[].encrypted_data.device.name

string
Conditionally returned

The name of the device, as returned by the digital wallet provider.

Allowable Values:

128 char max

data[].encrypted_data.device.location

string
Conditionally returned

The geographic coordinates of the device at the time of the tokenization request, as returned by the digital wallet provider.

Allowable Values:

25 char max

data[].encrypted_data.device.ip_address

string
Conditionally returned

The IP address of the device, as returned by the digital wallet provider.

Allowable Values:

An existing IP address

data[].encrypted_data.device.token

string
Conditionally returned

The unique identifier of the device object. This value, along with the subsequent data block, is returned if it is available for a given digital wallet token. It is typically available for Google Wallet, Samsung Wallet, and Apple Pay but not for ecommerce token requestors such as PayPal.

Allowable Values:

50 char max

data[].encrypted_data.device.language_code

string
Conditionally returned

The language the device is configured to use.

Allowable Values:

36 char max

data[].encrypted_data.address_verification

object
Conditionally returned

Contains the name and address of the cardholder for address verification.

Allowable Values:

A valid encrypted_data.address_verification object

data[].encrypted_data.address_verification.name

string
Returned

The name of the cardholder, as returned by the digital wallet provider.

Allowable Values:

255 char max

data[].encrypted_data.address_verification.street_address

string
Returned

The street address of the cardholder, as returned by the digital wallet provider.

Allowable Values:

255 char max

data[].encrypted_data.address_verification.postal_code

string
Returned

The postal code of the cardholder, such as a ZIP code, as returned by the digital wallet provider.

Allowable Values:

50 char max

data[].token_service_provider

object
Conditionally returned

Contains information held and provided by the token service provider (card network). This object is returned when relevant information is provided by the token service provider.

Allowable Values:

An existing token_service_provider object

data[].token_service_provider.pan_reference_id

string
Returned

The unique identifier of the digital wallet token PAN within the card network. This value may vary on a per-digital wallet basis. For example, the pan_reference_id may be different in Apple Pay and Google Wallet for the same digital wallet token.

Allowable Values:

255 char max

data[].token_service_provider.token_reference_id

string
Conditionally returned

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

Allowable Values:

An existing token_reference_id

data[].token_service_provider.correlation_id

string
Conditionally returned

The unique identifier of the digital wallet token within the Mastercard card network.

Allowable Values:

An existing correlation_id

data[].token_service_provider.token_requestor_id

string
Returned

The unique numerical identifier of the token requestor within the card network. The token_requestor_id is unique at the card network level.

Allowable Values:

50 char max

data[].token_service_provider.token_requestor_name

string
Returned

Specifies the name of the token requestor. Example values: APPLE_PAY, ANDROID_PAY, SAMSUNG_PAY.

Allowable Values:

100 char max

data[].token_service_provider.token_type

string
Returned

The name of the token requestor within the card network.

Allowable Values:

MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET, PSEUDO_ACCOUNT

data[].token_service_provider.token_pan

string
Conditionally returned

The digital wallet token primary account number (PAN), also known as Digital Account Number, Token Number, or Digital PAN (DPAN). These are unique only at a given point in time and are subject to reuse. This value is provided after a token is activated.

The token PAN appears in masked format. To view the token PAN in clear text, use the /showtokenpan endpoint.

Allowable Values:

An existing token PAN

data[].token_service_provider.token_expiration

string
Conditionally returned

The expiration date of the digital wallet token in MMyy format. This value is provided after a token is activated.

Allowable Values:

4 char max

data[].token_service_provider.token_assurance_level

string
Conditionally returned

Specifies the assurance level of the token-to-PAN binding as defined by the payment network. Represents a general risk value from 00 to 99.

Allowable Values:

2 char max

data[].token_service_provider.token_score

string
Conditionally returned

The token score assigned by the token service provider. This value is provided when it is received by the token service provider.

Allowable Values:

25 char max

data[].token_service_provider.token_eligibility_decision

string
Conditionally returned

The token service provider’s recommendation as to whether the digital wallet token should be provisioned.

Allowable Values:

50 char max

data[].device

object
Conditionally returned

Contains information related to the device being provisioned. This object is returned when relevant information is provided by the token service provider, typically for device-based digital wallets such as Google Wallet and Apple Pay only.

Allowable Values:

An existing device object

data[].device.type

string
Returned

The type of device being provisioned.

Allowable Values:

MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET, PSEUDO_ACCOUNT

data[].device.device_id

string
Conditionally returned

The identity number of the device. This value is returned if it is available for a given digital wallet token.

Allowable Values:

255 char max

data[].device.phone_number

string
Conditionally returned

The telephone number of the device, as returned by the digital wallet provider. This value may be the full phone number, or just the last four digits.

Allowable Values:

20 char max

data[].device.name

string
Conditionally returned

The name of the device, as returned by the digital wallet provider.

Allowable Values:

128 char max

data[].device.location

string
Conditionally returned

The geographic coordinates of the device at the time of the tokenization request, as returned by the digital wallet provider.

Allowable Values:

25 char max

data[].device.ip_address

string
Conditionally returned

The IP address of the device, as returned by the digital wallet provider.

Allowable Values:

A valid IP address

data[].device.token

string
Conditionally returned

The unique identifier of the device object. This value, along with the subsequent data block, is returned if it is available for a given digital wallet token. It is typically available for Google Wallet, Samsung Wallet, and Apple Pay but not for ecommerce token requestors such as PayPal.

Allowable Values:

50 char max

data[].device.language_code

string
Conditionally returned

The language the device is configured to use.

Allowable Values:

36 char max

data[].address_verification

object
Conditionally returned

Contains the name and address of the cardholder for address verification.

Allowable Values:

An existing address_verification object

data[].address_verification.name

string
Returned

The name of the cardholder, as returned by the digital wallet provider.

Allowable Values:

255 char max

data[].address_verification.street_address

string
Returned

The street address of the cardholder, as returned by the digital wallet provider.

Allowable Values:

255 char max

data[].address_verification.postal_code

string
Returned

The postal code of the cardholder, such as a ZIP code, as returned by the digital wallet provider.

Allowable Values:

50 char max

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

The Marqeta unique identifier for the digital wallet token.

Allowable Values:

An existing digital wallet token

Response body
Fields Description

token

string
Returned

The Marqeta unique identifier for the digital wallet token.

Allowable Values:

36 char max

card_token

string
Returned

The token that identifies the card and correlates it with the card issuer. This token is used to minimize the need to exchange card details during subsequent calls, and also for troubleshooting. Use a GUID or a pseudo-unique identifier for this token.

Allowable Values:

An existing card token

state

string
Conditionally returned

The current state of the digital wallet token. For example, REQUESTED, REQUEST_DECLINED, TERMINATED, SUSPENDED, ACTIVE.

Allowable Values:

255 char max

state_reason

string
Conditionally returned

A descriptive reason for the current state of the digital wallet token.

Allowable Values:

255 char max

fulfillment_status

string
Conditionally returned

The digital wallet token’s provisioning status. Example values: DECISION_RED, DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED.

Allowable Values:

255 char max

issuer_eligibility_decision

string
Conditionally returned

The Marqeta platform’s recommendation as to whether the digital wallet token should be provisioned. Example values: 0000 (Approved), invalid.cid, avs.decline, token.activation.

Allowable Values:

255 char max

wallet_provider_profile

object
Conditionally returned

Contains information held and provided by the digital wallet provider. This object is returned when relevant information is provided by the digital wallet provider.

Allowable Values:

A valid wallet_provider_profile object

wallet_provider_profile.account

object
Returned

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

Allowable Values:

An existing wallet_provider_profile.account object

wallet_provider_profile.account.id

string
Returned

The digital wallet provider’s unique identity number for the cardholder. This identity number does not correlate with other information.

Allowable Values:

255 char max

wallet_provider_profile.account.email_address

string
Conditionally returned

A hashed version of the email address linked to the digital wallet.

Allowable Values:

255 char max

wallet_provider_profile.account.score

string
Conditionally returned

The score from the digital wallet provider. This value is returned if it is provided by the digital wallet provider.

Allowable Values:

255 char max

wallet_provider_profile.risk_assessment

object
Conditionally returned

Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token, as returned by the digital wallet provider.

Allowable Values:

An existing wallet_provider_profile.risk_assessment object

wallet_provider_profile.risk_assessment.score

string
Conditionally returned

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

Allowable Values:

DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED

wallet_provider_profile.risk_assessment.version

string
Conditionally returned

The digital wallet provider’s risk version. Changes in the version may indicate differences in other fields.

Allowable Values:

255 char max

wallet_provider_profile.device_score

string
Conditionally returned

The score from the device, as returned by the digital wallet provider.

Allowable Values:

255 char max

wallet_provider_profile.pan_source

string
Returned

The source from which the digital wallet provider obtained the card PAN, as returned by the digital wallet provider.

Allowable Values:

KEY_ENTERED, ON_FILE, MOBILE_BANKING_APP

wallet_provider_profile.reason_code

string
Conditionally returned

The reason for the digital wallet provider’s provisioning decision.

Allowable Values:

100 char max

wallet_provider_profile.recommendation_reasons

array of strings
Conditionally returned

Provisioning decision recommendations, from Mastercard only.

Allowable Values:

A valid wallet_provider_profile.recommendation_reasons array

created_time

datetime
Conditionally returned

The date and time when the resource was created, in UTC. 2020-10-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

last_modified_time

datetime
Conditionally returned

The date and time when the resource was last modified, in UTC. 2020-10-26T20:03:10Z, for example.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

encrypted_data

object
Conditionally returned

The encrypted_data object contains encrypted versions of the token_service_provider, device, and address_verification objects.

Allowable Values:

An existing encrypted_data object

encrypted_data.token_service_provider

object
Conditionally returned

Contains information held and provided by the token service provider (card network). This object is returned when relevant information is provided by the token service provider.

Allowable Values:

An existing encrypted_data.token_service_provider object

encrypted_data.token_service_provider.pan_reference_id

string
Returned

The unique identifier of the digital wallet token PAN within the card network. This value may vary on a per-digital wallet basis. For example, the pan_reference_id may be different in Apple Pay and Google Wallet for the same digital wallet token.

Allowable Values:

255 char max

encrypted_data.token_service_provider.token_reference_id

string
Conditionally returned

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

Allowable Values:

255 char max

encrypted_data.token_service_provider.correlation_id

string
Conditionally returned

The unique identifier of the digital wallet token within the Mastercard card network.

Allowable Values:

255 char max

encrypted_data.token_service_provider.token_requestor_id

string
Returned

The unique numerical identifier of the token requestor within the card network. The token_requestor_id is unique at the card network level.

Allowable Values:

50 char max

encrypted_data.token_service_provider.token_requestor_name

string
Returned

Specifies the name of the token requestor. Example values: APPLE_PAY, ANDROID_PAY, SAMSUNG_PAY.

Allowable Values:

100 char max

encrypted_data.token_service_provider.token_type

string
Returned

The name of the token requestor within the card network.

Allowable Values:

MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET, PSEUDO_ACCOUNT

encrypted_data.token_service_provider.token_pan

string
Conditionally returned

The digital wallet token primary account number (PAN), also known as Digital Account Number, Token Number, or Digital PAN (DPAN). These are unique only at a given point in time and are subject to reuse. This value is provided after a token is activated.

The token PAN appears in masked format. To view the token PAN in clear text, use the /showtokenpan endpoint.

Allowable Values:

255 char max

encrypted_data.token_service_provider.token_expiration

string
Conditionally returned

The expiration date of the digital wallet token in MMyy format. This value is provided after a token is activated.

Allowable Values:

4 char max

encrypted_data.token_service_provider.token_assurance_level

string
Conditionally returned

Specifies the assurance level of the token-to-PAN binding as defined by the payment network. Represents a general risk value from 00 to 99.

Allowable Values:

2 char max

encrypted_data.token_service_provider.token_score

string
Conditionally returned

The token score assigned by the token service provider. This value is provided when it is received by the token service provider.

Allowable Values:

25 char max

encrypted_data.token_service_provider.token_eligibility_decision

string
Conditionally returned

The token service provider’s recommendation as to whether the digital wallet token should be provisioned.

Allowable Values:

50 char max

encrypted_data.device

object
Conditionally returned

Contains information related to the device being provisioned. This object is returned when relevant information is provided by the token service provider, typically for device-based digital wallets such as Google Wallet and Apple Pay only.

Allowable Values:

An existing encrypted_data.device object

encrypted_data.device.type

string
Returned

The type of device being provisioned.

Allowable Values:

MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET, PSEUDO_ACCOUNT

encrypted_data.device.device_id

string
Conditionally returned

The identity number of the device. This value is returned if it is available for a given digital wallet token.

Allowable Values:

255 char max

encrypted_data.device.phone_number

string
Conditionally returned

The telephone number of the device, as returned by the digital wallet provider. This value may be the full phone number, or just the last four digits.

Allowable Values:

20 char max

encrypted_data.device.name

string
Conditionally returned

The name of the device, as returned by the digital wallet provider.

Allowable Values:

128 char max

encrypted_data.device.location

string
Conditionally returned

The geographic coordinates of the device at the time of the tokenization request, as returned by the digital wallet provider.

Allowable Values:

25 char max

encrypted_data.device.ip_address

string
Conditionally returned

The IP address of the device, as returned by the digital wallet provider.

Allowable Values:

A valid IP address

encrypted_data.device.token

string
Conditionally returned

The unique identifier of the device object. This value, along with the subsequent data block, is returned if it is available for a given digital wallet token. It is typically available for Google Wallet, Samsung Wallet, and Apple Pay but not for ecommerce token requestors such as PayPal.

Allowable Values:

50 char max

encrypted_data.device.language_code

string
Conditionally returned

The language the device is configured to use.

Allowable Values:

36 char max

encrypted_data.address_verification

object
Conditionally returned

Contains the name and address of the cardholder for address verification.

Allowable Values:

An existing encrypted_data.address_verification object

encrypted_data.address_verification.name

string
Returned

The name of the cardholder, as returned by the digital wallet provider.

Allowable Values:

255 char max

encrypted_data.address_verification.street_address

string
Returned

The street address of the cardholder, as returned by the digital wallet provider.

Allowable Values:

255 char max

encrypted_data.address_verification.postal_code

string
Returned

The postal code of the cardholder, such as a ZIP code, as returned by the digital wallet provider.

Allowable Values:

50 char max

token_service_provider

object
Conditionally returned

Contains information held and provided by the token service provider (card network). This object is returned when relevant information is provided by the token service provider.

Allowable Values:

An existing token_service_provider object

token_service_provider.pan_reference_id

string
Returned

The unique identifier of the digital wallet token PAN within the card network. This value may vary on a per-digital wallet basis. For example, the pan_reference_id may be different in Apple Pay and Google Wallet for the same digital wallet token.

Allowable Values:

255 char max

token_service_provider.token_reference_id

string
Conditionally returned

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

Allowable Values:

255 char max

token_service_provider.correlation_id

string
Conditionally returned

The unique identifier of the digital wallet token within the Mastercard card network.

Allowable Values:

255 char max

token_service_provider.token_requestor_id

string
Returned

The unique numerical identifier of the token requestor within the card network. The token_requestor_id is unique at the card network level.

Allowable Values:

50 char max

token_service_provider.token_requestor_name

string
Returned

Specifies the name of the token requestor. Example values: APPLE_PAY, ANDROID_PAY, SAMSUNG_PAY.

Allowable Values:

100 char max

token_service_provider.token_type

string
Returned

The name of the token requestor within the card network.

Allowable Values:

MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET, PSEUDO_ACCOUNT

token_service_provider.token_pan

string
Conditionally returned

The digital wallet token primary account number (PAN), also known as Digital Account Number, Token Number, or Digital PAN (DPAN). These are unique only at a given point in time and are subject to reuse. This value is provided after a token is activated.

The token PAN appears in masked format. To view the token PAN in clear text, use the /showtokenpan endpoint.

Allowable Values:

255 char max

token_service_provider.token_expiration

string
Conditionally returned

The expiration date of the digital wallet token in MMyy format. This value is provided after a token is activated.

Allowable Values:

4 char max

token_service_provider.token_assurance_level

string
Conditionally returned

Specifies the assurance level of the token-to-PAN binding as defined by the payment network. Represents a general risk value from 00 to 99.

Allowable Values:

2 char max

token_service_provider.token_score

string
Conditionally returned

The token score assigned by the token service provider. This value is provided when it is received by the token service provider.

Allowable Values:

25 char max

token_service_provider.token_eligibility_decision

string
Conditionally returned

The token service provider’s recommendation as to whether the digital wallet token should be provisioned.

Allowable Values:

50 char max

device

object
Conditionally returned

Contains information related to the device being provisioned. This object is returned when relevant information is provided by the token service provider, typically for device-based digital wallets such as Google Wallet and Apple Pay only.

Allowable Values:

A valid device object

device.type

string
Returned

The type of device being provisioned.

Allowable Values:

MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET, PSEUDO_ACCOUNT

device.device_id

string
Conditionally returned

The identity number of the device. This value is returned if it is available for a given digital wallet token.

Allowable Values:

255 char max

device.phone_number

string
Conditionally returned

The telephone number of the device, as returned by the digital wallet provider. This value may be the full phone number, or just the last four digits.

Allowable Values:

20 char max

device.name

string
Conditionally returned

The name of the device, as returned by the digital wallet provider.

Allowable Values:

128 char max

device.location

string
Conditionally returned

The geographic coordinates of the device at the time of the tokenization request, as returned by the digital wallet provider.

Allowable Values:

25 char max

device.ip_address

string
Conditionally returned

The IP address of the device, as returned by the digital wallet provider.

Allowable Values:

A valid IP address

device.token

string
Conditionally returned

The unique identifier of the device object. This value, along with the subsequent data block, is returned if it is available for a given digital wallet token. It is typically available for Google Wallet, Samsung Wallet, and Apple Pay but not for ecommerce token requestors such as PayPal.

Allowable Values:

50 char max

device.language_code

string
Conditionally returned

The language the device is configured to use.

Allowable Values:

36 char max

address_verification

object
Conditionally returned

Contains the name and address of the cardholder for address verification.

Allowable Values:

An existing address_verification object

address_verification.name

string
Returned

The name of the cardholder, as returned by the digital wallet provider.

Allowable Values:

255 char max

address_verification.street_address

string
Returned

The street address of the cardholder, as returned by the digital wallet provider.

Allowable Values:

255 char max

address_verification.postal_code

string
Returned

The postal code of the cardholder, such as a ZIP code, as returned by the digital wallet provider.

Allowable Values:

50 char max

List digital wallet tokens by card

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

Retrieve a list of digital wallet tokens for the specified card.

URL path parameters
Fields Description

card_token

string
Required

The token that identifies the card and correlates it with the card issuer. This token is used to minimize the need to exchange card details during subsequent calls, and also for troubleshooting. Use a GUID or a pseudo-unique identifier for this token.

Allowable Values:

An existing card token

URL query parameters
Fields Description

count

integer
Optional

The number of digital wallet tokens to retrieve.

Allowable Values:

1-10

start_index

integer
Optional

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

Allowable Values:

Any integer

sort_by

string
Optional

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

Allowable Values:

lastModifiedTime, createdTime, or any field in the resource model

Response body
Fields Description

count

integer
Returned

The number of resources returned.

Allowable Values:

1-10

start_index

integer
Returned

The sort order index of the first resource in the returned array.

Allowable Values:

Any integer

end_index

integer
Returned

The sort order index of the last resource in the returned array.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist.

Allowable Values:

true, false

data

array of objects
Conditionally returned

Contains the returned resources.

Allowable Values:

A valid data array

data[].token

string
Returned

The Marqeta unique identifier for the digital wallet token.

Allowable Values:

36 char max

data[].card_token

string
Returned

The token that identifies the card and correlates it with the card issuer. This token is used to minimize the need to exchange card details during subsequent calls, and also for troubleshooting. Use a GUID or a pseudo-unique identifier for this token.

Allowable Values:

An existing card token

data[].state

string
Conditionally returned

The current state of the digital wallet token. For example, REQUESTED, REQUEST_DECLINED, TERMINATED, SUSPENDED, ACTIVE.

Allowable Values:

255 char max

data[].state_reason

string
Conditionally returned

A descriptive reason for the current state of the digital wallet token.

Allowable Values:

255 char max

data[].fulfillment_status

string
Conditionally returned

The digital wallet token’s provisioning status. Example values: DECISION_RED, DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED.

Allowable Values:

255 char max

data[].issuer_eligibility_decision

string
Conditionally returned

The Marqeta platform’s recommendation as to whether the digital wallet token should be provisioned. Example values: 0000 (Approved), invalid.cid, avs.decline, token.activation.

Allowable Values:

255 char max

data[].wallet_provider_profile

object
Conditionally returned

Contains information held and provided by the digital wallet provider. This object is returned when relevant information is provided by the digital wallet provider.

Allowable Values:

An existing wallet_provider_profile

data[].wallet_provider_profile.account

object
Returned

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

Allowable Values:

An existing wallet_provider_profile.account object

data[].wallet_provider_profile.account.id

string
Returned

The digital wallet provider’s unique identity number for the cardholder. This identity number does not correlate with other information.

Allowable Values:

255 char max

data[].wallet_provider_profile.account.email_address

string
Conditionally returned

A hashed version of the email address linked to the digital wallet.

Allowable Values:

A valid email address

data[].wallet_provider_profile.account.score

string
Conditionally returned

The score from the digital wallet provider. This value is returned if it is provided by the digital wallet provider.

Allowable Values:

255 char max

data[].wallet_provider_profile.risk_assessment

object
Conditionally returned

Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token, as returned by the digital wallet provider.

Allowable Values:

An existing wallet_provider_profile.risk_assessment object

data[].wallet_provider_profile.risk_assessment.score

string
Conditionally returned

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

Allowable Values:

DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED

data[].wallet_provider_profile.risk_assessment.version

string
Conditionally returned

The digital wallet provider’s risk version. Changes in the version may indicate differences in other fields.

Allowable Values:

255 char max

data[].wallet_provider_profile.device_score

string
Conditionally returned

The score from the device, as returned by the digital wallet provider.

Allowable Values:

255 char max

data[].wallet_provider_profile.pan_source

string
Returned

The source from which the digital wallet provider obtained the card PAN, as returned by the digital wallet provider.

Allowable Values:

KEY_ENTERED, ON_FILE, MOBILE_BANKING_APP

data[].wallet_provider_profile.reason_code

string
Conditionally returned

The reason for the digital wallet provider’s provisioning decision.

Allowable Values:

100 char max

data[].wallet_provider_profile.recommendation_reasons

array of strings
Conditionally returned

Provisioning decision recommendations, from Mastercard only.

Allowable Values:

A valid wallet_provider_profile.recommendation_reasons array

data[].created_time

datetime
Conditionally returned

The date and time when the resource was created, in UTC. 2020-10-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

data[].last_modified_time

datetime
Conditionally returned

The date and time when the resource was last modified, in UTC. 2020-10-26T20:03:10Z, for example.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

data[].encrypted_data

object
Conditionally returned

The encrypted_data object contains encrypted versions of the token_service_provider, device, and address_verification objects.

Allowable Values:

An existing encrypted_data object

data[].encrypted_data.token_service_provider

object
Conditionally returned

Contains information held and provided by the token service provider (card network). This object is returned when relevant information is provided by the token service provider.

Allowable Values:

An existing encrypted_data.token_service_provider object

data[].encrypted_data.token_service_provider.pan_reference_id

string
Returned

The unique identifier of the digital wallet token PAN within the card network. This value may vary on a per-digital wallet basis. For example, the pan_reference_id may be different in Apple Pay and Google Wallet for the same digital wallet token.

Allowable Values:

255 char max

data[].encrypted_data.token_service_provider.token_reference_id

string
Conditionally returned

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

Allowable Values:

255 char max

data[].encrypted_data.token_service_provider.correlation_id

string
Conditionally returned

The unique identifier of the digital wallet token within the Mastercard card network.

Allowable Values:

255 char max

data[].encrypted_data.token_service_provider.token_requestor_id

string
Returned

The unique numerical identifier of the token requestor within the card network. The token_requestor_id is unique at the card network level.

Allowable Values:

50 char max

data[].encrypted_data.token_service_provider.token_requestor_name

string
Returned

Specifies the name of the token requestor. Example values: APPLE_PAY, ANDROID_PAY, SAMSUNG_PAY.

Allowable Values:

100 char max

data[].encrypted_data.token_service_provider.token_type

string
Returned

The name of the token requestor within the card network.

Allowable Values:

MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET, PSEUDO_ACCOUNT

data[].encrypted_data.token_service_provider.token_pan

string
Conditionally returned

The digital wallet token primary account number (PAN), also known as Digital Account Number, Token Number, or Digital PAN (DPAN). These are unique only at a given point in time and are subject to reuse. This value is provided after a token is activated.

The token PAN appears in masked format. To view the token PAN in clear text, use the /showtokenpan endpoint.

Allowable Values:

255 char max

data[].encrypted_data.token_service_provider.token_expiration

string
Conditionally returned

The expiration date of the digital wallet token in MMyy format. This value is provided after a token is activated.

Allowable Values:

4 char max

data[].encrypted_data.token_service_provider.token_assurance_level

string
Conditionally returned

Specifies the assurance level of the token-to-PAN binding as defined by the payment network. Represents a general risk value from 00 to 99.

Allowable Values:

2 char max

data[].encrypted_data.token_service_provider.token_score

string
Conditionally returned

The token score assigned by the token service provider. This value is provided when it is received by the token service provider.

Allowable Values:

25 char max

data[].encrypted_data.token_service_provider.token_eligibility_decision

string
Conditionally returned

The token service provider’s recommendation as to whether the digital wallet token should be provisioned.

Allowable Values:

50 char max

data[].encrypted_data.device

object
Conditionally returned

Contains information related to the device being provisioned. This object is returned when relevant information is provided by the token service provider, typically for device-based digital wallets such as Google Wallet and Apple Pay only.

Allowable Values:

An existing encrypted_data.device object

data[].encrypted_data.device.type

string
Returned

The type of device being provisioned.

Allowable Values:

MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET, PSEUDO_ACCOUNT

data[].encrypted_data.device.device_id

string
Conditionally returned

The identity number of the device. This value is returned if it is available for a given digital wallet token.

Allowable Values:

255 char max

data[].encrypted_data.device.phone_number

string
Conditionally returned

The telephone number of the device, as returned by the digital wallet provider. This value may be the full phone number, or just the last four digits.

Allowable Values:

20 char max

data[].encrypted_data.device.name

string
Conditionally returned

The name of the device, as returned by the digital wallet provider.

Allowable Values:

128 char max

data[].encrypted_data.device.location

string
Conditionally returned

The geographic coordinates of the device at the time of the tokenization request, as returned by the digital wallet provider.

Allowable Values:

25 char max

data[].encrypted_data.device.ip_address

string
Conditionally returned

The IP address of the device, as returned by the digital wallet provider.

Allowable Values:

A valid IP address

data[].encrypted_data.device.token

string
Conditionally returned

The unique identifier of the device object. This value, along with the subsequent data block, is returned if it is available for a given digital wallet token. It is typically available for Google Wallet, Samsung Wallet, and Apple Pay but not for ecommerce token requestors such as PayPal.

Allowable Values:

50 char max

data[].encrypted_data.device.language_code

string
Conditionally returned

The language the device is configured to use.

Allowable Values:

36 char max

data[].encrypted_data.address_verification

object
Conditionally returned

Contains the name and address of the cardholder for address verification.

Allowable Values:

An existing encrypted_data.address_verification object

data[].encrypted_data.address_verification.name

string
Returned

The name of the cardholder, as returned by the digital wallet provider.

Allowable Values:

255 char max

data[].encrypted_data.address_verification.street_address

string
Returned

The street address of the cardholder, as returned by the digital wallet provider.

Allowable Values:

255 char max

data[].encrypted_data.address_verification.postal_code

string
Returned

The postal code of the cardholder, such as a ZIP code, as returned by the digital wallet provider.

Allowable Values:

50 char max

data[].token_service_provider

object
Conditionally returned

Contains information held and provided by the token service provider (card network). This object is returned when relevant information is provided by the token service provider.

Allowable Values:

An existing token_service_provider object

data[].token_service_provider.pan_reference_id

string
Returned

The unique identifier of the digital wallet token PAN within the card network. This value may vary on a per-digital wallet basis. For example, the pan_reference_id may be different in Apple Pay and Google Wallet for the same digital wallet token.

Allowable Values:

255 char max

data[].token_service_provider.token_reference_id

string
Conditionally returned

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

Allowable Values:

255 char max

data[].token_service_provider.correlation_id

string
Conditionally returned

The unique identifier of the digital wallet token within the Mastercard card network.

Allowable Values:

255 char max

data[].token_service_provider.token_requestor_id

string
Returned

The unique numerical identifier of the token requestor within the card network. The token_requestor_id is unique at the card network level.

Allowable Values:

50 char max

data[].token_service_provider.token_requestor_name

string
Returned

Specifies the name of the token requestor. Example values: APPLE_PAY, ANDROID_PAY, SAMSUNG_PAY.

Allowable Values:

100 char max

data[].token_service_provider.token_type

string
Returned

The name of the token requestor within the card network.

Allowable Values:

MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET, PSEUDO_ACCOUNT

data[].token_service_provider.token_pan

string
Conditionally returned

The digital wallet token primary account number (PAN), also known as Digital Account Number, Token Number, or Digital PAN (DPAN). These are unique only at a given point in time and are subject to reuse. This value is provided after a token is activated.

The token PAN appears in masked format. To view the token PAN in clear text, use the /showtokenpan endpoint.

Allowable Values:

255 char max

data[].token_service_provider.token_expiration

string
Conditionally returned

The expiration date of the digital wallet token in MMyy format. This value is provided after a token is activated.

Allowable Values:

4 char max

data[].token_service_provider.token_assurance_level

string
Conditionally returned

Specifies the assurance level of the token-to-PAN binding as defined by the payment network. Represents a general risk value from 00 to 99.

Allowable Values:

2 char max

data[].token_service_provider.token_score

string
Conditionally returned

The token score assigned by the token service provider. This value is provided when it is received by the token service provider.

Allowable Values:

25 char max

data[].token_service_provider.token_eligibility_decision

string
Conditionally returned

The token service provider’s recommendation as to whether the digital wallet token should be provisioned.

Allowable Values:

50 char max

data[].device

object
Conditionally returned

Contains information related to the device being provisioned. This object is returned when relevant information is provided by the token service provider, typically for device-based digital wallets such as Google Wallet and Apple Pay only.

Allowable Values:

An existing device object

data[].device.type

string
Returned

The type of device being provisioned.

Allowable Values:

MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET, PSEUDO_ACCOUNT

data[].device.device_id

string
Conditionally returned

The identity number of the device. This value is returned if it is available for a given digital wallet token.

Allowable Values:

255 char max

data[].device.phone_number

string
Conditionally returned

The telephone number of the device, as returned by the digital wallet provider. This value may be the full phone number, or just the last four digits.

Allowable Values:

20 char max

data[].device.name

string
Conditionally returned

The name of the device, as returned by the digital wallet provider.

Allowable Values:

128 char max

data[].device.location

string
Conditionally returned

The geographic coordinates of the device at the time of the tokenization request, as returned by the digital wallet provider.

Allowable Values:

25 char max

data[].device.ip_address

string
Conditionally returned

The IP address of the device, as returned by the digital wallet provider.

Allowable Values:

A valid IP address

data[].device.token

string
Conditionally returned

The unique identifier of the device object. This value, along with the subsequent data block, is returned if it is available for a given digital wallet token. It is typically available for Google Wallet, Samsung Wallet, and Apple Pay but not for ecommerce token requestors such as PayPal.

Allowable Values:

50 char max

data[].device.language_code

string
Conditionally returned

The language the device is configured to use.

Allowable Values:

36 char max

data[].address_verification

object
Conditionally returned

Contains the name and address of the cardholder for address verification.

Allowable Values:

An existing address_verification object

data[].address_verification.name

string
Returned

The name of the cardholder, as returned by the digital wallet provider.

Allowable Values:

255 char max

data[].address_verification.street_address

string
Returned

The street address of the cardholder, as returned by the digital wallet provider.

Allowable Values:

255 char max

data[].address_verification.postal_code

string
Returned

The postal code of the cardholder, such as a ZIP code, as returned by the digital wallet provider.

Allowable Values:

50 char max

Retrieve digital wallet token with PAN visible

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

Use this endpoint to retrieve a digital wallet token with the entire 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}.)

URL path parameters
Fields Description

token

string
Required

The Marqeta unique identifier for the digital wallet token.

Allowable Values:

An existing digital wallet token

Response body
Fields Description

token

string
Returned

The Marqeta unique identifier for the digital wallet token.

Allowable Values:

36 char max

card_token

string
Returned

The token that identifies the card and correlates it with the card issuer. This token is used to minimize the need to exchange card details during subsequent calls, and also for troubleshooting. Use a GUID or a pseudo-unique identifier for this token.

Allowable Values:

An existing card token

state

string
Conditionally returned

The current state of the digital wallet token. For example, REQUESTED, REQUEST_DECLINED, TERMINATED, SUSPENDED, ACTIVE.

Allowable Values:

255 char max

state_reason

string
Conditionally returned

A descriptive reason for the current state of the digital wallet token.

Allowable Values:

255 char max

fulfillment_status

string
Conditionally returned

The digital wallet token’s provisioning status. Example values: DECISION_RED, DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED.

Allowable Values:

255 char max

issuer_eligibility_decision

string
Conditionally returned

The Marqeta platform’s recommendation as to whether the digital wallet token should be provisioned. Example values: 0000 (Approved), invalid.cid, avs.decline, token.activation.

Allowable Values:

255 char max

wallet_provider_profile

object
Conditionally returned

Contains information held and provided by the digital wallet provider. This object is returned when relevant information is provided by the digital wallet provider.

Allowable Values:

An existing wallet_provider_profile object

wallet_provider_profile.account

object
Returned

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

Allowable Values:

An existing wallet_provider_profile,account object

wallet_provider_profile.account.id

string
Returned

The digital wallet provider’s unique identity number for the cardholder. This identity number does not correlate with other information.

Allowable Values:

255 char max

wallet_provider_profile.account.email_address

string
Conditionally returned

A hashed version of the email address linked to the digital wallet.

Allowable Values:

255 char max

wallet_provider_profile.account.score

string
Conditionally returned

The score from the digital wallet provider. This value is returned if it is provided by the digital wallet provider.

Allowable Values:

255 char max

wallet_provider_profile.risk_assessment

object
Conditionally returned

Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token, as returned by the digital wallet provider.

Allowable Values:

An existing wallet_provider_profile.risk_assessment object

wallet_provider_profile.risk_assessment.score

string
Conditionally returned

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

Allowable Values:

DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED

wallet_provider_profile.risk_assessment.version

string
Conditionally returned

The digital wallet provider’s risk version. Changes in the version may indicate differences in other fields.

Allowable Values:

255 char max

wallet_provider_profile.device_score

string
Conditionally returned

The score from the device, as returned by the digital wallet provider.

Allowable Values:

255 char max

wallet_provider_profile.pan_source

string
Returned

The source from which the digital wallet provider obtained the card PAN, as returned by the digital wallet provider.

Allowable Values:

KEY_ENTERED, ON_FILE, MOBILE_BANKING_APP

wallet_provider_profile.reason_code

string
Conditionally returned

The reason for the digital wallet provider’s provisioning decision.

Allowable Values:

100 char max

wallet_provider_profile.recommendation_reasons

array of strings
Conditionally returned

Provisioning decision recommendations, from Mastercard only.

Allowable Values:

A valid wallet_provider_profile.recommendation_reasons array

created_time

datetime
Conditionally returned

The date and time when the resource was created, in UTC. 2020-10-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

last_modified_time

datetime
Conditionally returned

The date and time when the resource was last modified, in UTC. 2020-10-26T20:03:10Z, for example.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

encrypted_data

object
Conditionally returned

The encrypted_data object contains encrypted versions of the token_service_provider, device, and address_verification objects.

Allowable Values:

An existing encrypted_data object

encrypted_data.token_service_provider

object
Conditionally returned

Contains information held and provided by the token service provider (card network). This object is returned when relevant information is provided by the token service provider.

Allowable Values:

An existing encrypted_data.token_service_provider object

encrypted_data.token_service_provider.pan_reference_id

string
Returned

The unique identifier of the digital wallet token PAN within the card network. This value may vary on a per-digital wallet basis. For example, the pan_reference_id may be different in Apple Pay and Google Wallet for the same digital wallet token.

Allowable Values:

255 char max

encrypted_data.token_service_provider.token_reference_id

string
Conditionally returned

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

Allowable Values:

255 char max

encrypted_data.token_service_provider.correlation_id

string
Conditionally returned

The unique identifier of the digital wallet token within the Mastercard card network.

Allowable Values:

255 char max

encrypted_data.token_service_provider.token_requestor_id

string
Returned

The unique numerical identifier of the token requestor within the card network. The token_requestor_id is unique at the card network level.

Allowable Values:

50 char max

encrypted_data.token_service_provider.token_requestor_name

string
Returned

Specifies the name of the token requestor. Example values: APPLE_PAY, ANDROID_PAY, SAMSUNG_PAY.

Allowable Values:

100 char max

encrypted_data.token_service_provider.token_type

string
Returned

The name of the token requestor within the card network.

Allowable Values:

MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET, PSEUDO_ACCOUNT

encrypted_data.token_service_provider.token_pan

string
Conditionally returned

The digital wallet token primary account number (PAN), also known as Digital Account Number, Token Number, or Digital PAN (DPAN). These are unique only at a given point in time and are subject to reuse. This value is provided after a token is activated.

The token PAN appears in masked format. To view the token PAN in clear text, use the /showtokenpan endpoint.

Allowable Values:

255 char max

encrypted_data.token_service_provider.token_expiration

string
Conditionally returned

The expiration date of the digital wallet token in MMyy format. This value is provided after a token is activated.

Allowable Values:

4 char max

encrypted_data.token_service_provider.token_assurance_level

string
Conditionally returned

Specifies the assurance level of the token-to-PAN binding as defined by the payment network. Represents a general risk value from 00 to 99.

Allowable Values:

2 char max

encrypted_data.token_service_provider.token_score

string
Conditionally returned

The token score assigned by the token service provider. This value is provided when it is received by the token service provider.

Allowable Values:

25 char max

encrypted_data.token_service_provider.token_eligibility_decision

string
Conditionally returned

The token service provider’s recommendation as to whether the digital wallet token should be provisioned.

Allowable Values:

50 char max

encrypted_data.device

object
Conditionally returned

Contains information related to the device being provisioned. This object is returned when relevant information is provided by the token service provider, typically for device-based digital wallets such as Google Wallet and Apple Pay only.

Allowable Values:

An existing encrypted_data.device object

encrypted_data.device.type

string
Returned

The type of device being provisioned.

Allowable Values:

MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET, PSEUDO_ACCOUNT

encrypted_data.device.device_id

string
Conditionally returned

The identity number of the device. This value is returned if it is available for a given digital wallet token.

Allowable Values:

255 char max

encrypted_data.device.phone_number

string
Conditionally returned

The telephone number of the device, as returned by the digital wallet provider. This value may be the full phone number, or just the last four digits.

Allowable Values:

20 char max

encrypted_data.device.name

string
Conditionally returned

The name of the device, as returned by the digital wallet provider.

Allowable Values:

128 char max

encrypted_data.device.location

string
Conditionally returned

The geographic coordinates of the device at the time of the tokenization request, as returned by the digital wallet provider.

Allowable Values:

25 char max

encrypted_data.device.ip_address

string
Conditionally returned

The IP address of the device, as returned by the digital wallet provider.

Allowable Values:

255 char max

encrypted_data.device.token

string
Conditionally returned

The unique identifier of the device object. This value, along with the subsequent data block, is returned if it is available for a given digital wallet token. It is typically available for Google Wallet, Samsung Wallet, and Apple Pay but not for ecommerce token requestors such as PayPal.

Allowable Values:

50 char max

encrypted_data.device.language_code

string
Conditionally returned

The language the device is configured to use.

Allowable Values:

36 char max

encrypted_data.address_verification

object
Conditionally returned

Contains the name and address of the cardholder for address verification.

Allowable Values:

An existing encrypted_data.address_verification object

encrypted_data.address_verification.name

string
Returned

The name of the cardholder, as returned by the digital wallet provider.

Allowable Values:

255 char max

encrypted_data.address_verification.street_address

string
Returned

The street address of the cardholder, as returned by the digital wallet provider.

Allowable Values:

255 char max

encrypted_data.address_verification.postal_code

string
Returned

The postal code of the cardholder, such as a ZIP code, as returned by the digital wallet provider.

Allowable Values:

50 char max

token_service_provider

object
Conditionally returned

Contains information held and provided by the token service provider (card network). This object is returned when relevant information is provided by the token service provider.

Allowable Values:

An existing token_service_provider object

token_service_provider.pan_reference_id

string
Returned

The unique identifier of the digital wallet token PAN within the card network. This value may vary on a per-digital wallet basis. For example, the pan_reference_id may be different in Apple Pay and Google Wallet for the same digital wallet token.

Allowable Values:

255 char max

token_service_provider.token_reference_id

string
Conditionally returned

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

Allowable Values:

255 char max

token_service_provider.correlation_id

string
Conditionally returned

The unique identifier of the digital wallet token within the Mastercard card network.

Allowable Values:

255 char max

token_service_provider.token_requestor_id

string
Returned

The unique numerical identifier of the token requestor within the card network. The token_requestor_id is unique at the card network level.

Allowable Values:

50 char max

token_service_provider.token_requestor_name

string
Returned

Specifies the name of the token requestor. Example values: APPLE_PAY, ANDROID_PAY, SAMSUNG_PAY.

Allowable Values:

100 char max

token_service_provider.token_type

string
Returned

The name of the token requestor within the card network.

Allowable Values:

MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET, PSEUDO_ACCOUNT

token_service_provider.token_pan

string
Conditionally returned

The digital wallet token primary account number (PAN), also known as Digital Account Number, Token Number, or Digital PAN (DPAN). These are unique only at a given point in time and are subject to reuse. This value is provided after a token is activated.

The token PAN appears in masked format. To view the token PAN in clear text, use the /showtokenpan endpoint.

Allowable Values:

255 char max

token_service_provider.token_expiration

string
Conditionally returned

The expiration date of the digital wallet token in MMyy format. This value is provided after a token is activated.

Allowable Values:

4 char max

token_service_provider.token_assurance_level

string
Conditionally returned

Specifies the assurance level of the token-to-PAN binding as defined by the payment network. Represents a general risk value from 00 to 99.

Allowable Values:

2 char max

token_service_provider.token_score

string
Conditionally returned

The token score assigned by the token service provider. This value is provided when it is received by the token service provider.

Allowable Values:

25 char max

token_service_provider.token_eligibility_decision

string
Conditionally returned

The token service provider’s recommendation as to whether the digital wallet token should be provisioned.

Allowable Values:

50 char max

device

object
Conditionally returned

Contains information related to the device being provisioned. This object is returned when relevant information is provided by the token service provider, typically for device-based digital wallets such as Google Wallet and Apple Pay only.

Allowable Values:

An existing device object

device.type

string
Returned

The type of device being provisioned.

Allowable Values:

MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET, PSEUDO_ACCOUNT

device.device_id

string
Conditionally returned

The identity number of the device. This value is returned if it is available for a given digital wallet token.

Allowable Values:

255 char max

device.phone_number

string
Conditionally returned

The telephone number of the device, as returned by the digital wallet provider. This value may be the full phone number, or just the last four digits.

Allowable Values:

20 char max

device.name

string
Conditionally returned

The name of the device, as returned by the digital wallet provider.

Allowable Values:

128 char max

device.location

string
Conditionally returned

The geographic coordinates of the device at the time of the tokenization request, as returned by the digital wallet provider.

Allowable Values:

25 char max

device.ip_address

string
Conditionally returned

The IP address of the device, as returned by the digital wallet provider.

Allowable Values:

A valid IP address

device.token

string
Conditionally returned

The unique identifier of the device object. This value, along with the subsequent data block, is returned if it is available for a given digital wallet token. It is typically available for Google Wallet, Samsung Wallet, and Apple Pay but not for ecommerce token requestors such as PayPal.

Allowable Values:

50 char max

device.language_code

string
Conditionally returned

The language the device is configured to use.

Allowable Values:

36 char max

address_verification

object
Conditionally returned

Contains the name and address of the cardholder for address verification.

Allowable Values:

An existing address_verification object

address_verification.name

string
Returned

The name of the cardholder, as returned by the digital wallet provider.

Allowable Values:

255 char max

address_verification.street_address

string
Returned

The street address of the cardholder, as returned by the digital wallet provider.

Allowable Values:

255 char max

address_verification.postal_code

string
Returned

The postal code of the cardholder, such as a ZIP code, as returned by the digital wallet provider.

Allowable Values:

50 char max

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

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

reason_code

string
Required

The two-digit reason code for the transition.

Allowable Values:

Two digits

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. This is the primary identifier for Visa.

Allowable Values:

An existing token_reference_id

channel

string
Required

The mechanism by which the transition was initiated. API, for example.

Allowable Values:

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

state

string
Required

Specifies the state to which the digital wallet token transitions.

Allowable Values:

REQUESTED, ACTIVE, TERMINATED, SUSPENDED, REQUEST_DECLINED

digital_wallet_token

object
Required

The Marqeta unique identifier for the digital wallet token.

Allowable Values:

An existing digital_wallet_token object

digital_wallet_token.token

string
Required

The Marqeta unique identifier for the digital wallet token.

Allowable Values:

1-36 chars

reason

string
Optional

A descriptive reason for the transition.

Allowable Values:

255 char max

Response body
Fields Description

token

string
Returned

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

Allowable Values:

1-36 chars

digital_wallet_token

object
Returned

The Marqeta unique identifier for the digital wallet token.

Allowable Values:

An existing digital_wallet_token object

digital_wallet_token.token

string
Returned

The Marqeta unique identifier for the digital wallet token.

Allowable Values:

1-36 chars

card_swap

object
Conditionally returned

Specifies the old and new payment card tokens that were swapped.

Allowable Values:

An existing card_swap object

card_swap.previousCardToken

string
Returned

The existing payment card token that has digital wallet tokens assigned to it.

Allowable Values:

1-36 chars

card_swap.newCardToken

string
Returned

The new payment card token to which the digital wallet tokens are assigned.

Allowable Values:

1-36 chars

type

string
Returned

The type of digital wallet token transition. state.activated, for example.

Allowable Values:

36 char max

channel

string
Returned

The mechanism by which the transition was initiated.

Allowable Values:

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

state

string
Returned

Specifies the state to which the digital wallet token transitions.

Allowable Values:

REQUESTED, ACTIVE, TERMINATED, SUSPENDED, REQUEST_DECLINED

fulfillment_status

string
Returned

The digital wallet token’s provisioning status.

Allowable Values:

DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED

reason

string
Conditionally returned

A descriptive reason for the transition.

Allowable Values:

255 char max

reason_code

string
Returned

The two-digit reason code for the transition.

Allowable Values:

Two digits

created_time

datetime
Returned

The date and time when the digital wallet token transition was created, in UTC. 2020-10-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

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

The digital wallet token associated with the transitions.

Allowable Values:

An existing digital wallet token

URL query parameters
Fields Description

count

integer
Optional

The number of digital wallet token transitions to retrieve.

Allowable Values:

1-10

start_index

integer
Optional

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

Allowable Values:

Any integer

sort_by

string
Optional

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

Allowable Values:

lastModifiedTime, createdTime, or any field in the resource model

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:

A comma-delimited list of fields, or blank

Response body
Fields Description

count

integer
Returned

The number of resources returned.

Allowable Values:

1-10

start_index

integer
Returned

The sort order index of the first resource in the returned array.

Allowable Values:

Any integer

end_index

integer
Returned

The sort order index of the last resource in the returned array.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist.

Allowable Values:

true, false

data

array of objects
Conditionally returned

Returns an array of objects related to the digital wallet token transition.

Allowable Values:

A valid data array

data[].token

string
Returned

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

Allowable Values:

1-36 chars

data[].digital_wallet_token

object
Returned

The Marqeta unique identifier for the digital wallet token.

Allowable Values:

An existing digital_wallet_token object

data[].digital_wallet_token.token

string
Returned

The Marqeta unique identifier for the digital wallet token.

Allowable Values:

1-36 chars

data[].card_swap

object
Conditionally returned

Specifies the old and new payment card tokens that were swapped.

Allowable Values:

An existing card_swap object

data[].card_swap.previousCardToken

string
Returned

The existing payment card token that has digital wallet tokens assigned to it.

Allowable Values:

1-36 chars

data[].card_swap.newCardToken

string
Returned

The new payment card token to which the digital wallet tokens are assigned.

Allowable Values:

1-36 chars

data[].type

string
Returned

The type of digital wallet token transition. state.activated, for example.

Allowable Values:

36 char max

data[].channel

string
Returned

The mechanism by which the transition was initiated.

Allowable Values:

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

data[].state

string
Returned

Specifies the state to which the digital wallet token transitions.

Allowable Values:

REQUESTED, ACTIVE, TERMINATED, SUSPENDED, REQUEST_DECLINED

data[].fulfillment_status

string
Returned

The digital wallet token’s provisioning status.

Allowable Values:

DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED

data[].reason

string
Conditionally returned

A descriptive reason for the transition.

Allowable Values:

255 char max

data[].reason_code

string
Returned

The two-digit reason code for the transition.

Allowable Values:

Two digits

data[].created_time

datetime
Returned

The date and time when the digital wallet token transition was created, in UTC. 2020-10-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

Retrieve digital wallet token transition

Action: GET
Endpoint: /digitalwallettokentransitions/{token}

Retrieve a specific digital wallet token transition.

URL path parameters
Fields Description

token

string
Required

The transition token.

Allowable Values:

An existing 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:

A comma-delimited list of fields, or blank

Response body
Fields Description

count

integer
Returned

The number of resources returned.

Allowable Values:

1-10

start_index

integer
Returned

The sort order index of the first resource in the returned array.

Allowable Values:

Any integer

end_index

integer
Returned

The sort order index of the last resource in the returned array.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist.

Allowable Values:

true, false

data

array of objects
Conditionally returned

Returns an array of objects related to the digital wallet token transition.

Allowable Values:

A valid data array

data[].token

string
Returned

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

Allowable Values:

1-36 chars

data[].digital_wallet_token

object
Returned

The Marqeta unique identifier for the digital wallet token.

Allowable Values:

An existing digital_wallet_token object

data[].digital_wallet_token.token

string
Returned

The Marqeta unique identifier for the digital wallet token.

Allowable Values:

1-36 chars

data[].card_swap

object
Conditionally returned

Specifies the old and new payment card tokens that were swapped.

Allowable Values:

An existing card_swap object

data[].card_swap.previousCardToken

string
Returned

The existing payment card token that has digital wallet tokens assigned to it.

Allowable Values:

1-36 chars

data[].card_swap.newCardToken

string
Returned

The new payment card token to which the digital wallet tokens are assigned.

Allowable Values:

1-36 chars

data[].type

string
Returned

The type of digital wallet token transition. state.activated, for example.

Allowable Values:

36 char max

data[].channel

string
Returned

The mechanism by which the transition was initiated.

Allowable Values:

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

data[].state

string
Returned

Specifies the state to which the digital wallet token transitions.

Allowable Values:

REQUESTED, ACTIVE, TERMINATED, SUSPENDED, REQUEST_DECLINED

data[].fulfillment_status

string
Returned

The digital wallet token’s provisioning status.

Allowable Values:

DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED

data[].reason

string
Conditionally returned

A descriptive reason for the transition.

Allowable Values:

255 char max

data[].reason_code

string
Returned

The two-digit reason code for the transition.

Allowable Values:

Two digits

data[].created_time

datetime
Returned

The date and time when the digital wallet token transition was created, in UTC. 2020-10-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

Create digital wallet provision request for Android Pay

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

encrypted_card_data

object
Required

The card details encrypted using JSON Web Encryption (JWE).

Allowable Values:

A valid encrypted_card_data object

encrypted_card_data.expiration

object
Required

Specifies the expiry date for the card.

Allowable Values:

A valid encrypted_card_data.expiration object

encrypted_card_data.expiration.month

string
Required

Specifies the expiry month for the card in MM format. 01, for example.

Allowable Values:

Format: MM

encrypted_card_data.expiration.year

string
Required

Specifies the expiry year for the card in yyyy format. 2024, for example.

Allowable Values:

Format: yyyy

encrypted_card_data.card_token

string
Required

The token that identifies the card and correlates it with the card issuer. This token is used to minimize the need to exchange card details during subsequent calls, and also for troubleshooting. Use a GUID or a pseudo-unique identifier for this token.

Allowable Values:

1-36 chars

encrypted_card_data.primary_account_number

string
Required

The primary account number of the card that is being tokenized. Typically expected to be 16 digits.

Allowable Values:

12-19 chars

encrypted_card_data.card_type

string
Optional

The type of card. This field is required for Samsung Wallet.

Allowable Values:

CREDIT, DEBIT

encrypted_card_data.cardholder_info

object
Optional

Contains the personal information of the cardholder.

Allowable Values:

A valid encrypted_card_data.cardholder_info object

encrypted_card_data.cardholder_info.first_name

string
Optional

The first or given name of the cardholder.

Allowable Values:

40 char max

encrypted_card_data.cardholder_info.last_name

string
Optional

The last or family name of the cardholder.

Allowable Values:

40 char max

encrypted_card_data.cardholder_info.cardholder_address

object
Optional

The cardholder address.

Allowable Values:

A valid encrypted_card_data.cardholder_info.cardholder_address object

encrypted_card_data.cardholder_info.cardholder_address.address_line_1

string
Required

The street address of the cardholder.

Allowable Values:

255 char max

encrypted_card_data.cardholder_info.cardholder_address.address_line_2

string
Optional

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

Allowable Values:

255 char max

encrypted_card_data.cardholder_info.cardholder_address.postal_code

string
Required

The postal code of the cardholder, such as a ZIP code. 94612, for example.

Allowable Values:

1-10 chars

encrypted_card_data.cardholder_info.cardholder_address.city

string
Optional

The city of the cardholder.

Allowable Values:

40 char max

encrypted_card_data.cardholder_info.cardholder_address.state

string
Optional

The two-character state or province code. CA, for example.

Allowable Values:

2 char max

encrypted_card_data.cardholder_info.cardholder_address.country_code

string
Optional

The two-character ISO 3166-1 alpha-2 country code. US, for example.

Allowable Values:

2 char max

encrypted_card_data.cardholder_info.email_address

string
Optional

The email address of the cardholder. test_recipient@example.com, for example.

Allowable Values:

255 char max

encrypted_card_data.cardholder_info.phone_number

string
Optional

The phone number of the cardholder.

Allowable Values:

255 char max

encrypted_card_data.metadata

array of objects
Optional

Additional metadata related to the card details object.

Allowable Values:

A valid encrypted_card_data.metadata array

encrypted_card_data.metadata[].name

string
Required

The metadata attribute name. CARD_ART_ID or MAX_TOKENS_PER_CARD, for example.

Allowable Values:

255 char max

encrypted_card_data.metadata[].value

string
Required

The metadata attribute value.

Allowable Values:

255 char max

card_token

string
Optional

The token that identifies the card and correlates it with the card issuer. This token is used to minimize the need to exchange card details during subsequent calls, and also for troubleshooting. Use a GUID or a pseudo-unique identifier for this token.

Allowable Values:

An existing card token

device_type

string
Optional

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

Allowable Values:

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

provisioning_app_version

string
Optional

Version of the application making the provisioning request (used for debugging and fraud).

Allowable Values:

50 char max

wallet_account_id

string
Required

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

Allowable Values:

1-50 chars

device_id

string
Required

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

Allowable Values:

1-24 chars

Response body
Fields Description

created_time

datetime
Returned

The date and time when the digital wallet provisioning request was created, in UTC. 2020-10-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

last_modified_time

datetime
Returned

The date and time when the digital wallet token provisioning request was last updated, in UTC. 2020-10-26T20:03:10Z, for example.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

card_token

string
Returned

The token that identifies the card and correlates it with the card issuer. This token is used to minimize the need to exchange card details during subsequent calls, and also for troubleshooting. Use a GUID or a pseudo-unique identifier for this token.

Allowable Values:

An existing card token

push_tokenize_request_data

object
Returned

Specifies the data provided in the push tokenization request.

Allowable Values:

An existing push_tokenize_request_data

push_tokenize_request_data.display_name

string
Returned

The display name of the cardholder.

Allowable Values:

255 char max

push_tokenize_request_data.last_digits

string
Returned

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

Allowable Values:

4 chars

push_tokenize_request_data.network

string
Returned

Specifies the card network of the physical or virtual card.

Allowable Values:

Visa, Mastercard

push_tokenize_request_data.token_service_provider

string
Returned

Specifies the network that provides the token service.

Allowable Values:

TOKEN_PROVIDER_VISA, TOKEN_PROVIDER_MASTERCARD

push_tokenize_request_data.opaque_payment_card

string
Returned

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

Allowable Values:

255 char max

push_tokenize_request_data.user_address

object
Returned

Specifies the cardholder address.

Allowable Values:

An existing push_tokenize_request_data.user_address object

push_tokenize_request_data.user_address.name

string
Returned

The name of the cardholder.

Allowable Values:

255 char max

push_tokenize_request_data.user_address.address1

string
Returned

The street address of the cardholder.

Allowable Values:

255 char max

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:

255 char max

push_tokenize_request_data.user_address.city

string
Returned

The city of the cardholder.

Allowable Values:

255 char max

push_tokenize_request_data.user_address.state

string
Returned

The two-character state or province code. CA, for example.

Allowable Values:

Two char max

push_tokenize_request_data.user_address.postal_code

string
Returned

The postal code of the cardholder, such as a ZIP code. 94612, for example.

Allowable Values:

255 char max

push_tokenize_request_data.user_address.country

string
Returned

The two-character ISO 3166-1 alpha-2 country code. US, for example.

Allowable Values:

Two char max

push_tokenize_request_data.user_address.phone

string
Returned

The phone number of the cardholder. +15105551212, for example.

Allowable Values:

255 char max

Create digital wallet provision 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

encrypted_card_data

object
Required

The card details encrypted using JSON Web Encryption (JWE).

Allowable Values:

A valid encrypted_card_data object

encrypted_card_data.expiration

object
Required

Specifies the expiry date for the card.

Allowable Values:

A valid encrypted_card_data.expiration object

encrypted_card_data.expiration.month

string
Required

Specifies the expiry month for the card in MM format. 01, for example.

Allowable Values:

Format: MM

encrypted_card_data.expiration.year

string
Required

Specifies the expiry year for the card in yyyy format. 2024, for example.

Allowable Values:

Format: yyyy

encrypted_card_data.card_token

string
Required

The token that identifies the card and correlates it with the card issuer. This token is used to minimize the need to exchange card details during subsequent calls, and also for troubleshooting. Use a GUID or a pseudo-unique identifier for this token.

Allowable Values:

1-36 chars

encrypted_card_data.primary_account_number

string
Required

The primary account number of the card that is being tokenized. Typically expected to be 16 digits.

Allowable Values:

12-19 chars

encrypted_card_data.card_type

string
Optional

The type of card. This field is required for Samsung Wallet.

Allowable Values:

CREDIT, DEBIT

encrypted_card_data.cardholder_info

object
Optional

Contains the personal information of the cardholder.

Allowable Values:

A valid encrypted_card_data.cardholder_info object

encrypted_card_data.cardholder_info.first_name

string
Optional

The first or given name of the cardholder.

Allowable Values:

40 char max

encrypted_card_data.cardholder_info.last_name

string
Optional

The last or family name of the cardholder.

Allowable Values:

40 char max

encrypted_card_data.cardholder_info.cardholder_address

object
Optional

The cardholder address.

Allowable Values:

A valid encrypted_card_data.cardholder_info.cardholder_address object

encrypted_card_data.cardholder_info.cardholder_address.address_line_1

string
Required

The street address of the cardholder.

Allowable Values:

255 char max

encrypted_card_data.cardholder_info.cardholder_address.address_line_2

string
Optional

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

Allowable Values:

255 char max

encrypted_card_data.cardholder_info.cardholder_address.postal_code

string
Required

The postal code of the cardholder, such as a ZIP code. 94612, for example.

Allowable Values:

1-10 chars

encrypted_card_data.cardholder_info.cardholder_address.city

string
Optional

The city of the cardholder.

Allowable Values:

40 char max

encrypted_card_data.cardholder_info.cardholder_address.state

string
Optional

The two-character state or province code. CA, for example.

Allowable Values:

2 char max

encrypted_card_data.cardholder_info.cardholder_address.country_code

string
Optional

The two-character ISO 3166-1 alpha-2 country code. US, for example.

Allowable Values:

2 char max

encrypted_card_data.cardholder_info.email_address

string
Optional

The email address of the cardholder. test_recipient@example.com, for example.

Allowable Values:

255 char max

encrypted_card_data.cardholder_info.phone_number

string
Optional

The phone number of the cardholder.

Allowable Values:

255 char max

encrypted_card_data.metadata

array of objects
Optional

Additional metadata related to the card details object.

Allowable Values:

A valid encrypted_card_data.metadata array

encrypted_card_data.metadata[].name

string
Required

The metadata attribute name. CARD_ART_ID or MAX_TOKENS_PER_CARD, for example.

Allowable Values:

255 char max

encrypted_card_data.metadata[].value

string
Required

The metadata attribute value.

Allowable Values:

255 char max

card_token

string
Optional

The token that identifies the card and correlates it with the card issuer. This token is used to minimize the need to exchange card details during subsequent calls, and also for troubleshooting. Use a GUID or a pseudo-unique identifier for this token.

Allowable Values:

An existing card token

device_type

string
Optional

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

Allowable Values:

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

provisioning_app_version

string
Optional

Version of the application making the provisioning request (used for debugging and fraud).

Allowable Values:

50 char max

wallet_user_id

string
Required

The user’s Samsung wallet account identifier, as provided by Google during the provisioning process.

Allowable Values:

1-50 chars

device_id

string
Required

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

Allowable Values:

1-24 chars

Response body
Fields Description

created_time

datetime
Returned

The date and time when the digital wallet provisioning request was created, in UTC. 2020-10-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

last_modified_time

datetime
Returned

The date and time when the digital wallet token provisioning request was last updated, in UTC. 2020-10-26T20:03:10Z, for example.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

card_token

string
Returned

The token that identifies the card and correlates it with the card issuer. This token is used to minimize the need to exchange card details during subsequent calls, and also for troubleshooting. Use a GUID or a pseudo-unique identifier for this token.

Allowable Values:

An existing card token

push_tokenize_request_data

object
Returned

Returns tokenization request data.

Allowable Values:

An existing push_tokenize_request_data object

push_tokenize_request_data.display_name

string
Returned

The display name of the cardholder.

Allowable Values:

255 char max

push_tokenize_request_data.last_digits

string
Returned

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

Allowable Values:

4 chars

push_tokenize_request_data.network

string
Returned

Specifies the card network of the physical or virtual card.

Allowable Values:

Visa, Mastercard

push_tokenize_request_data.token_service_provider

string
Returned

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

Allowable Values:

VI, MC

push_tokenize_request_data.extra_provision_payload

string
Returned

Encrypted card or cardholder details.

Allowable Values:

255 char max

push_tokenize_request_data.card_type

string
Returned

Specifies the type of payment card.

Allowable Values:

PAYMENT, DEBIT, CREDIT, LOYALTY, GIFT

Create digital wallet provision request for Apple Pay

Action: POST
Endpoint: /digitalwalletprovisionrequests/applepay

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

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

Request body
Fields Description

encrypted_card_data

object
Required

The card details encrypted using JSON Web Encryption (JWE).

Allowable Values:

A valid encrypted_card_data object

encrypted_card_data.expiration

object
Required

Specifies the expiry date for the card.

Allowable Values:

A valid encrypted_card_data.expiration object

encrypted_card_data.expiration.month

string
Required

Specifies the expiry month for the card in MM format. 01, for example.

Allowable Values:

Format: MM

encrypted_card_data.expiration.year

string
Required

Specifies the expiry year for the card in yyyy format. 2024, for example.

Allowable Values:

Format: yyyy

encrypted_card_data.card_token

string
Required

The token that identifies the card and correlates it with the card issuer. This token is used to minimize the need to exchange card details during subsequent calls, and also for troubleshooting. Use a GUID or a pseudo-unique identifier for this token.

Allowable Values:

1-36 chars

encrypted_card_data.primary_account_number

string
Required

The primary account number of the card that is being tokenized. Typically expected to be 16 digits.

Allowable Values:

12-19 chars

encrypted_card_data.card_type

string
Optional

The type of card. This field is required for Samsung Wallet.

Allowable Values:

CREDIT, DEBIT

encrypted_card_data.cardholder_info

object
Optional

Contains the personal information of the cardholder.

Allowable Values:

A valid encrypted_card_data.cardholder_info object

encrypted_card_data.cardholder_info.first_name

string
Optional

The first or given name of the cardholder.

Allowable Values:

40 char max

encrypted_card_data.cardholder_info.last_name

string
Optional

The last or family name of the cardholder.

Allowable Values:

40 char max

encrypted_card_data.cardholder_info.cardholder_address

object
Optional

The cardholder address.

Allowable Values:

A valid encrypted_card_data.cardholder_info.cardholder_address object

encrypted_card_data.cardholder_info.cardholder_address.address_line_1

string
Required

The street address of the cardholder.

Allowable Values:

255 char max

encrypted_card_data.cardholder_info.cardholder_address.address_line_2

string
Optional

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

Allowable Values:

255 char max

encrypted_card_data.cardholder_info.cardholder_address.postal_code

string
Required

The postal code of the cardholder, such as a ZIP code. 94612, for example.

Allowable Values:

1-10 chars

encrypted_card_data.cardholder_info.cardholder_address.city

string
Optional

The city of the cardholder.

Allowable Values:

40 char max

encrypted_card_data.cardholder_info.cardholder_address.state

string
Optional

The two-character state or province code. CA, for example.

Allowable Values:

2 char max

encrypted_card_data.cardholder_info.cardholder_address.country_code

string
Optional

The two-character ISO 3166-1 alpha-2 country code. US, for example.

Allowable Values:

2 char max

encrypted_card_data.cardholder_info.email_address

string
Optional

The email address of the cardholder. test_recipient@example.com, for example.

Allowable Values:

255 char max

encrypted_card_data.cardholder_info.phone_number

string
Optional

The phone number of the cardholder.

Allowable Values:

255 char max

encrypted_card_data.metadata

array of objects
Optional

Additional metadata related to the card details object.

Allowable Values:

A valid encrypted_card_data.metadata array

encrypted_card_data.metadata[].name

string
Required

The metadata attribute name. CARD_ART_ID or MAX_TOKENS_PER_CARD, for example.

Allowable Values:

255 char max

encrypted_card_data.metadata[].value

string
Required

The metadata attribute value.

Allowable Values:

255 char max

card_token

string
Optional

The token that identifies the card and correlates it with the card issuer. This token is used to minimize the need to exchange card details during subsequent calls, and also for troubleshooting. Use a GUID or a pseudo-unique identifier for this token.

Allowable Values:

An existing card token

device_type

string
Optional

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

Allowable Values:

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

provisioning_app_version

string
Optional

Version of the application making the provisioning request (used for debugging and fraud).

Allowable Values:

50 char max

certificates

array of strings
Required

Leaf and sub-CA certificates provided by Apple. Base64 encoded. The first element of the array should be the leaf certificate followed by the sub-CA.

Allowable Values:

A valid certificates array

nonce

string
Required

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

Allowable Values:

255 char max

nonce_signature

string
Required

Apple-provided signature to the nonce. Base64 encoded.

Allowable Values:

255 char max

Response body
Fields Description

created_time

datetime
Returned

The date and time when the digital wallet token provisioning request was created, in UTC. 2020-10-26T20:03:05Z, for example

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

last_modified_time

datetime
Returned

The date and time when the digital wallet token provisioning request was last updated, in UTC. 2020-10-26T20:03:10Z, for example.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

card_token

string
Returned

The token that identifies the card and correlates it with the card issuer. This token is used to minimize the need to exchange card details during subsequent calls, and also for troubleshooting. Use a GUID or a pseudo-unique identifier for this token.

Allowable Values:

An existing card token

encrypted_pass_data

string
Returned

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

Allowable Values:

255 char max

activation_data

string
Returned

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

Allowable Values:

255 char max

ephemeral_public_key

string
Returned

The ephemeral public key used for the provisioning attempt.

Allowable Values:

255 char max

Update expiry dates

Action: PUT
Endpoint: /cardactions/updateexpiration

Update the expiry dates of a digital wallet token.

Request body
Fields Description

primary_account_number

string
Required

The primary account number (PAN) of the card.

Allowable Values:

12-19 chars

old_card_token

string
Required

The existing payment card token that has digital wallet tokens assigned to it.

Allowable Values:

255 char max

old_pan_expiry

object
Required

Specifies the expiry date for the card.

Allowable Values:

A valid old_pan_expiry object

old_pan_expiry.month

string
Required

Specifies the expiry month for the card in MM format. 01, for example.

Allowable Values:

Format: MM

old_pan_expiry.year

string
Required

Specifies the expiry year for the card in yyyy format. 2024, for example.

Allowable Values:

Format: yyyy

new_card_token

string
Required

The new payment card token to which the digital wallet tokens are assigned.

Allowable Values:

255 char max

new_pan_expiry

object
Required

Specifies the expiry date for the card.

Allowable Values:

A valid new_pan_expiry object

new_pan_expiry.month

string
Required

Specifies the expiry month for the card in MM format. 01, for example.

Allowable Values:

Format: MM

new_pan_expiry.year

string
Required

Specifies the expiry year for the card in yyyy format. 2024, for example.

Allowable Values:

Format: yyyy

Response body
Fields Description

success

boolean
Conditionally returned

Indicates success if true, failure if false.

Allowable Values:

true, false

Transfer digital wallet tokens

Action: PUT
Endpoint: /cardactions/cardswap

Transfer digital wallet tokens to a new card with a different primary account number.

Request body
Fields Description

old_primary_account_number

string
Required

The primary account number for the existing payment card that has digital wallet tokens assigned to it.

Allowable Values:

12-19 chars

old_pan_expiry

object
Required

Specifies the expiry date for the card.

Allowable Values:

A valid old_pan_expiry object

old_pan_expiry.month

string
Required

Specifies the expiry month for the card in MM format. 01, for example.

Allowable Values:

Format: MM

old_pan_expiry.year

string
Required

Specifies the expiry year for the card in yyyy format. 2024, for example.

Allowable Values:

Format: yyyy

old_card_token

string
Required

The existing payment card token that has digital wallet tokens assigned to it.

Allowable Values:

255 char max

new_primary_account_number

string
Required

The primary account number for the new payment card to which the digital wallet tokens are assigned.

Allowable Values:

12-19 chars

new_pan_expiry

object
Required

Specifies the expiry date for the card.

Allowable Values:

A valid new_pan_expiry object

new_pan_expiry.month

string
Required

Specifies the expiry month for the card in MM format. 01, for example.

Allowable Values:

Format: MM

new_pan_expiry.year

string
Required

Specifies the expiry year for the card in yyyy format. 2024, for example.

Allowable Values:

Format: yyyy

new_card_token

string
Required

The new payment card token to which the digital wallet tokens are assigned.

Allowable Values:

255 char max

Response body
Fields Description

success

boolean
Conditionally returned

Indicates success if true, failure if false.

Allowable Values:

true, false

Create webhook

Action: POST
Endpoint: /webhooks/{token}/{event_type}/{event_token}

Resends an event notification to your webhook endpoint.

Although you send this request as a POST, all parameters are passed in the URL and the body is empty. The event notification is resent to your webhook endpoint and also returned in the response to this request.

URL path parameters
Fields Description

token

string
Required

The webhook token.

Allowable Values:

1-36 chars

event_type

string
Required

The event type.

Allowable Values:

digitalwallettokentransition

event_token

string
Required

The event token.

Allowable Values:

255 char max

Request body
Fields Description

token

string
Required

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

Allowable Values:

1-36 chars

digital_wallet_token

object
Required

The Marqeta unique identifier for the digital wallet token.

Allowable Values:

An existing digital_wallet_token object

digital_wallet_token.token

string
Required

The Marqeta unique identifier for the digital wallet token.

Allowable Values:

1-36 chars

card_swap

object
Optional

Specifies the old and new payment card tokens that were swapped.

Allowable Values:

A valid card_swap object

card_swap.previousCardToken

string
Required

The existing payment card token that has digital wallet tokens assigned to it.

Allowable Values:

1-36 chars

card_swap.newCardToken

string
Required

The new payment card token to which the digital wallet tokens are assigned.

Allowable Values:

1-36 chars

type

string
Required

The type of digital wallet token transition. state.activated, for example.

Allowable Values:

36 char max

channel

string
Required

The mechanism by which the transition was initiated.

Allowable Values:

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

state

string
Required

Specifies the state to which the digital wallet token transitions.

Allowable Values:

REQUESTED, ACTIVE, TERMINATED, SUSPENDED, REQUEST_DECLINED

fulfillment_status

string
Required

The digital wallet token’s provisioning status.

Allowable Values:

DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED

reason

string
Optional

A descriptive reason for the transition.

Allowable Values:

255 char max

reason_code

string
Required

The two-digit reason code for the transition.

Allowable Values:

Two digits

created_time

datetime
Required

The date and time when the digital wallet token transition was created, in UTC. 2020-10-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

Join our developer newsletter