DOCS
Support

Marqeta Home

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

20 minute read

August 26, 2020

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

Develop Now!

Sign in and use your sandbox to access the 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 your PCI compliance overhead.

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

Develop Now!

Sign in and use your sandbox to access the 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 your PCI compliance overhead.

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

{
  "created_time": "2019-11-06T22:43:20Z",
  "last_modified_time": "2019-11-06T22:43:20Z",
  "card_token": "rWgXMJKDrz1dPJxkorqK4",
  "push_tokenize_request_data": {
    "display_name": "Visa Card",
    "last_digits": "3264",
    "network": "Visa",
    "token_service_provider": "TOKEN_PROVIDER_VISA",
    "opaque_payment_card": "eyJraWQiOiIxVjMwT1ZCUTNUMjRZMVFBVFRRUza...",
    "user_address": {
      "name": "John Doe",
      "address1": "180 Grand Ave",
      "address2": "Suite 500",
      "city": "Oakland",
      "state": "CA",
      "postal_code": "94612",
      "country": "US",
      "phone": "5105551212"
    }
  }
}

Is this helpful?

Create digital wallet token transition
Copy section link

Action: POST
Endpoint: /digitalwallettokentransitions

Develop Now!

Sign in and use your sandbox to access the 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:

Existing digital_wallet_token object.

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.

22

PIN retry limit reached.

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.

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

Fields Description

card_swap.previous_card_token

string
Conditionally returned

Present when type is card.swap.

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

Allowable Values:

Existing card token.

card_swap.new_card_token

string
Conditionally returned

Present when type is card.swap.

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

Allowable Values:

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}

Develop Now!

Sign in and use your sandbox to access the 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}

Develop Now!

Sign in and use your sandbox to access the 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:

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

Develop Now!

Sign in and use your sandbox to access the 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:

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

The unique identifier of the digital wallet token.

Allowable Values:

36 char max

card_token

string
Conditionally returned

The unique identifier of the card.

Allowable Values:

36 char max

state

string
Conditionally returned

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

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

Allowable Values:

255 char max

fulfillment_status

string
Conditionally returned

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

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

  • 0000 – The token should be provisioned.

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

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

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

Allowable Values:

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

created_time

string
Conditionally returned

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

Allowable Values:

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

last_modified_time

string
Conditionally returned

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

Allowable Values:

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

token_service_provider

object
Conditionally returned

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

Allowable Values:

Existing token_service_provider object.

device

object
Conditionally returned

Contains information related to the device being provisioned.

Allowable Values:

Existing device object.

wallet_provider_profile

object
Conditionally returned

Contains information held and provided by the digital wallet provider.

Allowable Values:

Existing wallet_provider_profile object.

address_verification

object
Conditionally returned

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

Allowable Values:

Existing address_verification object.

The token_service_provider object (response)
Copy section link

Fields Description

token_reference_id

string
Conditionally returned

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

Allowable Values:

50 char max

pan_reference_id

string
Conditionally returned

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

Allowable Values:

50 char max

token_requestor_id

string
Conditionally returned

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

Visa

  • 40010030273 – APPLE_PAY

  • 40010075001 – ANDROID_PAY

  • 40010075338 – VISA_CHECKOUT

  • 40010075449 – FACEBOOK

  • 40010075839 – NETFLIX

Note
The list of allowable values for this field is maintained by the card networks and is subject to change.

Allowable Values:

  • Mastercard – 50110030273, 50120834693

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

token_requestor_name

string
Conditionally returned

The name of the token requestor within the card network.

Note
The list of allowable values for this field is maintained by the card networks and is subject to change.

Allowable Values:

  • Mastercard – APPLE_PAY, ANDROID_PAY

  • Visa – APPLE_PAY, ANDROID_PAY, VISA_CHECKOUT, FACEBOOK, NETFLIX

token_type

string
Conditionally returned

The type of digital wallet token.

Allowable Values:

MERCHANT_CARD_ON_FILE, DEVICE_SECURE_ELEMENT, DEVICE_CLOUD_BASED, ECOMMERCE_DIGITAL_WALLET

token_pan

string
Conditionally returned

The digital wallet token primary account number (PAN).

Allowable Values:

16 char max

token_expiration

string
Conditionally returned

The expiration date of the digital wallet token.

Allowable Values:

MMYY

token_score

string
Conditionally returned

The token score assigned by the digital wallet.

Allowable Values:

25 char max

token_eligibility_decision

string
Conditionally returned

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

The unique identifier of the device object.

Allowable Values:

36 char max

type

string
Conditionally returned

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

The language the device is configured to use.

Allowable Values:

50 char max

For example: eng

device_id

string
Conditionally returned

The identity number of the device.

Allowable Values:

20 char max

phone_number

string
Conditionally returned

The device’s telephone number.

Allowable Values:

50 char max

name

string
Conditionally returned

The name of the device.

Allowable Values:

50 char max

location

string
Conditionally returned

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

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

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

Allowable Values:

Existing account object.

risk_assessment

object
Conditionally returned

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

Allowable Values:

Existing risk_assessment object.

device_score

string
Conditionally returned

The score from the device.

Allowable Values:

50 char max

pan_source

string
Conditionally returned

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

Allowable Values:

KEY_ENTERED, ON_FILE, MOBILE_BANKING_APP

reason_code

string
Conditionally returned

The reason for the wallet provider’s provisioning decision.

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

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

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

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

  • 05 – Suspicious transactions linked to this account.

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

  • 07 – Suspended cards in the secure element.

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

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

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

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

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

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

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

  • 0G – Suspect fraud.

Allowable Values:

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

The wallet_provider_profile.account object (response)
Copy section link

Fields Description

id

string
Conditionally returned

The wallet provider’s identity number for the cardholder.

Allowable Values:

20 char max

score

string
Conditionally returned

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

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

The name of the cardholder.

Allowable Values:

50 char max

street_address

string
Conditionally returned

The street address of the cardholder.

Allowable Values:

50 char max

postal_code

string
Conditionally returned

The postal code of the cardholder.

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}

Develop Now!

Sign in and use your sandbox to access the 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

Develop Now!

Sign in and use your sandbox to access the 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 cardholder’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.