Putting Marqeta To Work

Marqeta is a nimble payments platform with full feature-rich functionality, making it quick and easy to set up new payment cards, configure multiple funding types, and define how and where cards can be used in real time. Marqeta can power a host of specialty applications, from processing and program management, to multi-merchant commerce, to dynamic spend controls for both business-to-business and consumer use cases.

The platform is available through a set of modern RESTful APIs, meticulously built from the ground up with no legacy infrastructure to tie down. Marqeta puts experimentation, A/B testing and rapid cycling of product development at your fingertips.

Hero arrow api Hero arrow api small

API Terminology


Click A Card To See Definition
Auth Controls

Auth controls and velocity controls are used to define spending controls: where and how a transaction may occur. These controls can be associated with (applied to) a user, a card product, or an entire program (everything). Auth controls limit where a transaction may occur. Velocity controls define spending limits such as how much can be spent per day and how often a card may be used.

An important note for auth controls is that you must first define your default behavior, whether to disable everything by default or to enable everything by default. Then, you create exceptions. For example, if you only want to accept transactions at StoreX then you'd set the default behavior to disable everything, then you would create an auth control to enable StoreX. Conversely, if you wanted to enable everything except liquor stores then you could set the default to enable everything and add an auth control which restricts the alcohol MCC.

Campaigns

A campaign is primarily a group of stores, though it also accepts parameters for defining when it's active. Campaigns are used with offer orders and MSA orders. For example, a campaign would be used to enable an offer for a group of stores for a certain period of time.

Card Products

The card products resource represents the behavior/functionality of one or more cards (physical or virtual). For example, attributes of the card product determine the color (if it's a physical card), whether it can be used at an ATM and/or online, and whether the associated card is currently enabled. For physical cards, the card product also determines the physical printing specifications when the card is manufactured and personalized. You may optionally associate auth controls and/or velocity controls to card products in order to restrict where and how any associated cards can be used.

In most cases, Marqeta will take care of creating the card products for you in a production environment.

Cards

The cards resource represents how a user conducts transactions, either by physical or virtual card (determined by the card products object). Cards have attributes such as personal account numbers (PANs), expiration dates, CVV/CVV2 numbers, and so on. Cards communicate to Marqeta over networks like Discover, Mastercard, and VISA. A card is owned by a user and controlled by a card product.

Note that because accounting and balance information is associated with the users resource, physical cards can be replaced when lost or stolen while leaving account balances intact.

Fee Transfers

Fee transfers are used to assess a fee. Effectively, fee transfers move funds from a user's general purpose account (GPA) and into a partner account. Note that a fee may also be assessed directly against a user's funding source by using a GPA order.

Fees

Fees represent instances of things for which the partner may choose to bill the user. For example, you may create a yearly subscription fee; once per year you then submit either a fee transfer or GPA order to assess this fee to a user and transfer the funds for the fee into the the partner bank account.

Funding Sources

Funding sources are typically owned by a cardholder and enable access to funds outside of the Marqeta platform. Funding sources include credit/debit payment cards, bank (ACH) accounts, points, and alternative funding APIs. The special program funding source allows funding as a book transfer inside the Marqeta platform. This is useful when a partner wants to fund accounts directly for promotional or B2B reasons. After funding sources are created they are used when submitting 'orders' (MSA orders, GPA orders, offer orders).

GPA Orders

GPA orders are used to load funds into a user's general purpose account (GPA) from one of the user's funding sources. GPA orders may also move funds for a fee from a user's funding source into a partner bank account.

Merchants & Stores

The merchants resource represents a business. A store is an instance of a merchant; there may be many stores belonging to a given merchant* A store can be either a physical location or an e-commerce site. Creation of merchants and stores is only required if you are performing some merchant-specific action such as the creation of an MSA order, an offer order, or a location-specific velocity control or auth control. Note that you'll need to onboard a store before you can use it.

MSA Orders

Creating a Merchant Specific Account (MSA) order is the equivalent of buying credit that can be used later only at a specific merchant and one or more stores. MSA orders may be funded by a user or by a partner. MSA orders require a campaign.

Offer Orders

An offer order associates an offer to a user. Its attributes include information that identifies the user, the offer, and the order number of the offer.

Offers

An offer represents a deal that is available for one or more store(s) (associated via campaigns). For example, you may create a campaign which includes SampleStore1 and SampleStore2, and which links to an offer that provides $50 in store credit for the cost of $30. Submitting an offer order purchases the offer and associates it with a user. The user can then use their card to spend the $50 in store credit at SampleStore1 or SampleStore2.

Orders & Transfers

Here's a brief explanation regarding the Marqeta API nomenclature. An 'order' represents the movement of funds from an external funding source to a user's general purpose account (GPA). External funding sources may belong to a user (such as a bank account), a merchant, or even an employer.

A 'transfer', on the other hand, represents the movement of funds within the Marqeta system only. For example, a peer transfer from one user's GPA to another's, or a fee transfer that moves funds from the user's account to partner's account.

Peer Transfers

Peer transfers move money between the general purpose accounts of two users.

Users

The users resource represents a cardholder account. It contains metadata that describes a person, such as first name, last name, address, city, state, zip, SSN, birth date, and so on, as well as financial information such as balances and other accounting details. Additional metadata, like phone number and email address, can be used for services such as IVR (Interactive Voice Response), SMS, and email.

Storing financial information and balances with the user is preferable to storing it with a card (see below). If a card is lost or stolen the card can be easily replaced with a new card associated to the user.

The primary account for every user is called the general purpose account (GPA). The GPA is funded by using a funding source. GPA funds can be used when a card is swiped at a merchant, when transferring funds to another user, or when being assessed certain types of fees. Note that MSA orders and offer orders do not leverage the GPA; please see the respective sections for more details.