Marqeta Integration 101: First Steps and Basic API Structure
The number of companies using Marqeta to issue credit cards and process payments continues to grow quickly. If you’re considering doing the same, it’s important to understand how integrating the platform and its structure with your business works.
Plenty of beginner-friendly documentation exists that outlines the integration process, of course. Marqeta does a great job of making materials that are accessible even to finance and fintech novices. However, I wanted to put together a brief 101 article that offers a simple primer on the process.
In this article, you’ll get a bird’s eye view of Marqeta’s cornerstone models and concepts. I hope this eases the work of digging through official documentation and gives you a basic understanding of the Marqeta integration to support you before you even open their quick guide.
What is Marqeta?
To begin, let’s get an overview of the Marqeta platform.
Companies use Marqeta to launch and manage their payment card programs. The platform works on their behalf with card networks and issuing banks to
- issue cards
- authorize transactions
- communicate with settlement entities
Marqeta takes on all the hard work of card program management and lets you focus on controlling and managing processes via the API, SDK, and Dashboard.
When businesses want to avoid the high investment of building their own card issuing and management software, Kunai has often partnered with Marqeta to help clients integrate, launch, and support this fintech solution.
What can companies kicking things off with Marqeta expect?
Should you decide to leverage Marqeta to power your card program, you’ll move through a few well-defined steps.
1. Define your program.
The journey begins with defining your company’s card program. This is where you lay out the features and constraints of your card program. This includes the type of funding sources, whether you’ll issue physical and/or virtual cards, KYC details, and more.
Marqeta’s managers help you navigate this process, which is largely driven by human communication. This stage relies heavily on you, the client company, and your tech department. All three groups should work together to capture important context, including the following:
- the type of API used
- how authorization tokens are issued, and
- synchronous vs. asynchronous processes
These details and others will help the tech team plan, estimate the results of, and implement the solution.
2. Explore the sandbox.
After the features and constraints are hashed out, Marqeta creates a virtual sandbox. The sandbox is a dedicated cloud environment designated specifically to execute payment orchestration operations only for your company.
If you’re interested in learning the platform without this custom environment, perhaps you’re doing research on various financial APIs or negotiations between parties are taking longer, and you want to start development to be on time, then you can create your own dev sandbox on their website.
Some of your required parameters and entities will already be in the sandbox waiting for you. You can also access API endpoints and API keys to use in your HTTP requests from the sandbox’s home page:
The screenshot above is the simplest version of the Marqeta Dashboard: the web frontend through which you control your sandbox. This lets you control users, cards, payment options, API access, and much more.
It’s entirely up to you if you want to use the standard dashboard to manage your card program or want to build your own frontend using the custom flow. You might want to do that if you want to embed the dashboard features into your existing ERP portal or you want to give some of the control to end users. All the functionality is available through the API, so either approach works just as well as the other.
3. Create entities.
When you have access to a sandbox, you’ll need to create a User and Card in order to be able to perform transaction authorization. You’ll find a sample of commands that let you do exactly that in the Quick Guide.
At this point, you now have a sandbox and can access it via the Core API or Marqeta’s Dashboard. Within that sandbox, you have created a User and a Card. Now we’re ready to talk about where the money comes and goes within this structure.
The pipes that support money flow
The User and the Card are only the tip of the iceberg. They aren’t floating somewhere independently, but rather fit into a bigger and very important picture. Let’s dig into some details.
Understanding Account Holders
The User is a special kind of Account Holder. An Account Holder can either represent a real-world customer of Marqeta’s, such as your business, or it can represent your employees or clients. The exact representation depends on the type of business you’re running.
There are two types of Account Holders:
- User: an individual account holder, represented by the user object
- Business: a company account holder, represented by the business object
When you create Users, Businesses, and Cards or perform other actions in the sandbox, your application calls the Core API to create and manage users and businesses. You are communicating with the Core API via endpoints and tokens you find in the Dashboard.
Defining Relationships and How GPA Works
With the sandbox tools, you can do things like create parent-child relationships. This enables the child User to inherit some attributes and behaviors of the parent Business.
Each User and Business on the platform has a general-purpose account (GPA). The GPA holds funds used to make payments. The GPA is tied directly to the user or business — in other words, there is no separate GPA resource.
Managing Money Supply
This brings us to the supply side of the Marqeta platform. Pipeline money is dispensed from GPA. There are a couple of ways to fund a GPA, and these depend on the funding model you selected for your particular card program.
Without getting into too much detail, let’s look at two primary approaches:
- Standard Funding: card accounts that carry a balance of funds for making payments. Funds are loaded into individual GPAs before cardholders can spend.
- Just-in-Time (JIT) Funding: card accounts that carry no balance. Funds are held in your program funding account until a cardholder initiates a purchase.
You can manage funding sources using API calls such as /fundingsources/ach, /fundingsources/card, /fundingsources/program, and others found in the Core API docs.
Spending with Marqeta
Now let’s talk about the spending end of the pipeline, which is done via cards.
A User can own one or more cards. These are used as payment devices to spend funds from an account. Businesses cannot own cards; however, you can configure a child User to spend funds from a parent Business account.
You can also create both physical and virtual cards. Marqeta orders physical cards from a third-party provider and delivers them to specified addresses. Virtual cards are ready to use immediately.
Card Objects vs. Card Products
The card object in Marqeta stores details about the card like card number and security code. It’s a digital representation of an individual card. Each card has an associated User object, representing the card user, and a Card Product object, representing the card program with which it is associated.
The Card Product object defines attributes and behaviors for all associated cards. It operates as a template when creating new cards, but it’s important to note that the association with the Card Product object 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. That’s one of the entities you’re working to get right with sandbox.
This diagram summarizes the minimum structure you need to understand when dealing with Core API in Marqeta. If you can grasp this, you’re ready to fully appreciate the official documentation.
Moving beyond the basics...
There are several other important things you can do with Marqeta in order to fully leverage its potential. In fact, every or almost every integration Kunai performed for its clients required the following features to also be enabled:
- KYC - or Know Your Customer. This is the procedure for verifying that individuals (or businesses) are those who (or what) they claim to be. Marqeta provides a couple approaches to KYC depending on your business situation
- Spend Controls - This is the portion of the API that allows you to set up constraints regarding individuals’ spending. This also plays a role in JIT funding.
- Just-in-Time Funding - JIT funding is how the system makes decisions about approving or declining transactions. It also determines the way you tailor this process to your business case.
- Digital Wallets - As the world moves away from plastic, mobile-enabled spending is an increasingly common request from customers.
- Webhooks - This is the way your system receives asynchronous notifications about events generated by users or businesses. Use webhooks to build a great UX or to feed your system with real-time data
I wish you luck in your explorations; have fun experimenting with Marqeta API!