Cards in the payments ecosystem
In the payments ecosystem, a card stores data necessary for a merchant to make an authorization request. The card holder presents the card to the merchant at a physical point of sale or enters the information into a form for an online purchase. When the merchant has the card data, they can attempt to complete the transaction.
Cards store multiple pieces of data necessary to complete a transaction, including the following:
- Name – card holder's name.
- Primary account number (PAN) – unique identifier that appears on the front of the card; identifies the card network, issuing bank, and card holder account.
- Expiration date – date when the card expires.
- Card verification value (CVV2) – verification number that appears on the back of the card, usually used for “card not present” transactions. Some card networks refer to this as the card verification code (CVC).
Some cards, including EMV "chip and PIN" cards, also require a personal identification number (PIN). You can also choose to enable the PIN feature, whether it is required or not. If a PIN is required or you opt to enable it, you must provide the card holder a method of setting the PIN. Available methods include the following:
- An iframe widget that injects a PIN-setting tool into your webpage or web application.
- Over the phone, using an interactive voice response (IVR) system.
- The /pins endpoint of the Marqeta API.
Note: Funds are not loaded onto or directly associated with a card. Rather, a card is a device used to access funds held in a user or business account.
You can issue cards in the following form factors:
|Physical||A traditional plastic card, ordered through a third-party provider, shipped to the address provided.||Making payments at physical points of sale.
For example, you can issue a physical card to enable a delivery service to make any necessary purchases at retailers.
|Virtual||A virtual payment card with no physical component.||A card intended for immediate use.
For example, you can issue a virtual card to make a payment to a retailer after the user signs up for an alternative lending payment plan. The lender can add the necessary funds to an account and create a new one-time-use virtual card to provide payment to the retailer.
You can also provision digital wallet tokens for use in digital wallets like Apple Pay and Google Pay. Digital wallets enable users to make in-store and online payments using any device storing their tokenized card. Each token is based on an existing physical or virtual card. For more information on tokenization and digital wallets, see Digital Wallets and Tokenization.
Single- vs. multi-use cards
You can configure a card to be usable once or multiple times.
- A single-use card only functions for one transaction, after which the Marqeta platform terminates the card.
- A multi-use card functions for multiple transactions, usually until the expiration date is reached.
Note: You can create a single-use card by applying a velocity control. A velocity control specifies how much and how frequently a user can spend their funds. For more information on setting up a single-use card, see the Controlling Spending page.
Number of cards
You can set the number of active or suspended cards each user can own. The following card ownership scenarios are possible:
- Each user can own a single active or suspended card.
- Each user can own multiple active or suspended cards that share the same PAN (by reissuing an existing card).
- Each user can own multiple active or suspended cards with one or more PANs (by issuing original cards or reissuing existing cards).
For information on creating original cards and reissuing existing cards, see "Issuance and reissuance".
The card object
The card object is a first-class object that represents a payment card issued by Marqeta. The card object stores details about the card, including the card number and security code.
Each card has an associated card product object and a user object.
- The cardproduct object is a first-class object that defines attributes and behaviors for all associated cards. The card product operates like a template when creating new cards, but the association continues—updating the card product affects each associated card throughout the card's lifetime. Your program needs at least one card product before you can create a new card. You will work with Marqeta to create new card products in the production environment.
- The user object is a first-class object that represents a current or potential card holder. In addition to storing details like name, address, and phone number, a user also represents an account to which funds can be added, and from which funds are drawn at transaction time.
Note: Each user can have a parent user and one or more child users associated with it. If configured, funds held in a parent user account can be drawn from using a child user's card. The parent account can also be a business account—businesses are never a child to a user account. The business object can have associated fundingsource objects, but it cannot have an associated card object.
The attributes of a card product answer the following questions about cards:
- Is the card physical or virtual?
- For physical cards, where are they shipped?
- Where can a card holder conduct transactions, and what is required of them to complete a transaction?
- When is the card activated? When does it expire?
- Can the card be added to a digital wallet?
The following table outlines a card's attributes and behaviors by their source.
|Source||Attributes and behaviors|
|Card (provided by you at card creation time)||
|Card (Marqeta-provided at card creation time)||
Some configurations defined in the card product can be overridden at the card level, potentially requiring additional data in the API request.
For example, Marqeta configures your card product's instrument type to be physical or virtual. Issuing physical cards requires you to specify how Marqeta should fulfill the card order. You must specify where to ship each card and what personalizations, if any, are applied to the card and/or the card mailer. This can be defined at the card product or individual card levels. On the other hand, issuing virtual cards does not require these details.
The card lifecycle
From issuance to expiration, cards transition (or switch) between several states during their lifetime. The following endpoints enable you to manipulate a card's state:
- To issue a new card or reissue an existing card, use the /cards endpoint.
- To transition a card between states, use the /cardtransitions endpoint.
Note: In addition to your API calls, Marqeta and the card holder can affect the state of a card.
The following diagram outlines the possible transitions between states.
Issuance and reissuance
When issuing a card, you can choose to create an original card or to reissue an existing card. A reissued card behaves the same and has the same card number as the source card. For example, if a card has expired, you can reissue the card with the same PAN and a new expiration date.
You can only reissue a source card once; the source card can be an original card or a reissued card. For example, you might create an original-issue Card A, then reissue Card A as Card B, and then reissue Card B as Card C, resulting in a reissue chain that looks like this: "Card A > Card B > Card C".
You can also configure whether the original card is automatically terminated or remains active when reissued, though this is limited by your program's maximum active card limit. Contact a Marqeta Customer Success representative to determine how many active cards your users can own.
Note: All digital wallet tokens associated with a reissued card are reassigned to the new card when it's activated.
Cards must be activated before use. You can configure your card product so that new cards are active upon issuance. In general, new physical cards are shipped in an unactivated state, while new virtual cards are digitally presented (shown on a screen, for example) and active immediately.
Activating an original-issue card (as opposed to a reissued card) never affects other cards owned by the user. An error is returned if any attempted activation would result in the user owning more active and/or suspended cards than the maximum allowed by the program configuration.
If you issue unactivated cards, you must provide your card holders a method for activating them. The method you choose depends on your implementation and data security compliance requirements.
Available methods for activating cards include:
- An iframe widget that injects a card activation tool into your webpage or web application.
- Over the phone, using an interactive voice response (IVR) system.
- The /cardtransitions endpoint of the Marqeta API.
Suspension and termination
To make a card temporarily nonfunctional, you can suspend it. Suspended cards can transition back to the active state.
To make a card permanently nonfunctional, you can transition it to the terminated state. Terminated cards cannot be reactivated.
Note: Clearing and refund events will succeed for suspended and terminated cards.
When you create a new card, the Marqeta platform assigns an expiration date and time. When the expiration time is reached, the card is terminated automatically. You can set the expiration date for a card product or an individual card.
Lost, stolen, or damaged cards
When a card holder is separated from their card or it becomes physically nonfunctional, you should take action to limit potential fraud and provide the user a functional card.
In general, you should respond to card problems in the following ways:
- If a card is lost, you should suspend or terminate the card and reissue it with a new PAN.
- If a card is stolen, you should terminate the card and reissue it with a new PAN.
- If a card is damaged, you should terminate the card and reissue it with the same PAN.
Note: For more information, see Managing Lost, Stolen, or Damaged Cards page.