Basic Architecture of Payment Apps using Marqeta | Part 1 of 2

[Ricardo]

Part One Getting to Know the Platform and the Models

The open, extensible, and customizable design of the Marqeta platform is what makes it so attractive to businesses that want to tailor payment experiences. Those same characteristics can make it seem complex to get started with, but it’s not. All you need is a basic understanding of the main components of the platform and Marqeta’s Core API.

To help you get up to speed, we’ve put together this two-part series to cover everything you need to know. In Part One, we’ll cover the basic architecture and models that enable developers to create payment apps using Marqeta. In Part Two, we’ll get our hands dirty with a walkthrough usage of the Core API, working with users and...

Are you ready? Let’s dive in and get to know the Marqeta platform.

The Basic Building Blocks

The basic building blocks of Marqeta payment apps are:

• Account holders: the users or businesses that have accounts on the platform
• Funding sources: the source of money for an account
• Cards: the virtual or physical cards that account holders use to perform transactions

Once you understand how these three models work and interact, designing business logic for your apps and financial products is simple. Our developer guides explore these topics in-depth, so here we’ll focus on the basics you need to get started building your apps.

Account Holders 

There are two types of account holders on the platform:

• User: an individual represented by a user API object
• Business: a company represented by a business API object

The fundamental difference between the two types is this: A business cannot own cards. 

These endpoints contain personally identifying information related to an account and details such as the following:

• spending accounts
• balances
• associated cards
• group membership
• parent-child relationships

A general purpose account (GPA) is associated with each account holder. A GPA stores the funds for payments on a given account. You can check an account holder’s GPA at the balances endpoint. 

You can create parent-child relationships, in which parent businesses (or parent users) monitor and/or control the spending of child users. Note that a business cannot be a child. For example, multiple users can use funds from the GPA of a single parent business (or parent user), like this:

Alternatively, child users can use funds from separate GPAs which the parent manages individually.

You can also create parent ⇢ child ⇢ grandchild users where the “child” does not use the parent’s GPA, but rather the “grandchild” draws from the “parent” GPA. 

Understanding the account holder lifecycle

Every account holder has a status that dictates whether or not they can carry out transactions. Possible statuses include:

• Active: The account is activated and available to use without restrictions.
• Active-Limited: The account is in an Account Holder Group and subject to specific rules related to Know Your Customer (KYC) requirements, defined in the accountholdergroups.pre_kyc_controls endpoint.

• Inactive-Unverified: Funds cannot be loaded and cards cannot be activated until KYC verification completes.

• Inactive-Suspended: The account has been suspended, funds cannot be loaded, and cards cannot be activated.

• Inactive-Closed: The account has been closed, funds cannot be loaded, and cards cannot be activated. The difference between suspended and closed is simple: “closed” implies the account will be permanently inactive while “suspended” implies it will be temporary. 

The initial status of an account generally depends on KYC requirements and can change throughout the account holder lifecycle (for example, if an account is suspended or closed). The diagram below details the different potential transitions.

KYC verification

Some card programs require KYC identity verification before a user can conduct transactions. While we won’t need to perform KYC in our sandbox environment, the Core API has a KYC endpoint that makes verification simple.

Above, we briefly mentioned Account Holder Groups. An account holder group is a way of grouping together multiple account holders—those are users and/or businesses—as a group. This is particularly related to KYC because you can uniformly apply KYC rules across the board for all new account holders in an account holder group.

Funding Models and Funding Sources

We already touched on the GPA and its use as an account to hold funds for individual account holders. Funding models and funding sources define where the funds in an account come from and how balances are carried. 

There are two basic funding models on the Marqeta platform, and each requires a different type of funding source. 

• Standard funding model: GPAs carry a balance and must be funded before any transactions can occur. Account balances must be managed to avoid under/over funding. With the standard funding model, accounts depend on a program funding source. For a closer look at exactly how funds flow with the standard funding model, check out Money Movement Overview. 

• Just-in-time (JIT) funding model: With JIT Funding, GPAs do not carry a balance, but are funded automatically during the transaction process. Marqeta automatically moves funds from a program gateway funding source into a given GPA as transactions occur. Compliance in the payment-processing space is vital, so bank accounts used as a program funding source must be approved by Marqeta and the issuing bank. If you use a third party to collect funds, they must comply with specific reporting standards. For a closer look at how funds flow with the JIT funding model, check out Gateway JIT Funding Scenarios. 

Managed versus Gateway JIT funding

Under the JIT funding model, there are two different approaches you can take:

1. Managed JIT: You predefine rules on how a cardholder can use their card, and the Marqeta platform approves or denies transactions based on those rules. You do not explicitly approve or deny individual transactions. Visually, here’s how the process works:

2. Gateway JIT: You configure a JIT gateway to individually evaluate and approve each funding response. With Gateway JIT, the process flow looks like this:

 If your JIT Gateway becomes unresponsive, you can configure Marqeta’s Commando Mode to be in effect. When turned on, Commando Mode takes over and approves/denies requests based on predefined rules. Essentially, if your JIT Gateway fails, Commando Mode gives you Managed JIT Funding as a failsafe until the gateway is back up. 

Benefits of JIT funding

As you’d expect, approving or denying transactions programmatically in real-time adds some complexity. So, why bother? The JIT funding model allows you to implement business logic to approve or deny every transaction, have more granular control over cash flow, and use custom metadata to speed up reconciliations.

Cards and Card Products

So far, we have covered account holders and account funding. However, account holders need a card to carry out transactions. On the Marqeta platform, understanding cards begins with the following concepts:

• Cards: Specific payment cards—which can be physical or virtual—that users transact with are represented by the card API object. Cards are assigned to individual users and are the object on which merchants make authorization requests. A single-use card is only good for one transaction, and then the platform terminates the card. A multi-use card, like a traditional payment card, is good for multiple transactions and usually terminates at its expiration date. 

• Card products: A card product API object acts as a template to define the characteristics of one or more cards. Card products define things like color and printing characteristics of a physical card, restrictions on card usage, if cards can be used at an ATM or online, or other common attributes.

It’s important to understand that not every account holder is a cardholder. Cardholders are a subset of account holders consisting of users that have been issued at least one card. A user account holder can have zero, one, or multiple cards assigned to them. An individual card can only be assigned to one user. 

Like accounts, cards have a lifecycle with various stages. Physical cards are unactivated until an activation event occurs, while virtual cards are active upon creation. A card can also go into a suspended status, from which it can be restored to active or to a permanently terminated status where it can never be used again. The diagram below details all possible status changes throughout the card’s lifecycle.

Looking Ahead

Just like that, we’ve covered all of the core concepts for the Marqeta platform that you need to know to get started. Now, you should be ready to jump in and get your feet wet. Join us for the next part in our series, where you’ll begin working directly with the Core API in your sandbox.

Head on over to Part Two. We’ll meet you there!