Digital Wallets Management
The Marqeta platform facilitates the use of digital wallets for storing tokenized cards and making payments. The API provides endpoints that enable mobile applications to provision tokens into a digital wallet. It also provides endpoints for retrieving digital wallet tokens and for managing their lifecycle through state transitions.
For an overview of digital wallet tokens, see Digital Wallets and Tokenization.
Create digital wallet token provision request for Apple Pay
Copy section link
Action: POST
Endpoint: /digitalwalletprovisionrequests/applepay
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
|
Identifies the card to use for the provision request. Allowable Values: Existing card token. Send a |
device_type
string
|
The type of device into which the digital wallet token will be provisioned. Allowable Values:
|
provisioning_app_version
string
|
Version of the application making the provisioning request (used for debugging and fraud). Allowable Values: 50 char max |
certificates
array of strings
|
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
|
One-time-use nonce provided by Apple for security purposes. Allowable Values: Base64 encoded nonce from Apple. |
nonce_signature
string
|
Apple-provided signature to the nonce. Allowable Values: Base64 encoded nonce signature from Apple. |
Create digital wallet token provision request for Google Pay
Copy section link
Action: POST
Endpoint: /digitalwalletprovisionrequests/androidpay
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
|
Identifies the card to use for the provision request. Allowable Values: Existing card token. Send a |
device_type
string
|
The type of device into which the digital wallet token will be provisioned. Example device types include: Allowable Values:
|
provisioning_app_version
string
|
Version of the application making the provisioning request (used for debugging and fraud). Allowable Values: 50 char max |
wallet_account_id
string
|
The user’s Google wallet account ID. Allowable Values: 50 char max |
device_id
string
|
The user’s Android device ID; the device’s unique identifier. Allowable Values: 24 char max |
Create digital wallet token transition
Copy section link
Action: POST
Endpoint: /digitalwallettokentransitions
Use this endpoint to transition a digital wallet token from one state to another.
Body field details
Copy section link
| Fields | Description |
|---|---|
token
string
|
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 Allowable Values: 36 char max |
digital_wallet_token
object
|
Contains the token of the digital wallet token that will transition to a different state. Allowable Values: Existing |
state
string
|
Specifies the state to which the digital wallet token will transition. The original state is Allowable Values:
|
reason
string
|
The reason for the transition. Allowable Values: 255 char max |
reason_code
string
|
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 |
This address cannot accept mail or the addressee is unknown. |
04 |
Negative account balance. |
05 |
Account under review. |
06 |
Suspicious activity was identified. |
07 |
Activity outside the program parameters was identified. |
08 |
Confirmed fraud was identified. |
09 |
Matched with an Office of Foreign Assets Control list. |
10 |
Card was reported lost. |
11 |
Card information was cloned. |
12 |
Account or card information was compromised. |
13 |
Temporary status change while on hold/leave. |
14 |
Initiated by Marqeta. |
15 |
Initiated by issuer. |
16 |
Card expired. |
17 |
Failed KYC. |
18 |
Changed to |
19 |
Changed to |
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
|
Identifies the digital wallet token that will transition to a different state. Allowable Values: Existing digital wallet token. Send a |
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 |
The card_swap object (response)
Copy section link
| Fields | Description |
|---|---|
card_swap.previous_card_token
string
|
Present when Token of the card with which the digital wallet was previously associated. Allowable Values: Existing card token. |
card_swap.new_card_token
string
|
Present when 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. |
Retrieve digital wallet token transition
Copy section link
Action: GET
Endpoint: /digitalwallettokentransitions/{token}
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
|
Identifies the digital wallet token transition to retrieve. Allowable Values: Existing digital wallet token transition token. Send a |
List transitions for digital wallet token
Copy section link
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
Copy section link
| Fields | Description |
|---|---|
token
string
|
The token identifying the digital wallet token whose transitions you want to list. Allowable Values: Existing digital wallet token. Send a |
Retrieve digital wallet token
Copy section link
Action: GET
Endpoint: /digitalwallettokens/{token}
Use this endpoint to retrieve a specific digital wallet token.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
The token identifying the digital wallet token to retrieve. Allowable Values: Existing digital wallet token. Send a |
Response body
Copy section link
| Fields | Description |
|---|---|
token
string
|
The unique identifier of the digital wallet token. Allowable Values: 36 char max |
card_token
string
|
The unique identifier of the card. Allowable Values: 36 char max |
state
string
|
The state of the digital wallet token. For state descriptions, see Transitioning Token States. Allowable Values:
|
state_reason
string
|
The reason the digital wallet token transitioned to its current state. Allowable Values: 255 char max |
fulfillment_status
string
|
The digital wallet token’s provisioning status. For fulfillment status descriptions, see Create Digital Wallet Token Transition. Allowable Values:
|
issuer_eligibility_decision
string
|
The Marqeta platform’s decision as to whether the digital wallet token should be provisioned.
For all other values, check the value of the NOTE: The value Allowable Values: NOTE: This list of allowable values is subject to change. 0000, |
created_time
string
|
The date and time when the digital wallet token object was created. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ssZ |
last_modified_time
string
|
The date and time when the digital wallet token object was last modified. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ssZ |
token_service_provider
object
|
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 |
device
object
|
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 Pay and Apple Pay only. Allowable Values: Existing |
wallet_provider_profile
object
|
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: Existing |
address_verification
object
|
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 |
The token_service_provider object (response)
Copy section link
| Fields | Description |
|---|---|
token_reference_id
string
|
The unique identifier of the digital wallet token within the card network.
The Allowable Values: 50 char max |
pan_reference_id
string
|
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 Allowable Values: 50 char max |
token_requestor_id
string
|
The unique numerical identifier of the token requestor within the card network.
The Mastercard
Visa
NOTE: The list of allowable values for this field is maintained by the card networks and is subject to change. Allowable Values:
|
token_requestor_name
string
|
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:
|
token_type
string
|
The type of digital wallet token. Allowable Values:
|
token_pan
string
|
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. Allowable Values: 16 char max |
token_expiration
string
|
The expiration date of the digital wallet token. This value is provided after a token is activated. Allowable Values: MMYY |
token_score
string
|
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
|
The token service provider’s (typically the network’s) recommendation as to whether the digital wallet token should be provisioned. Allowable Values:
|
The device object (response)
Copy section link
| Fields | Description |
|---|---|
token
string
|
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 Pay, Samsung Pay, and Apple Pay but not for ecommerce token requestors such as PayPal. Allowable Values: 36 char max |
type
string
|
The type of device being provisioned as provided by the mobile application. Example device types include: Allowable Values: 255 char max |
language_code
string
|
The language the device is configured to use. Allowable Values: 50 char max For example: eng |
device_id
string
|
The identity number of the device. This value is returned if it is available for a given digital wallet token. Allowable Values: 50 char max |
phone_number
string
|
The device’s telephone number. This value is returned as 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
|
The name of the device. This value is returned as provided by the digital wallet. Allowable Values: 50 char max |
location
string
|
The geographic coordinates of the device. This value is returned as provided by the digital wallet. Allowable Values: DDD.DD/DDD.DD latitude/longitude NOTE: Both the longitude and latitude are prefixed with either a |
ip_address
string
|
The device’s IP address. This value is returned as 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
|
Contains information related to the cardholder, provided by the digital wallet provider. This value is returned as provided by the digital wallet. Allowable Values: Existing |
risk_assessment
object
|
Contains the digital wallet provider’s risk assessment for provisioning the digital wallet token. This value is returned as provided by the digital wallet. Allowable Values: Existing |
device_score
string
|
The score from the device. This value is returned as provided by the digital wallet. Allowable Values: 50 char max |
pan_source
string
|
The source from which the digital wallet provider obtained the card PAN. This value is returned as provided by the digital wallet. Allowable Values:
|
reason_code
string
|
The reason for the digital 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)
Google Pay/Samsung Pay (Visa only)
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
|
The digital 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
|
The score from the digital wallet provider. This value is returned as 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
|
The digital wallet provider’s decision as to whether the digital wallet token should be provisioned. Allowable Values:
|
The address_verification object (response)
Copy section link
| Fields | Description |
|---|---|
name
string
|
The name of the cardholder. This value is returned as provided by the digital wallet provider. Allowable Values: 50 char max |
street_address
string
|
The street address of the cardholder. This value is returned as provided by the digital wallet provider. Allowable Values: 50 char max |
postal_code
string
|
The postal code of the cardholder. This value is returned as provided by the digital wallet provider. Allowable Values: 50 char max |
List digital wallet tokens for card
Copy section link
Action: GET
Endpoint: /digitalwallettokens/card/{card_token}
Use this endpoint to return an array of all digital wallet tokens for a particular card.
This endpoint supports pagination.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
card_token
string
|
Identifies the card whose digital wallet tokens you want to list. Allowable Values: Existing card token. Send a |
Retrieve digital wallet token PAN
Copy section link
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}.)
Warning
Sending a request to this endpoint requires PCI DSS compliance. You must comply with PCI DSS data security requirements if you want to store, transmit, or process sensitive card data such as the cardholder’s primary account number (PAN), personal identification number (PIN), and card expiration date.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
The token identifying the digital wallet token to retrieve. Allowable Values: Existing digital wallet token. Send a |