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:
Endpoint:
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 GET request to /cards/user/{user_token} to retrieve card tokens for a specific user.
|
device_type
string
|
The type of device into which the digital wallet token will be provisioned. Allowable Values: MOBILE_PHONE , WATCH , TABLET
|
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:
Endpoint:
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 GET request to /cards/user/{user_token} to retrieve card tokens for a specific user.
|
device_type
string
|
The type of device into which the digital wallet token will be provisioned. Allowable Values: MOBILE_PHONE , WATCH , TABLET
|
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:
Endpoint:
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 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
|
Contains the token of the digital wallet token that will transition to a different state. Allowable Values: Existing digital_wallet_token object.
|
state
string
|
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
|
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 |
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
|
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
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
|
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
|
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
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:
Endpoint:
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 GET request to /digitalwallettokentransitions/digitalwallettoken/{token} to retrieve digital wallet token transition tokens for a particular digital wallet token.
|
List transitions for digital wallet token
Copy section link
Action:
Endpoint:
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 token. Send a GET request to /digitalwallettokens/card/{card_token} to retrieve digital wallet token tokens for a specific card.
|
Retrieve digital wallet token
Copy section link
Action:
Endpoint:
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 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
|
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: REQUESTED , REQUEST_DECLINED , ACTIVE , SUSPENDED , TERMINATED
|
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: DECISION_RED , DECISION_YELLOW , DECISION_GREEN , REJECTED , PROVISIONED
|
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 fulfillment_status field to definitively ascertain the provisioning outcome.
NoteThe valuedecision 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: NoteThis 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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
Visa
NoteThe 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.
NoteThe list of allowable values for this field is maintained by the card networks and is subject to change at any time.Allowable Values:
|
token_type
string
|
The type of digital wallet token. Allowable Values: MERCHANT_CARD_ON_FILE , DEVICE_SECURE_ELEMENT , DEVICE_CLOUD_BASED , ECOMMERCE_DIGITAL_WALLET
|
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 re-use. 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: DECISION_RED , DECISION_YELLOW , DECISION_GREEN
|
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 GooglePay, SamsungPay and ApplePay but not for ecommerce token requestors such as Paypal. Allowable Values: 36 char max |
type
string
|
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
|
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: 20 char max |
phone_number
string
|
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
|
The name of the device. This value is returned as it is provided by the digital wallet. Allowable Values: 50 char max |
location
string
|
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
NoteBoth the longitude and latitude are prefixed with either a+ or - symbol, for example: +42.29/-71.07
|
ip_address
string
|
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
|
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
|
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
|
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
|
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
|
The reason for the wallet provider’s provisioning decision.
NoteThis 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 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 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
|
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
|
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
|
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
|
The postal code of the cardholder. This value is returned as it is provided by the digital wallet provider. Allowable Values: 50 char max |
List digital wallet tokens for card
Copy section link
Action:
Endpoint:
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 GET request to /cards/user/{user_token} to retrieve card tokens for a specific user.
|
Retrieve digital wallet token PAN
Copy section link
Action:
Endpoint:
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
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
|
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.
|