About Account Holders
An account holder is an individual or company that holds an account on the Marqeta platform. Account holders can be one of the following types:
-
User – An individual account holder, represented by the user object.
-
Business – A company account holder, represented by the business object.
Both the user and business objects store personally identifying information and other attributes and configurations.
Your application calls the Core API to create and manage users and businesses.
You can create parent-child relationships, which enable the child to inherit some attributes and behaviors of the parent. You can also configure a child to draw funds from a parent account when making a payment.
For a complete description of the /users endpoint, see Users.
For a complete description of the /businesses endpoint, see Businesses.
At the end of this guide, you should understand:
-
The difference between users and businesses on the Marqeta platform.
-
How to build parent-child relationships.
-
The user and business lifecycles, from creation to closure.
The role of users and businesses
Copy section link
In general, an account holder represents one of your customers. Each user and business on the Marqeta platform can have one or more associated entities, including accounts, cards, and spend controls. During the transaction process, the Marqeta platform makes authorization decisions based on account balance data, the card being used, and controls associated with the user.
In addition to personally identifying information, the attributes of users and businesses answer the following questions:
-
What is the balance of the account?
-
Is the user a child of another user or a business?
-
Does the child spend with the account of the parent?
-
Is the associated card a corporate card?
-
To which account holder group does the account holder belong?
-
What are the details of the associated deposit account?
Accounts and funds
Copy section link
Each user and business on the Marqeta 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.
To retrieve account balances, use the /balances endpoint.
For more information, see Balances.
Cards
Copy section link
A user can own one or more cards, which can be 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.
Note
An account holder is a distinct concept from a cardholder. On the Marqeta platform, a user who owns no cards is still an account holder, but is not a cardholder. All cardholders are account holders, but not all account holders are cardholders.For more information, see About Cards.
Spend controls
Copy section link
On the Marqeta platform, you can create spend controls that limit where and how much a user can spend. Spend controls can affect one or more users depending on how they are configured.
-
A spend control associated with a user applies only to that user.
-
A spend control associated with a card product applies to every user who owns a card associated with that card product.
You cannot create spend controls for businesses because businesses do not spend with cards.
For more information, see Controlling Spending.
Identity verification
Copy section link
To minimize fraudulent activity, the Marqeta platform uses personal data stored in a user or business to perform the following verifications:
-
Know Your Customer (KYC) – An identity verification process performed on user and business resources at creation time. Some programs require account holders to pass identity verification before loading funds or making payments. For example, if your program supports reloadable cards, the Marqeta platform requires account holders to undergo identity verification because of regulatory mandates intended to prevent activities like money laundering. Other programs require that a business passes KYC Verification before cardholders perform any transactions. In such cases, Marqeta recommends that you do not create child users of a business or issue any cards until after that business has passed KYC verification and is in the
ACTIVEstate. For more information, see About KYC Verification. -
Address Verification System (AVS) – An identity verification process performed on authorizations and tokenization requests at transaction time. The Marqeta platform compares the address provided by the cardholder with the address held on file for the associated user or business. The outcome of this verification depends on your program configuration. For more information, see About Address Verification.
Account holder groups
Copy section link
Each account holder is associated with an account holder group. Account holder groups enable you to configure multiple account holders with a common set of attributes and behaviors. For example, you can configure the following:
-
Whether cards owned by users in the group are reloadable.
-
Whether KYC is required for account holders in the group.
-
The maximum balance of accounts for users and businesses in the group.
By default, the Marqeta platform associates new account holders with your program’s default account holder group. The configuration of the default group is managed by Marqeta. You can also associate account holders with a custom group.
For more information, see Account Holder Groups.
Users vs. businesses
Copy section link
The following table compares the functionality of user and business entities.
| User | Business | |
|---|---|---|
Stores personally identifying information |
Yes |
Yes |
Owns a GPA |
Yes |
Yes |
Can own cards |
Yes |
No |
Affected by spend controls |
Yes |
No |
Can be a parent of a user |
Yes |
Yes |
Can be a parent of a business |
No |
No |
Can be a child of a user |
Yes |
No |
Can be a child of a business |
Yes |
No |
Parent-child relationships
Copy section link
You can associate users and businesses with one another by creating parent-child relationships. This relationship enables a parent user or business to monitor the spending of its children. You can optionally enable a child user to make payments using funds held by the parent’s account.
The following rules apply to parent-child relationships:
-
A user or business can be a parent, but only a user can be a child.
-
A parent can have multiple child users, but a child user can only have one parent.
-
A user can be a child of a business and the parent of one or more users simultaneously.
-
A child user cannot spend funds if its parent is not active.
-
An active child user can activate cards, whether the parent is active or not.
Making payments using a parent account
Copy section link
By default, a user making a payment draws funds from its own account.
You can, however, configure a child user to draw funds from its parent account instead.
To enable this, set the value of uses_parent_account to true when creating the child user.
In this configuration, you can load funds onto a single parent account and have multiple child users draw funds when spending with their cards.
Warning
In a production environment, you must make this configuration when you create the child user. Existing users cannot be updated to draw funds from a parent account.
Expense management use case
Copy section link
In the expense management use case, business customers want to pay for employee expenses, but do not want to manage funding for individual accounts. Business customers also want to implement velocity controls to limit employee spending.
Using parent-child relationships, you can configure the child users (the employees) to draw funds from the parent business to make payments. This enables you to fund payments for multiple child accounts using a single parent account.
To support this configuration, you can create the following parent-child hierarchy:
-
Create a parent business, as described on the Businesses API reference page. This business represents your business customer.
-
Create one or more child users, as described on the Users page, ensuring that you specify
uses_parent_account=truewhen creating each user. These users represent the employees of your business customer. -
Create velocity controls for each child user, as described on the Velocity Controls API reference page. For example, you could create velocity controls for your child users that limit spending to a maximum of $500 per 30-day period.
Supported parent-child relationships
Copy section link
The Marqeta platform supports the following parent-child relationships:
Parent business, child users, separate accounts
Copy section link
In this relationship, the parent business has one or more child users.
Each child user draws funds from their own GPA (uses_parent_account=false).
This relationship allows the parent business to monitor and control spending for its child users. The business must manage funding for one or more child GPAs.
Parent business, child users, shared account
Copy section link
This relationship is described in the expense management use case.
The business user has one or more child users.
The child users draw funds from the parent business' GPA (uses_parent_account=true).
This relationship allows the parent business to monitor and control spending for its child users without managing funding for child GPAs.
Parent business, child users, grandchild users
Copy section link
In this relationship, the parent business has one or more child users.
Each child user uses their own GPA.(uses_parent_account=false).
Those child users have one or more child users of their own (grandchild users to the top-level business) that draw from their parent users' GPA (uses_parent_account=true).
For example:
-
Your Company Enterprises is the parent business
-
Jane Smith is the child user, who draws funds from her own GPA.
-
John Smith and Jack Smith are the child users of Jane Smith, and the grandchild users of Your Company Enterprises. John and Jack draw funds from Jane Smith’s GPA.
This relationship allows the parent business to monitor and control spending for its child and grandchild users, while managing only a select number of child GPAs. Using the previous example, Your Company Enterprises can monitor and control spending for Jane, John, and Jack, but only needs to manage Jane’s GPA.
Parent user, child users, separate accounts
Copy section link
In this relationship, the parent user has one or more child users.
Each child user draws funds from their own general purpose account, or GPA (uses_parent_account=false).
This relationship allows the parent user to monitor and control spending for their child users. The parent must manage funding for one or more child GPAs.
Parent user, child users, shared account
Copy section link
In this relationship, the parent user has one or more child users.
Each child user draws funds from the parent user’s GPA (uses_parent_account=true).
This relationship allows the parent user to monitor and control spending for their child users without managing funding for child GPAs. This relationship might also represent an authorized or acting user, such as a spouse, sharing an account balance.
Parent-child relationships and Just-in-Time Funding
Copy section link
If you use Just-in-Time (JIT) Funding, you are responsible for managing your own ledger balances. You can use parent-child relationships to facilitate reporting.
Note
If you use JIT Funding, you do not set velocity controls on the Marqeta platform. Rather, the decision to fund transactions comes from your own business logic.For more information about JIT Funding, see About Just-in-Time Funding.
The account holder lifecycle
Copy section link
Each account holder has a status that defines which actions it can take. Users and businesses objects transition between (or change) statuses during their lifetime. The following endpoints enable you to manage an account holder’s status:
-
To create a new
user, use the/usersendpoint. -
To create a new
business, use the/businessesendpoint. -
To transition a
userbetween statuses, use the/usertransitionsendpoint. -
To transition a
businessbetween statuses, use the/businesstransitionsendpoint.
The following diagram outlines the possible transitions between statuses.
Activation
Copy section link
The initial status of a new user or business depends on the KYC requirements of your program or the associated account holder group.
If the user or business passes KYC, the status transitions to ACTIVE.
| KYC Required? | Initial Account Status | Account Restrictions |
|---|---|---|
Always |
|
|
Conditionally |
|
|
Never |
|
|
Suspension and closure
Copy section link
To make a user or business temporarily non-functional, transition it to the SUSPENDED status.
An account holder in the SUSPENDED status cannot have funds loaded onto the account or activate cards.
Suspended account holders can transition back to the ACTIVE status.
Transitioning a suspended account holder to the ACTIVE status is restricted based on your role and the details of the previous status change.
To make a user or business permanently non-functional, transition it to the CLOSED status.
An account holder in the CLOSED status cannot have funds loaded onto the account or activate cards.
CLOSED users and businesses cannot be reactivated except in exceptional cases depending on your role and the previous status change.
Contact your Marqeta representative for more information.