Onboard Consumer Authorized Users

An Authorized User is a person granted access to a primary account holder's financial account. This guide details the complete lifecycle for managing consumer authorized users, from creation to issuing them a payment card and keeping their information updated.

All operations for an authorized user are managed through the USPersonAccountHolder object, which links them to their applications, financial accounts, and payment cards.

Key actions you can perform include:

• Create an Authorized User: Onboard a new user by providing their personal information, such as name, address, and date of birth.
• Create a Card Application: After creating a user, you can apply for a card product on their behalf and link them to a primary financial account.
• Issue a Payment Card: Once an application is approved, you can issue a virtual or physical payment card directly to the authorized user.
• Update User Information: Modify an authorized user's billing address, phone number, or email address as needed.
• Query and Search: Find individual authorized users by their unique ID, search for them using personal data, or look up account relationships to see which users belong to a specific financial account.

Creating an authorized user is the first step in the onboarding process. Call the createUSPersonAccountHolder mutation and provide the user's personal information to generate their profile and unique ID.

After creating a user profile, the next step is to create a card application for them. This mutation links the authorized user to a primary account, which allows them to be issued a payment card.

For enhanced security, especially in client-side applications, you can tokenize an authorized user's personally identifiable information (PII) before creating their profile. This process ensures that sensitive data is never directly handled by your servers. The flow involves generating a client token, using it to tokenize the user's data, and then creating the user from that secure token.

The first step in the tokenization process is to generate a short-lived client token. This token grants temporary permission for a client-side application to securely submit user data for tokenization without having long-term API credentials exposed on the client. No input is required to generate the client token.

With a valid client token from the previous step, you can now exchange the authorized user's personal information for a secure, single-use token. The tokenizeUSPersonAccountHolder mutation takes the user's PII and returns a token that represents this data, which can then be safely passed to your backend.

The final step is to create the authorized user's profile using the secure token. By calling createUSPersonAccountHolderFromToken, your backend can create the user without ever directly handling their sensitive PII, which was exchanged for the token in the previous step.

After an authorized user has been created and their application has been approved, you can issue them a payment card. Depending on your card program's configuration, you have two options:

• Option 1: Issue a card directly from the primary account holder's account or
• Option 2: Issue a card from a dedicated authorized user financial account which requires that you (a) create the account application, then (b) issue the card from the account generated by the application.

Some card programs let you issue an authorized user card directly from the primary financial account, and do not require a dedicated authorized user account.

To issue a payment card to an authorized user from the primary account holder account, call the mutation issuePaymentCardForAuthorizedUserApplication.

Some card programs require a dedicated authorized user account to issue a payment card to an authorized user.

Step 1 is to create a financial account application for the authorized user by calling the mutation issueFinancialAccountForApplication.

Step 2 is to issue a payment card to the authorized use from the new financial account (created above).

Use the issuePaymentCardForFinancialAccount mutation to create a card for the financial account created based on the authorized user application.

You can modify an authorized user's personal information after their profile has been created. The following mutations allow you to update their billing address, phone number, and email address individually. Each mutation requires the user's unique accountHolderId to identify which profile to update.

To update the billing address for a consumer authorized user, call the mutation updateUSPersonAccountHolderBillingAddress.

To update the phone number for a consumer authorized user, call the mutation updateUSPersonAccountHolderPhone.

To update the email address for a consumer authorized user, call the mutation updateUSPersonAccountHolderEmail.

The following four queries let you query authorized by person, or by account.

The first two queries are person-centric, designed to find and retrieve the profiles of authorized users.

• Find authorized user by authorized user ID
• Find authorized user by personal data

The last two queries are account-centric, designed to map the relationships between users and their financial accounts.

• Find financial accounts for authorized user
• Find all authorized users by primary financial account

This query uses USPersonAccountHolder to retrieve a single authorized user's complete profile by using their unique id. The returned information includes personal details such as their name, email, and date of birth, as well as their billing address and phone number. It also fetches the status of any card products they have applied for.

This query uses USPersonAccountHolder to search for authorized users by filtering on specific personal information, such as their name and date of birth. It returns a paginated list of all users who match the search criteria. For each user found, the query provides a detailed profile that includes their personal data, contact information, and the status of their applications.

This query retrieves all the financial accounts associated with a single authorized user by using that person's account holder id as the input. The results include a list of financial accounts, with details on account status, enabled features (like DirectDeposit), and ledger balances. This is used to see all the accounts a person is authorized to use.

This query identifies all authorized users linked to a specific primary financial account by using the account's id. It returns a list of the associated authorized user financial accounts, including details about their status, features, payment cards, and ledger balances. This is useful for retrieving all authorized users on a single primary account.