DOCS

Beta

/

10 minute read

June 4, 2019

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.

Note
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

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

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.

Note
You can also create one or more merchant specific accounts (MSA) for a user or business. An MSA is a special type of account with funds that can only be spent at a defined set of merchants. For more information, contact your Marqeta Customer Success representative.

Cards

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’s account.

Note
An account holder is a distinct concept from a card holder. On the Marqeta platform, a user who owns no cards is still an account holder, but is not a card holder. In other words, all card holders are account holders, but not all account holders are card holders.

For more information, see About Cards.

Spend controls

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

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 both 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. For more information, see 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 card holder 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

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.

Parent-child relationships

If your use case requires it, 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

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.

Note
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

Expense management programs often have multiple business customers, each with their own set of users. The business customer needs to pay for employee expenses, but doesn’t want to manage funding for individual accounts.

Using a parent-child relationship, you can configure the child users 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.

Example parent-child relationship between a parent business and child users

Is this helpful?

To support this configuration, you can create the following parent-child hierarchy:

  • One parent business – This business represents your expense program’s business customer.

  • One or more child users – These users represent the employees of your business customer.

Users vs. businesses

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

The account holder lifecycle

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 /users endpoint.

  • To create a new business, use the /businesses endpoint.

  • To transition a user between statuses, use the /usertransitions endpoint.

  • To transition a business between statuses, use the /businesstransitions endpoint.

The following diagram outlines the possible transitions between statuses.

Possible transitions between account holder states

Is this helpful?

Activation

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

UNVERIFIED

  • Funds cannot be loaded onto the account.

  • Cards owned by a user cannot be activated.

Conditionally

LIMITED

  • Users and businesses must follow rules defined in accountholdergroups.pre_kyc_controls.

Never

ACTIVE

  • None

Suspension and closure

To make a user or business temporarily nonfunctional, 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 nonfunctional, 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 Customer Success representative for more information.

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.