DOCS

Marqeta.com
Support
/
Guides
Core API Reference
DiVA API Reference
Core API Explorer
25 minute read
December 22, 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

Sign in to use API widgets
POST

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

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
Copied

Is this helpful?

Yes
No
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

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

Action:

POST

Endpoint:
/digitalwalletprovisionrequests/androidpay

Sign in to use API widgets
POST

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

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
Copied

Is this helpful?

Yes
No
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Create digital wallet token transition
Copy section link

Action:

POST

Endpoint:
/digitalwallettokentransitions

Sign in to use API widgets
POST

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.

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.

23

Card was reported stolen.
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_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
Copied

Is this helpful?

Yes
No
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Retrieve digital wallet token transition
Copy section link

Action:

GET

Endpoint:
/digitalwallettokentransitions/{token}

Sign in to use API widgets
GET

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
Copied

Is this helpful?

Yes
No

List transitions for digital wallet token
Copy section link

Action:

GET

Endpoint:
/digitalwallettokentransitions/digitalwallettoken/{token}

Sign in to use API widgets
GET

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
Copied

Is this helpful?

Yes
No

Retrieve digital wallet token
Copy section link

Action:

GET

Endpoint:
/digitalwallettokens/{token}

Sign in to use API widgets
GET

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
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
decision due to TSP risk manager
indicates that the decision was determined according to rules configured on the token service provider’s risk rules platform. The value
invalid.cid
indicates an invalid CVV2 number. The value
low.device.score
indicates the specified device was determined to have high risk.

Allowable Values:

Note
This list of allowable values is subject to change.

0000,

avs.decline
,
card.expiration.mismatch
,
card.expired
,
card.not.active
,
card.lost
,
card.not.configured
,
card.suspended
,
card.suspicious
,
cvv.attempt.limit.exceeded
,
decision due to TSP risk manager
,
invalid.cid
,
low.device.score
,
token.activation-request.decline
,
token.activation.verification.required
,
cardholder.not.active

created_time

string
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
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). This object is returned when relevant information is provided by the token service provider.

Allowable Values:

Existing

token_service_provider
object.

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 GooglePay and ApplePay only.

Allowable Values:

Existing

device
object.

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 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. This object is provided when address information was included as part of the tokenization request.

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. The

token_reference_id
is unique at the card network level.

Allowable Values:

50 char max

pan_reference_id

string
Conditionally 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 an Apple Pay wallet and a Google Pay wallet for the same digital wallet token.

Allowable Values:

50 char max

token_requestor_id

string
Conditionally returned

The unique numerical identifier of the token requestor within the card network. The

token_requestor_id
is unique at the card network level. 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

  • 40010075338 –

    VISA_CHECKOUT

  • 40010075449 –

    FACEBOOK

  • 40010075839 –

    NETFLIX

  • 40010043095 -

    SAMSUNG_PAY

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, 50139059239

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

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 at any time.

Allowable Values:

  • Mastercard –

    APPLE_PAY
    ,
    ANDROID_PAY
    ,
    SAMSUNG_PAY

  • Visa –

    APPLE_PAY
    ,
    ANDROID_PAY
    ,
    FACEBOOK
    ,
    NETFLIX
    ,
    PAYPAL
    ,
    SAMSUNG_PAY
    ,
    UNKNOWN
    ,
    VISA_CHECKOUT

token_type

string
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), 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 re-use. This value is provided after a token is activated.

Allowable Values:

16 char max

token_expiration

string
Conditionally returned

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

Allowable Values:

MMYY

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_eligibility_decision

string
Conditionally returned

The token service provider’s (typically the network’s) recommendation 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. 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 GooglePay, SamsungPay and ApplePay but not for ecommerce token requestors such as Paypal.

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. This value is returned if it is available for a given digital wallet token.

Allowable Values:

20 char max

phone_number

string
Conditionally returned

The device’s telephone number. This value is returned as it is provided by the digital wallet. This value may be the full phone number, or just the last four digits.

Allowable Values:

50 char max

name

string
Conditionally returned

The name of the device. This value is returned as it is provided by the digital wallet.

Allowable Values:

50 char max

location

string
Conditionally returned

The geographic coordinates of the device. This value is returned as it is provided by the digital wallet.

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.' This value is returned as it is provided by the digital wallet.

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, provided by the digital wallet provider. This value is returned as it is provided by the digital wallet.

Allowable Values:

Existing

account
object.

risk_assessment

object
Conditionally returned

Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token. This value is returned as it is provided by the digital wallet.

Allowable Values:

Existing

risk_assessment
object.

device_score

string
Conditionally returned

The score from the device. This value is returned as it is provided by the digital wallet.

Allowable Values:

50 char max

pan_source

string
Conditionally returned

The source from which the digital wallet provider obtained the card PAN. This value is returned as it is provided by the digital wallet.

Allowable Values:

KEY_ENTERED
,
ON_FILE
,
MOBILE_BANKING_APP

reason_code

string
Conditionally returned

The reason for the wallet provider’s provisioning decision.

Note
This list of reason codes is subject to change.

Apple Pay (Visa/Mastercard), Google Pay/Samsung Pay (Mastercard only)

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

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

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

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

  • 05 – Suspicious transactions linked to this account.

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

  • 07 – Suspended cards in the secure element.

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

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

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

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

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

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

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

  • 0G – Suspected fraud.

  • 0H – The phone number score is less than 3.

Google Pay/Samsung Pay (Visa only)

  • A0 – Cardholder PAN associated with account within threshold days.

  • A1 – Wallet account holder name on file does not match cardholder entered name.

  • A2 – User’s account on device less than threshold days.

  • A3 – User account was created within threshold days.

  • A4 – Wallet account created within threshold days.

  • A5 – Changes made to account data within threshold days.

  • A6 – The number of provisioning attempts across all cards on this device in the last 24 hours exceeds the threshold.

  • A7 – The wallet account into which the card is being provisioned contains distinct names greater than threshold.

  • A8 – Device provisioning location outside of cardholder’s wallet account home country.

  • A9 – Suspended cards in the wallet account is greater than threshold.

  • AA – This account has not had activity within threshold period.

  • AB – Number of days since device was last reported lost is less than threshold days.

  • AC – Number of transactions in last 12 months less than threshold number.

  • AD – Number of active tokens greater than threshold.

  • AE – Number of devices with Same UserID with token is greater than threshold.

  • AF – Number of active tokens on all devices is greater than threshold.

  • AG – Issuer deferred ID&V decision.

  • AH – Issuer encrypted payment instrument data expired.

  • AI – User/device receiving encrypted payment instrument data is different than the one that is provisioning the token.

  • AL – Encrypted payment instrument data is pushed to a different device than the one that issuer application authenticated.

  • AM – Encrypted payment instrument data is pushed to a different user than the cardholder.

  • AN – Encrypted Payment Instrument Data is being pushed by the Issuer to the same device that the Issuer application authenticated, but without any upfront authentication.

  • AO – Encrypted Payment Instrument Data is being pushed by the Issuer to the same device that the Issuer application authenticated, but with successful upfront authentication.

Allowable Values:

01, 02, 03, 04, 05, 06, 07, 08, 09, 0A, 0B, 0C, 0D, 0E, 0G, 0H, A1, A2, A3, A4, A5, A6, A7, A8, A9, AA, AB, AC, AD, AE, AF, AG, AH, AI, AL, AM, AN, AO
The wallet_provider_profile.account object (response)
Copy section link
Fields Description

id

string
Conditionally returned

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

Allowable Values:

20 char max

score

string
Conditionally returned

The score from the digital wallet provider. This value is returned as it is provided by 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. This value is returned as it is provided by the digital wallet provider.

Allowable Values:

50 char max

street_address

string
Conditionally returned

The street address of the cardholder. This value is returned as it is provided by the digital wallet provider.

Allowable Values:

50 char max

postal_code

string
Conditionally returned

The postal code of the cardholder. This value is returned as it is provided by the digital wallet provider.

Allowable Values:

50 char max
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

List digital wallet tokens for card
Copy section link

Action:

GET

Endpoint:
/digitalwallettokens/card/{card_token}

Sign in to use API widgets
GET

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
Copied

Is this helpful?

Yes
No

Retrieve digital wallet token PAN
Copy section link

Action:

GET

Endpoint:
/digitalwallettokens/{token}/showtokenpan

Sign in to use API widgets
GET

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
Copied

Is this helpful?

Yes
No
Related materials

Feedback on this page?

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

© 2021 Marqeta, Inc.

• Terms
 • API Terms
 • Privacy
 • Cookies