Provisioning Digital Wallet Tokens
Marqeta supports several methods for provisioning a token to insert a payment card into a digital wallet.
-
manual-entry — The cardholder enters the card data directly into the digital wallet, typically either by typing in the data or by taking a photo of the card. This method might be preferred when your users already possess the physical cards they want to insert into their digital wallets.
-
card-on-file — The cardholder adds a card to an additional device. This method requires the digital wallet to already have the card information on file, possibly from a previous tokenization request. For example, the card is already stored in the digital wallet on a phone and the cardholder is adding the card to a watch.
-
in-app-provisioning — Your mobile application dynamically creates a new virtual card and then adds it to the digital wallet for instant availability of the funds.
For any card product, you can choose which of these methods you want to allow. For every token activation request processed through any of the methods, Marqeta sends an event notification to your configured webhook endpoint. You can use the information in the token activation request to determine the current status of a request and to change the status, when necessary.
Basic provisioning flow
Copy section link
In the basic provisioning flow, the cardholder initiates the provisioning request either by manually entering the data for a new card or by selecting a card that is already on file (i.e., the manual-entry and card-on-file methods).
A basic token provisioning flow proceeds as follows:
-
The cardholder initiates the request via manual-entry or card-on-file on the target device (e.g., Apple Pay wallet on an iPhone).
-
The digital wallet requests a token from the card network.
-
The card network, Marqeta (the issuer processor), and the digital wallet coordinate the approval of the token activation request.
-
Marqeta sends an event notification to your webhook endpoint. You can use this information to determine the current status and to take further actions, if necessary.
-
If the token activation request is approved, the card network issues a digital wallet token.
-
The digital wallet stores the digital wallet token on the target device, where the cardholder can now use it to make payments.
Instant issuance flow
Copy section link
In the instant issuance flow, your mobile application initiates the provisioning request to create a new Marqeta virtual card and then tokenize it (the in-app-provisioning method). This unique capability from Marqeta allows you to create a virtual card and make it instantly available for use at both brick-and-mortar merchants that support the digital wallet and e-commerce merchants.
Tip
To support the instant issuance flow from your mobile application, you must obtain approval from the digital wallet provider and integrate with their API, in addition to integrating with the Marqeta API. To facilitate this integration, Marqeta provides documentation.
An instant issuance flow proceeds as follows:
-
Your mobile application initiates the request by calling your backend.
-
Your backend sends a
POSTrequest to the/cardsendpoint to create a new virtual card. -
Marqeta creates a new virtual card and returns the card token in the response object.
-
Your backend sends a
POSTrequest to the Marqeta API endpoint for the specific type of digital wallet, with the card token in the request object. For example, if you add the card to an Apple Pay digital wallet, your application sends aPOSTrequest to the/digitalwalletprovisionrequests/applepayendpoint. -
The Marqeta API responds with encrypted card data for the new card. Your backend passes the encrypted card data to the digital wallet (e.g., Apple Pay) by integrating with the provider’s API.
-
The digital wallet requests a token from the card network.
-
The card network, Marqeta (the issuer processor), and the digital wallet coordinate the approval of the token activation request.
-
Marqeta sends an event notification to your webhook endpoint. You can use this information to determine the current status and to take further actions, if necessary.
-
If the token activation request is approved, the card network issues a digital wallet token.
-
The digital wallet stores the digital wallet token on the target device, where the cardholder can now use it to make payments.
Choosing the allowable provisioning methods
Copy section link
The card product controls the allowable methods for providing card data during token provisioning.
To see which methods are currently allowed, send a GET request to the /cardproducts endpoint.
Optionally, include the token path parameter to see the allowable methods for a specific card product.
The card product object indicates the allowable methods in the digital_wallet_tokenization.provisioning_controls element.
For example, the following card product allows the manual-entry and card-on-file methods, but not the in-app-provisioning method.
To ensure that cards function as expected and meet all card network and regulatory requirements, Marqeta configures and maintains the card products in your production environment. If you want to change the provisioning controls for a card product, contact your Marqeta representative.