DOCS

New!

Support
Sign in to get developer support

Marqeta Home

/
Developer Guides
Core API Reference
DiVA API Reference
Core API Explorer

15 minute read

August 3, 2019

Digital Wallets Management

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

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

Create digital wallet token provision request for Apple Pay
Copy section link

Action: POST
Endpoint: /digitalwalletprovisionrequests/applepay

Get started now!

Sign up today and get access to Marqeta's API Explorer

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

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

Body field details
Copy section link

Fields Description

card_token

string, required

Identifies the card to use for the provision request.

Allowable Values:

Existing card token.

Send a GET request to /cards/user/{user_token} to retrieve card tokens for a specific user.

device_type

string, required

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

Allowable Values:

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

provisioning_app_version

string, required

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.

Allowable Values:

Array of Base64 encoded certificates from Apple.

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

nonce

string, required

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

Allowable Values:

Base64 encoded nonce from Apple.

nonce_signature

string, required

Apple-provided signature to the nonce.

Allowable Values:

Base64 encoded nonce signature from Apple.

Sample request body
Copy section link

{
  "card_token": "a00cac6c-a5c8-4e8d-b8aa-54f2238ef646",
  "device_type": "MOBILE_PHONE",
  "provisioning_app_version": "2.13.7",
  "certificates": [
    "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" ],
  "nonce": "vXWJaBidcTLaJJCF",
  "nonce_signature": "jD4Aphu+93N2wbBn"
}

Is this helpful?

Sample response body
Copy section link

{
  "created_time": "2017-03-22T21:22:19Z",
  "last_modified_time": "2017-03-22T21:22:19Z",
  "card_token": "a00cac6c-a5c8-4e8d-b8aa-54f2238ef646",
  "encrypted_pass_data": "w9NGKYa3OkPGeQ+FmAKGgaVDbmV/UE7jdgBcE1RpbUc4pw+V4bDnSzNq1ndvSjHuTTa2xl2HIACb2W0uNN+759TLnusGc9FeLpBo5IMpUBi/XBK488BPqDB7qgeXFpvz5iU8X+ZIMG1WwpS5KEkwoqbcnSmTIfxnj7j8QzLFeP7N9jPk8NeuQlAcgSf6EFQKll8OazvFLKjQol+/gwoAfPOfjXZo+gw2xEG6WNKBg2R0r8q2c14cILPm17liTSzqbW4gB1HUz3+pxJEGKI5+z8hf7wN/uY2nd4xQ937TNVmvSE/qZXmzK5vYtWkkXvwgCFwHGk4FEjaQocZro0CYV/Io4+vPao5wINKOt0lrsjo9cMU/nzPhwz2lEMg8vPC3fXF93vbfSLzN3qhBoejrwxPRqI0a6yPWSPFGO8zstPNwMKoE2GQF+swPUJxBlJL05ZSlneHpITahdp7gEvCZolZEjht4inQcwwYvxgtp3MdVC5fxl/i9mYbVi/epHa6If0tudb2vIeiJfeTZwnTUc6XJFV2g6nnmG5gCPE42NcNCYcaG1Cn9qDdwD7h8l2KC78v37I2jkxbNp7pi0MoP4PFZdw==",
  "activation_data": "TUJQQUMtMS1GSy03NDgwNTIuMS0tVERFQS00RjU4OTZGMUE3NEUyNTdFNDAxRDg2RjUwOENBNEUyMkJBRjE1RTExOTA3RDlGQkE3ODJCQTMwNjIyMkJFOUI4OUE2QUZGMjA4MDU5RTA3NzhGMzA5QjIxRkNDNTVGNERDQ0VCMjMwNUM3MzBCMzEy",
  "ephemeral_public_key": "BMop3NufgKwy/r0GX1muvomvwFfKAYMYY74bvq3TyktjrZ/+6uzQCiIz/dx5Mii7bUuVIJ84C+5I6by05Zhdd3A="
}

Is this helpful?

Create digital wallet token provision request for Google Pay
Copy section link

Action: POST
Endpoint: /digitalwalletprovisionrequests/androidpay

Get started now!

Sign up today and get access to Marqeta's API Explorer

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

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

Body field details
Copy section link

Fields Description

card_token

string, required

Identifies the card to use for the provision request.

Allowable Values:

Existing card token.

Send a GET request to /cards/user/{user_token} to retrieve card tokens for a specific user.

device_type

string, required

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

Allowable Values:

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

provisioning_app_version

string, required

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.

Allowable Values:

50 char max

device_id

string, required

The user’s Android device ID; the device’s unique identifier.

Allowable Values:

24 char max

Sample request body
Copy section link

{
  "card_token": "9d3dee7c-19df-4b71-bbb9-521bb04307bf",
  "device_type": "MOBILE_PHONE",
  "provisioning_app_version": "2.13.3",
  "wallet_account_id": "ae25OGhjZTk2dsr452dgsr51",
  "device_id": "W85OGhjZTk2dsr452dgsr51j"
}

Is this helpful?

Sample response body
Copy section link

{
  "card_token": "9d3dee7c-19df-4b71-bbb9-521bb04307bf",
  "push_tokenize_request_data": {
    "network": "Visa",
    "token_service_provider": "TOKEN_PROVIDER_VISA",
    "display_name": "Visa Card",
    "last_digits": "4563",
    "user_address": {
      "name": "John Doe",
      "address1": "180 Grand Ave",
      "address2": "FL 5",
      "city": "Oakland",
      "state": "CA",
      "postal_code": "94612",
      "country": "US",
      "phone": "925-831-9837"
    },
    "opaque_payment_card": "amFoc2J1YWhzamhza2pkZmhrZHM="
  },
  "created_time": "2016-09-12T18:39:20Z",
  "last_modified_time":"2016-09-12T18:39:20Z"
}

Is this helpful?

Create digital wallet token transition
Copy section link

Action: POST
Endpoint: /digitalwallettokentransitions

Get started now!

Sign up today and get access to Marqeta's API Explorer

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

Body field details
Copy section link

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:

36 char max

digital_wallet_token

object, required

Contains the token of the digital wallet token that will transition to a different state.

Allowable Values:

state

string, required

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

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

Allowable Values:

ACTIVE, SUSPENDED , TERMINATED

reason

string, optional

The reason for the transition.

Allowable Values:

255 char max

reason_code

string, required

A standard two-digit reason code.

Allowable Values:

See "The reason_code field" section.

The reason_code field
Copy section link

Value Description

00

Object activated for the first time.

01

Requested by you.

02

Inactivity over time.

03

Provided address either does not accept mail or the addressee is not known at the address.

04

Negative account balance.

05

Account under review.

06

Suspicious activity was identified.

07

Activity outside the program parameters was identified.

08

Confirmed fraud was identified.

09

Matched with an Office of Foreign Assets Control list.

10

Card was reported lost or stolen.

11

Card information was cloned.

12

Account or card information was compromised.

13

Temporary status change while on hold/leave.

14

Initiated by Marqeta.

15

Initiated by issuer.

16

Card expired.

17

Failed KYC.

18

Changed to ACTIVE because information was properly validated and confirmed.

19

Changed to ACTIVE because account activity was properly validated and confirmed.

20

Change occurred prior to the normalization of reason codes.

21

Initiated by a third-party, often a digital wallet provider.

The digital_wallet_token object
Copy section link

Fields Description

token

string, required

Identifies the digital wallet token that will transition to a different state.

Allowable Values:

Existing digital wallet token token.

Send a GET request to /digitalwallettokens/card/{card_token} to retrieve digital wallet token tokens for a card.

The type field (response)
Copy section link

Every digital wallet token transition contains a type field, which cannot be set directly using the /digitalwallettokentransitions endpoint. The type field is managed by the Marqeta Platform, based on the state of the digital wallet token before and after the transition (as specified by the state field). The following table describes the type field’s possible values:

Value Description

fulfillment.requested

Digital wallet token was requested.

state.request_declined

Digital wallet token request was declined.

state.activated

Digital wallet token was activated.

state.suspended

Digital wallet token was suspended.

state.reinstated

Digital wallet token was re-activated from a suspended state.

state.terminated

Digital wallet token was terminated.

card.swap

A card was activated (the card state transitioned from UNACTIVATED to ACTIVE), and all existing digital wallet tokens owned by the user and having a state of REQUESTED, ACTIVE, or SUSPENDED were moved to the new card. When the type is card.swap, the response contains a card_swap object.

The card_swap object (response)
Copy section link

Field Name Type Required? Description Allowable Values

card_swap.previous_card_token

string

No

Present when type is card.swap.

Token of the card with which the digital wallet was previously associated.

Existing card token

card_swap.new_card_token

string

No

Present when type is card.swap.

Token of the card with which the digital wallet is currently associated.

Existing card token

The fulfillment_status field (response)
Copy section link

The digital wallet token transition response contains a fulfillment_status field that provides information regarding the associated digital wallet token’s provisioning status. The following table describes this field’s possible values:

Value Description

DECISION_RED

Initial value when the token activation request decision is red.

DECISION_YELLOW

Initial value when the token activation request decision is yellow.

DECISION_GREEN

Initial value when the token activation request decision is green.

REJECTED

The token activation request was declined.

PROVISIONED

Digital wallet token was successfully activated and provisioned into the digital wallet.

Sample request body
Copy section link

{
 "token": "my_transition_04",
 "digital_wallet_token": {
    "token": "b98cb680-2fd4-4c14-aa56-8d05091209d5"
  },
  "state": "ACTIVE",
  "reason": "Passed additional identity verification",
  "reason_code": "18"
}

Is this helpful?

Sample response body
Copy section link

{
  "token": "my_transition_04",
  "digital_wallet_token": {
    "token": "b98cb680-2fd4-4c14-aa56-8d05091209d5"
  },
  "type": "state.activated",
  "channel": "API",
  "state": "ACTIVE",
  "fulfillment_status": "PROVISIONED",
  "reason": "Passed additional identity verification",
  "reason_code": "18",
  "created_time": "2017-02-23T18:57:45Z"
}

Is this helpful?

Retrieve digital wallet token transition
Copy section link

Action: GET
Endpoint: /digitalwallettokentransitions/{token}

Get started now!

Sign up today and get access to Marqeta's API Explorer

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

This endpoint supports field filtering.

URL path parameters
Copy section link

Fields Description

token

string, required

Identifies the digital wallet token transition to retrieve.

Allowable Values:

Existing digital wallet token transition token.

Send a GET request to /digitalwallettokentransitions/digitalwallettoken/{token} to retrieve digital wallet token transition tokens for a particular digital wallet token.

Sample response body
Copy section link

{
  "token": "my_transition_04",
  "digital_wallet_token": {
    "token": "b98cb680-2fd4-4c14-aa56-8d05091209d5"
  },
  "type": "state.activated",
  "channel": "API",
  "state": "ACTIVE",
  "fulfillment_status": "PROVISIONED",
  "reason": "Passed additional identity verification",
  "reason_code": "18",
  "created_time": "2017-02-23T18:57:45Z"
}

Is this helpful?

List transitions for digital wallet token
Copy section link

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

Get started now!

Sign up today and get access to Marqeta's API Explorer

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
Copy section link

Fields Description

token

string, required

The token identifying the digital wallet token whose transitions you want to list.

Allowable Values:

Existing digital wallet token token.

Send a GET request to /digitalwallettokens/card/{card_token} to retrieve digital wallet token tokens for a specific card.

Sample response body
Copy section link

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "token": "my_transition_04",
      "digital_wallet_token": {
        "token": "b98cb680-2fd4-4c14-aa56-8d05091209d5"
    },
      "type": "state.activated",
      "channel": "API",
      "state": "ACTIVE",
      "fulfillment_status": "PROVISIONED",
      "reason": "Passed additional identity verification",
      "reason_code": "18",
      "created_time": "2017-02-23T18:57:45Z"
    },
    {
      "token": "659654f0-d5e4-4875-8e3e-2ecf1babd03b",
      "digital_wallet_token": {
        "token": "b98cb680-2fd4-4c14-aa56-8d05091209d5"
      },
      "type": "fulfillment.requested",
      "channel": "TOKEN_SERVICE_PROVIDER",
      "state": "REQUESTED",
      "fulfillment_status": "DECISION_YELLOW",
      "reason": "Additional identity verification required",
      "reason_code": "21",
      "created_time": "2017-02-23T18:44:21Z"
    }
  ]
}

Is this helpful?

Retrieve digital wallet token
Copy section link

Action: GET
Endpoint: /digitalwallettokens/{token}

Get started now!

Sign up today and get access to Marqeta's API Explorer

Use this endpoint to retrieve a specific digital wallet token.

URL path parameters
Copy section link

Fields Description

token

string, required

The token identifying the digital wallet token to retrieve.

Allowable Values:

Existing digital wallet token token.

Send a GET request to /digitalwallettokens/card/{card_token} to retrieve digital wallet token tokens for a particular card.

Body field details (response)
Copy section link

Fields Description

token

string, optional

The unique identifier of the digital wallet token.

Allowable Values:

36 char max

card_token

string, optional

The unique identifier of the card.

Allowable Values:

36 char max

state

string, optional

The state of the digital wallet token.

For state descriptions, see Transitioning Token States.

Allowable Values:

REQUESTED, REQUEST_DECLINED, ACTIVE, SUSPENDED, TERMINATED

state_reason

string, optional

The reason the digital wallet token transitioned to its current state.

Allowable Values:

255 char max

fulfillment_status

string, optional

The digital wallet token’s provisioning status.

For fulfillment status descriptions, see Create Digital Wallet Token Transition.

Allowable Values:

DECISION_RED, DECISION_YELLOW, DECISION_GREEN, REJECTED, PROVISIONED

issuer_eligibility_decision

string, optional

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

  • 0000 – The token should be provisioned.

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

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

Note
The value invalid.cid indicates an invalid CVV2 number.

Allowable Values:

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

created_time

string, optional

The date and time the digital wallet token object was created.

Allowable Values:

yyyy-MM-dd’T’HH:mm:ssZ

last_modified_time

string, optional

The date and time the digital wallet token object was last modified.

Allowable Values:

yyyy-MM-dd’T’HH:mm:ssZ

token_service_provider

object, optional

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

Allowable Values:

device

object, optional

Contains information related to the device being provisioned.

Allowable Values:

wallet_provider_profile

object, optional

Contains information held and provided by the digital wallet provider.

Allowable Values:

address_verification

object, optional

Contains information held by the card network and used for address verification of the card holder.

Allowable Values:

The token_service_provider object (response)
Copy section link

Fields Description

token_reference_id

string, optional

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

Allowable Values:

50 char max

pan_reference_id

string, optional

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

Allowable Values:

50 char max

token_requestor_id

string, optional

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

Mastercard

  • 50110030273 – APPLE_PAY

  • 50120834693 – ANDROID_PAY

  • 50139059239 – SAMSUNG_PAY

Visa

  • 40010030273 – APPLE_PAY

  • 40010075001 – ANDROID_PAY

  • 40010043095 – SAMSUNG_PAY

  • 40010075196 – MICROSOFT_PAY

  • 40010075338 – VISA_CHECKOUT

  • 40010075449 – FACEBOOK

  • 40010075839 – NETFLIX

  • 40010077056 – FITBIT_PAY

  • 40010069887 – GARMIN_PAY

Allowable Values:

Mastercard

50110030273, 50120834693, 50139059239

Visa

40010030273, 40010075001, 40010043095, 40010075196, 40010075338, 40010075449, 40010075839, 40010077056, 40010069887

token_requestor_name

string, optional

The name of the token requestor within the card network.

Allowable Values:

Mastercard

APPLE_PAY, ANDROID_PAY, SAMSUNG_PAY

Visa

APPLE_PAY, ANDROID_PAY, SAMSUNG_PAY, MICROSOFT_PAY, VISA_CHECKOUT, FACEBOOK, NETFLIX, FITBIT_PAY, GARMIN_PAY

token_type

string, optional

The type of digital wallet token.

Allowable Values:

MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET

token_pan

string, optional

The digital wallet token PAN (primary account number).

Allowable Values:

16 char max

token_expiration

string, optional

The expiration date of the digital wallet token.

Allowable Values:

yyyy-MM-dd HH:mm:ss

token_score

string, optional

The token score assigned by the digital wallet.

Allowable Values:

25 char max

token_eligibility_decision

string, optional

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

Allowable Values:

DECISION_RED, DECISION_YELLOW, DECISION_GREEN

The device object (response)
Copy section link

Fields Description

token

string, optional

The unique identifier of the device object.

Allowable Values:

36 char max

type

string, optional

The type of device being provisioned.

Allowable Values:

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

language_code

string, optional

The language the device is configured to use.

Allowable Values:

50 char max

For example: eng

device_id

string, optional

The identity number of the device.

Allowable Values:

20 char max

phone_number

string, optional

The device’s telephone number.

Allowable Values:

50 char max

name

string, optional

The name of the device.

Allowable Values:

50 char max

location

string, optional

The geographic coordinates of the device.

Allowable Values:

DDD.DD/DDD.DD

latitude/longitude

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

ip_address

string, optional

The device’s IP address.

Allowable Values:

50 char max (IP address format)

The wallet_provider_profile object (response)
Copy section link

Fields Description

account

object, optional

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

Allowable Values:

risk_assessment

object, optional

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

Allowable Values:

device_score

string, optional

The score from the device.

Allowable Values:

50 char max

pan_source

string, optional

The source from which the digital wallet provider obtained the card PAN.

Allowable Values:

KEY_ENTERED, ON_FILE, MOBILE_BANKING_APP

reason_code

string, optional

The reason for the wallet provider’s provisioning decision.

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

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

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

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

  • 05 – Suspicious transactions linked to this account.

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

  • 07 – Suspended cards in the secure element.

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

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

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

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

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

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

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

  • 0G – Suspect fraud.

Allowable Values:

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

The wallet_provider_profile.account object (response)
Copy section link

Fields Description

id

string, optional

The wallet provider’s identity number for the card holder.

Allowable Values:

20 char max

score

string, optional

The score from the digital wallet provider.

Allowable Values:

50 char max

The wallet_provider_profile.risk_assessment object (response)
Copy section link

Fields Description

score

string, optional

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

Allowable Values:

DECISION_RED, DECISION_YELLOW, DECISION_GREEN

The address_verification object (response)
Copy section link

Fields Description

name

string, optional

The name of the card holder.

Allowable Values:

50 char max

street_address

string, optional

The street address of the card holder.

Allowable Values:

50 char max

postal_code

string, optional

The postal code of the card holder.

Allowable Values:

50 char max

Sample response body
Copy section link

{
  "token": "ccc47fa8-7730-4188-91f6-7214ba38b8f3",
  "card_token": "platinum_grizzcard",
  "state": "ACTIVE",
  "state_reason": "",
  "fulfillment_status": "PROVISIONED",
  "issuer_eligibility_decision": "cardaccount.verified",
  "created_time": "2016-10-03T18:55:45Z",
  "last_modified_time": "2017-01-26T22:36:10Z",
  "token_service_provider": {
    "token_reference_id": "DNITHE381627769134881600",
    "pan_reference_id": "V-3806261653021975990073",
    "token_requestor_id": "40010020373",
    "token_requestor_name": "",
    "token_type": "DEVICE_SECURE_ELEMENT",
    "token_score": "02",
    "token_eligibility_decision": "DECISION_GREEN"
  },
  "device": {
    "type": "MOBILE_PHONE",
    "language_code": "eng",
    "device_id": "045632E32F25800141612033439308035B57A7954FD29575",
    "phone_number": "67595237333",
    "name": "April Phone",
    "location": "+37.81/-122.26",
    "ip_address": "013.002.136.004"
  },
  "wallet_provider_profile": {
    "account": {
      "score": "05"
    },
    "risk_assessment": {
      "score": "DECISION_YELLOW",
      "version": "0001.00"
    },
    "device_score": "03",
    "pan_source": "KEY_ENTERED"
  },
  "address_verification": {
    "name": "",
    "street_address": "223 Elm Street",
    "postal_code": "94703"
  }
}

Is this helpful?

List digital wallet tokens for card
Copy section link

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

Get started now!

Sign up today and get access to Marqeta's API Explorer

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

This endpoint supports pagination.

URL path parameters
Copy section link

Fields Description

card_token

string, required

Identifies the card whose digital wallet tokens you want to list.

Allowable Values:

Existing card token.

Send a GET request to /cards/user/{user_token} to retrieve card tokens for a specific user.

Sample response body
Copy section link

{
  "count": 1,
  "start_index": 0,
  "end_index": 0,
  "is_more": true,
  "data": [
    {
      "token": "ccc47fa8-7730-4188-91f6-7214ba38b8f3",
      "card_token": "platinum_grizzcard",
      "state": "ACTIVE",
      "state_reason": "",
      "fulfillment_status": "PROVISIONED",
      "issuer_eligibility_decision": "cardaccount.verified",
      "created_time": "2016-10-03T18:55:45Z",
      "last_modified_time": "2017-01-26T22:36:10Z",
      "token_service_provider": {
        "token_reference_id": "DNITHE381627769134881600",
        "pan_reference_id": "V-3806261653021975990073",
        "token_requestor_id": "40010020373",
        "token_requestor_name": "",
        "token_type": "DEVICE_SECURE_ELEMENT",
        "token_score": "02",
        "token_eligibility_decision": "DECISION_GREEN"
      },
      "device": {
        "type": "MOBILE_PHONE",
        "language_code": "eng",
        "device_id": "045632E32F25800141612033439308035B57A7954FD29575",
        "phone_number": "67595237333",
        "name": "April Phone",
        "location": "+37.81/-122.26",
        "ip_address": "013.002.136.004"
      },
      "wallet_provider_profile": {
        "account": {
          "score": "05"
        },
        "risk_assessment": {
          "score": "DECISION_YELLOW",
          "version": "0001.00"
        },
        "device_score": "03",
        "pan_source": "KEY_ENTERED"
      },
      "address_verification": {
        "name": "",
        "street_address": "223 Elm Street",
        "postal_code": "94703"
      }
    }
  ]
}

Is this helpful?

Retrieve digital wallet token PAN
Copy section link

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

Get started now!

Sign up today and get access to Marqeta's API Explorer

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

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

URL path parameters
Copy section link

Fields Description

token

string, required

The token identifying the digital wallet token to retrieve.

Allowable Values:

Existing digital wallet token token.

Send a GET request to /digitalwallettokens/card/{card_token} to retrieve digital wallet token tokens for a particular card.

Sample response body
Copy section link

{
  "token": "ccc47fa8-7730-4188-91f6-7214ba38b8f3",
  "card_token": "platinum_grizzcard",
  "state": "ACTIVE",
  "state_reason": "",
  "fulfillment_status": "PROVISIONED",
  "issuer_eligibility_decision": "cardaccount.verified",
  "created_time": "2016-10-03T18:55:45Z",
  "last_modified_time": "2017-01-26T22:36:10Z",
  "token_service_provider": {
    "token_reference_id": "DNITHE381627769134881600",
    "pan_reference_id": "V-3806261653021975990073",
    "token_requestor_id": "40010020373",
    "token_requestor_name": "",
    "token_type": "DEVICE_SECURE_ELEMENT",
    "token_pan": "3829071483456792",
    "token_score": "02",
    "token_eligibility_decision": "DECISION_GREEN"
  },
  "device": {
    "type": "MOBILE_PHONE",
    "language_code": "eng",
    "device_id": "045632E32F25800141612033439308035B57A7954FD29575",
    "phone_number": "67595237333",
    "name": "April Phone",
    "location": "+37.81/-122.26",
    "ip_address": "013.002.136.004"
  },
  "wallet_provider_profile": {
    "account": {
      "score": "05"
    },
    "risk_assessment": {
      "score": "DECISION_YELLOW",
      "version": "0001.00"
    },
    "device_score": "03",
    "pan_source": "KEY_ENTERED"
  },
  "address_verification": {
    "name": "",
    "street_address": "223 Elm Street",
    "postal_code": "94703"
  }
}

Is this helpful?

Related Materials

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.