Onboard Authorized Users

Highnote released a simplified model for Authorized Users that applies to both consumer and commercial card products. Going forward, all authorized users are Person account holder objects, even commercial products where the primary account holder is a Business account holder object.

An authorized user of a card product is a person who is granted access to the financial account of the primary account holder. Authorized user operations are managed through the USPersonAccountHolder object, which links them to their applications, financial accounts, and payment cards.

To onboard a consumer authorized user:

1. Create an authorized user securely with a token (or if necessary without token): Onboard a new user by providing their personal information, such as name, address, and date of birth.
2. Create a card application for the authorized user: Apply for a card product on their behalf and link them to a primary financial account.
3. Issue a payment card to the authorized user: Issue a virtual or physical payment card directly to the approved authorized user. You have two options: (a) issue the card from the primary financial account, or (b) create an authorized user financial account and issue from that.

Creating an authorized user is the first step in the onboarding process.

You can create authorized users with or without tokenizing, but Highnote highly recommends tokenization for enhanced security, especially in client-side applications. Tokenizing ensures that sensitive data is never directly handled by your servers.

This set of mutations let you tokenize an authorized user's personally identifiable information (PII) before creating their profile. 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.

Highnote recommends that you use the more secure process of creating authorized users with tokenization.

To create an authorized user without tokenization, call the following 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.

Note: Set financialAccountId to the ID of the primary account holder's financial account.

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.

Note: Set applicationId to the ID of the application you submitted in Step 2. This application in Step 2 is tied to the financialAccountId of the primary account holder.

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

First, create a financial account application for the authorized user by calling the mutation issueFinancialAccountForApplication.

Note: Just as with Option 1, set applicationId to the ID of the application you submitted in Step 2, because it is tied to the financialAccountId of the primary account holder. The difference is that rather than issuing a card as you did in Option 1, here, you are applying to create a financial account for the authorized user from which you can issue a card in the next step.

Next, 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.

Note: Set financialAccountId to the ID of the financial account you created for this authorized user (in Option 2a).

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 an authorized user, call the mutation updateUSPersonAccountHolderBillingAddress.

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

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

The following four queries let you find authorized users 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.