By Ahmed Siddiqui, VP of Product Management at Marqeta
The Smart City of the future offers ample challenges. Take mass transit systems, for example. They can get us most of the way from our homes to our destinations, but typically not all the way. Ride sharing companies step in to solve this last mile problem. The transit system and the ride sharing companies operate independently but, for consumers, they are definitely dependent. In a future smart city, we should be able to create the connection for consumers between the two independent systems. Wouldn’t it be great if my transit card rewarded me with credits at a ride sharing company or whatever other means of last mile transportation I use?
Mass transit systems typically operate on proprietary, “closed-loop” systems like the Clipper Card in the San Francisco Bay Area. These transit cards hold a monetary value that can only be spent for transit, and for nothing else, forcing you to have a piece of plastic in your wallet that only serves one purpose. These proprietary systems are contactless in most cases. Why do you need a physical card at all when most modern smartphones have NFC capability? How can we make the transit card truly digital and also be considered a “top-of-wallet” product?
How to build a Smarter City Digital Transit Reward card using Visa and Marqeta APIs
Visa’s Offers API allows us to create offers based off of some spend. For example, you take 5 BART rides, and then you get a $10 transit reward. The Marqeta platform enables you to create virtual cards that you can add to Apple Pay. Marqeta also enables you to control the spend behavior so these offers or rewards can only be spent at specific locations or for specific purposes (like transit).
Getting started with the Marqeta API
In the following example, code snippets illustrate how to interact with the Marqeta API. When you are ready to start exploring the API, be sure to modify these snippets to use your own authentication credentials, and be sure to replace all the example tokens with your own, unique values. You can also leave out the token field, and the system will automatically generate a unique token for each new object.
Note: Do not use the same tokens as in these examples. If an object with the same token already exists, the system will handle the request as a duplicate, and your request will not take effect.
- Sign up for an account on Marqeta.com to get access to the shared API sandbox.
Link: https://www.marqeta.com/users/sign_up
- Open the API Explorer and take note of your API keys. Link: https://www.marqeta.com/api-explorer
To authenticate each API request, you need to include your Application Token as the user name and your user Master Access Token as the password. For example, use this option with each cURL request:
--user application_token:master_access_token
- Create a card product to define the properties that control Smarter City Digital Transit Reward cards.
Namely, it is a virtual card that supports instant issuance to Apple Pay. Take note of the token, which you will use when you create cards.
Link: https://www.marqeta.com/api/docs/VhyptRwAAB8A_VeO/card-products
curl -i -X POST \
-H 'Content-type: application/json' \
--user application_token:master_access_token \
-d '{
"start_date": "2017-10-21",
"token": "SC-DTR-CardProduct",
"name": "Smarter City Digital Transit Reward",
"config": {
"fulfillment": {
"payment_instrument": "VIRTUAL_PAN"
},
"poi": {
"ecommerce": true
},
"card_life_cycle": {
"activate_upon_issue": true
},
"digital_wallet_tokenization": {
"provisioning_controls": {
"in_app_provisioning": {
"enabled": true
},
"wallet_provider_card_on_file": {
"enabled": true
}
}
}
}
}' \
'https://shared-sandbox-api.marqeta.com/v3/cardproducts'
- Create a funding source to enable access to the funds needed for a transaction. For a simple test, you can create a program funding source.
Link: https://www.marqeta.com/api/docs/VhyocxwAANkA_U_j/funding-sources
curl -i -X POST \
-H 'Content-type: application/json' \
--user application_token:master_access_token \
-d '{
"token": "SC-DTR-ProgramFundingSource",
"name": "SC-DTR-ProgramFundingSource"
}' \
'https://shared-sandbox-api.marqeta.com/v3/fundingsources/program'
- Create a test user to represent a hypothetical card holder. For a simple test, you can omit most of the body fields and just create a default user. Take note of the token, which you will use when you create a card for this user.
Link: https://www.marqeta.com/api/docs/VhK2YBwAALoAnvJs/users
curl -i -X POST \
-H 'Content-type: application/json' \
--user application_token:master_access_token \
-d '{
"token": "SC-DTR-TestUser"
}' \
'https://shared-sandbox-api.marqeta.com/v3/users'
- Create a Smarter City Digital Transit Reward card for your test user. The card is active right away because we configured the card product to activate upon issue, which is the standard behavior for a virtual card.
Link: https://www.marqeta.com/api/docs/VhypzxwAANwA_Vgx/cards
curl -i -X POST \
-H 'Content-type: application/json' \
--user application_token:master_access_token \
-d '{
"user_token": "SC-DTR-TestUser",
"card_product_token": "SC-DTR-CardProduct",
"token": "SC-DTR-TestCard"
}' \
'https://shared-sandbox-api.marqeta.com/v3/cards'
- Load funds into the user’s general purpose account so that the card has access to funds for transactions.
Link: https://www.marqeta.com/api/docs/VhyqdxwAAN8A_Vxf/orders
curl -i -X POST \
-H 'Content-type: application/json' \
--user application_token:master_access_token \
-d '{
"user_token": "SC-DTR-TestUser",
"amount": "100",
"currency_code": "USD",
"funding_source_token": "SC-DTR-ProgramFundingSource"
}' \
'https://shared-sandbox-api.marqeta.com/v3/gpaorders'
Demonstrating the Smarter City Digital Transit Reward Card in Action
To demonstrate your Smarter City card in action, you can write a routine that simulates transactions with your test virtual card. Include a counter that increments every time a transaction runs against a fictitious “BART” merchant ID number (mid). When the counter reaches 5, send a request to Visa Offers API to create a ride sharing credit of $10 and then reset the counter to 0.
For example, to simulate transactions at a “BART” merchant with the Marqeta API:
curl -i -X POST \
-H 'Content-type: application/json' \
--user application_token:master_access_token \
-d '{
"amount": "10",
"mid": "SC-DTR-BART-Test",
"card_token": "SC-DTR-TestCard"
}' \
'https://shared-sandbox-api.marqeta.com/v3/simulate/authorization'
Link: https://www.marqeta.com/api/docs/VhyrNBwAAB0A_WDD/testing
Adding Cards to Apple Pay
With Marqeta's instant issuance feature, you could build a mobile application that both creates the Smarter City Digital Transit Reward virtual card and automatically adds it to an Apple Pay digital wallet on the user’s device.
To add a card to Apple Pay, it must first be tokenized—which is a process that replaces sensitive card data with a token that serves as a reference to the card. You can use the Marqeta API to retrieve the encrypted card data.
curl -i -X POST \
-H 'Content-type: application/json' \
--user application_token:master_access_token \
-d '{
"card_token": "SC-DTR-TestCard",
"device_type": "MOBILE_PHONE",
"provisioning_app_version": "1.0.0",
"certificates": [
"MIIEPDCCA+ =", "MIIDZjCCAw2gAwI==" ],
"nonce": "vXWJaBidcTLaJJCF",
"nonce_signature": "jD4Aphu+93N2wbBn"
}' \
'https://shared-sandbox-api.marqeta.com/v3/digitalwalletprovisionrequests/applepay'
At this point, you’ll need to integrate with the Apple Pay API. You’ll send the encrypted card data to Apple Pay, and Apple Pay will request a token from the network. After the card network issues the token, Apple Pay stores it on the user’s device, and the card holder can use it to spend their reward credits on a ride sharing app.
Link: (with Apple Pay-specific endpoint used in the code snippet): https://www.marqeta.com/api/docs/WEB4zykAAKUpdPTF/digital-wallets-management
By adding a virtual card directly to a digital wallet, like Apple Pay, you can effectively bypass the need for a proprietary piece of plastic and allow the card holder to use a mobile device as an all-in-one transit card.
Let’s build a smarter transit system for the Smarter City together!
Ahmed Siddiqui is VP of Product Management at Marqeta, the first modern card issuing and core processing platform, powering prepaid, debit and credit cards for the world’s top commerce innovators. He can be reached on Twitter @siddiquiahmed
