/
10 minute read
September 8, 2022

About Cards

A card is a payment device that enables a user to conduct transactions at merchants. Cards can be physical or virtual. You can also tokenize cards for use in digital wallets.

Payment cards are represented on the Marqeta platform by the card object, which stores data about a card. Your application calls the Marqeta Core API to issue and manage cards.

The Marqeta platform enables you to customize a card’s attributes, behaviors, and lifecycle, including limits on spending, the number of card uses, and the number of active cards.

For the complete /cards endpoint documentation, see the Cards API reference page.

At the end of this guide, you should understand:

  • The role cards play in the payments ecosystem.

  • The card object on the Marqeta platform.

  • The card lifecycle, from issuance to termination.

Cards in the payments ecosystem

In the payments ecosystem, a card stores data necessary for a merchant to make an authorization request. The cardholder 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 – cardholder’s name.

  • Primary account number (PAN) – unique identifier that appears on the front of the card; identifies the card network, issuing bank, and cardholder 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 cardholder 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 Core 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.

Form factors

You can issue cards in the following form factors:

Form Factor Description Scenario

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 Wallet. 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.

Tip
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 guide.

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 your production environment.

  • The user object is a first-class object that represents a cardholder. 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. For more information, see About Account Holders.

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 cardholder 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)

  • Token

  • User token

  • Card product token

  • Fulfillment and personalization

  • Expiration date

Card (Marqeta-provided at card creation time)

  • last_four

  • PAN

  • PIN

  • Expiration date

  • Barcode

  • State and state reason

Card product

  • Instrument type (form factor)

  • Point-of-interaction configurations

  • Fulfillment and personalization

  • Expiration date and card lifecycle

  • Transaction controls and address verification

  • Spend controls

  • Digital wallet tokenization

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 cardholder can affect the state of a card.

The following diagram outlines the possible transitions between states.

Possible transitions between card states

Is this helpful?

Yes
No

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 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.

Activation

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.

It may not be possible to move a card from one user to another user once the card has been activated.

If you issue unactivated cards, you must provide your cardholders 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 IVR system.

  • The /cardtransitions endpoint of the Core API.

Suspension, limitation, and termination

To make a card temporarily non-functional, you can limit or suspend it. A limited card is temporarily non-functional except for card-on-file transactions such as installment payments or recurring charges. A suspended card is temporarily non-functional for all transactions.

Limited and suspended cards can transition back to the active state.

To make a card permanently non-functional, you can transition it to the terminated state. Terminated cards cannot be reactivated.

Note
Clearing and refund events will succeed for suspended, limited, and terminated cards.

Expiration

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 cardholder is separated from their card or it becomes physically non-functional, 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 reissue it with a new PAN and suspend or terminate the card.

  • If a card is stolen, you should reissue it with a new PAN and terminate the card.

  • If a card is damaged, you should reissue it with the same PAN and terminate the card.

Note
The reissued source card For more information, see the Managing Lost, Stolen, or Damaged Cards guide.

Moving active cards between users

In general, an active card belongs to a single user for its lifetime. For some use cases, however, you might want to move an active card from one user to another, enabling the card to draw funds from the balance of a different account on demand. This allows the cardholder to spend from multiple accounts using the same card.

Note
This feature is disabled by default and requires activation by Marqeta. To learn more, contact your Marqeta representative.

For example, an expense program might have a cardholder represented by a user named "John_Smith" with two child users named "John_Smith_Food" and "John_Smith_Travel". Note that in this example, these child accounts all belong to the same person but are distinct users on the Marqeta platform. Each child user has its own balance and is associated with its own card.

Each user on the Marqeta platform has a general purpose account (GPA) that holds funds used to make payments. For more information, see About Account Holders.

The cardholder, John Smith, is at a restaurant and wants to spend from his "John_Smith_Food" child account using the associated card ("John_Smith_Food_Card"), but he accidentally brought the card associated with "John_Smith_Travel". He wants to be able to login to the mobile app he uses to manage his cards so he can update his "John_Smith_Travel_Card" card to draw funds from his "John_Smith_Food" account.

To move a card to another user, send a PUT request to /cards/{token} and include the user_token of the alternate account you want to use. For example, to update John Smith’s travel card so it spends funds from the account of "John_Smith_Food", send the following PUT request to /cards/John_Smith_Travel_Card:

JSON
Copied

Is this helpful?

Yes
No

Future spending draws funds from the newly associated account and any existing spend controls associated with the account holder apply when spending with the card. You can send additional PUT requests to move the card to the original user or to another user.

When a user spends with a card, the token of the account that funded the transaction is included in the associated transaction object. Any subsequent related transactions, such as a clearing message, retain the token from the original transaction, even if the card moves between users in the meantime. For more information, see About Transactions.

Subscribe to our developer newsletter