About Accounts

This guide explains how accounts are structured in the Galileo system and which account types are relevant to the API consumer. This guide does not explain the many account characteristics that a program or product may support.

Galileo uses the term "account" in two senses:

  • "Account" or "customer account" — A record in a database that corresponds to a customer and product
  • "Bank account" — A financial account at a bank, where customer funds reside

Account types

When working with the Program API you generally do not need to deal with account types by their banking functions such as brokerage, savings, or debit. Those account properties are set at the program and product levels.

In the Galileo system an account can be either a primary account or a secondary account. The purpose of creating secondary accounts is to create relationships between accounts in the Galileo system. In most cases, the related accounts all belong to the same customer, although the secondaries can also belong to someone who is related to the primary customer in some way, such as the child or spouse of the customer, or the secondaries can link business-to-business accounts.

It is up to you whether to use the primary/secondary linkage inside the Galileo system or whether to use your own logic to set up relationships among accounts. If you use the primary/secondary linkage in the Galileo system the following will be true:

  • Account balances can be shared between a primary account and its secondary accounts.
  • The CSTCST - Customer Service Tool. Software that the Galileo customer service team uses, which is also available to providers, to view customers and their accounts. shows which accounts are related.
  • You can easily link naturally related accounts such as a DDADDA - Demand deposit account. The banking-industry term for an account from which funds can be withdrawn at any time, such as a checking account. and its overdraft account.
  • Galileo sets up and maintains the primary product parameters to indicate which products can be its secondaries, and also how many secondaries a primary account can have.
  • During customer onboarding the primary account must be created first, then the secondaries later.

Primary accounts

A primary account is the first account you create when onboarding a new customer. You must use either the Create Account or Create Virtual Card Account endpoint to create a primary account, because those endpoints include parameters for the customer's name, address, and other personal information that are in the customer record.

Secondary accounts

Secondary accounts represent additional products that a customer wishes to acquire. You can use the Create Account, Create Virtual Card Account, or Add Account endpoints to create a secondary account. You pass the primary account number to enable secondary account creation, either as the primaryAccount (Create Account and Create Virtual Card Account endpoints) or accountNo (Add Account endpoint).

Things to keep in mind about secondary accounts:

  • Secondary account numbers can never be passed for the primaryAccount parameter.
  • The technical limit on the number of secondary accounts that can be associated with a primary account is 9999; however, you may set a lower limit at the product level.
  • A secondary account can belong to the same customer or it can belong to a different customer than the primary customer.
  • Product settings may dictate that a minor child meet a minimum age requirement to obtain a secondary account.

📘

Note

Although there is no flag in the Galileo system to specifically mark primary and secondary accounts, you can view the relationships in the CST and RDFRDF - Raw data file. Once per day Galileo sends you RDFs that contain a list of all of your previous day's transactions and all of your current customers. Compare the RDFs with your own records and if there are discrepancies, treat the RDFs as authoritative.s.

Primary and secondary account scenarios

These example scenarios demonstrate some of the ways to set up primary and secondary accounts. For more use cases see Create Account vs Add Account.

One customer with multiple secondary accounts

In this scenario a provider offers these products: a DDA with a card, an overdraft account, and a savings account.

  1. A new customer, Leona Alvarez, signs up for a DDA. This account is created with the Create Account endpoint, which generates a card. This is the customer's primary account.
  2. The provider offers an automatic overdraft account for the DDA. This account is created with the Add Account endpoint, and specifying the DDA as the primary account.
  3. Leona also wants a savings account where she can automatically deposit funds from her DDA every month. This account is created with the Add Account endpoint, specifying the DDA as the primary account. This is another secondary account.

This is the end result of the above steps:

Two customers with the same primary account

In this scenario the provider offers three products: Product A, Product B, and Product A1, which is a version of Product A that is intended for teenaged customers.

  1. A new customer, Adele Johnson, signs up for Product A. This account is created with the Create Account endpoint, which generates a card.
  2. Adele also wants Product B, so the Add Account endpoint is called to create a secondary account.
  3. Adele wants Product A1 for her son Andy, and she wants Andy's account associated with hers. Create Account is called with Andy's personal information, and Adele's primary account number is provided to associate the two accounts.

This is the end result of the above steps:

📘

Note

Do not confuse primary and secondary accounts with primary and secondary products. At the time program managers set up a product they have the option of creating a secondary product with a separate product ID. The secondary product usually has lesser features compared to the primary product—such as a lower spending velocity—and is intended for minors to use.

Accounts for minors

If your program settings permit it, non-adult (under 18) customers can obtain secondary products. Use your product parameters to specify the youngest age for eligible customers. Where a minimum age is specified, the dateOfBirth parameter is required to ensure that the minor is eligible for the product.

Account identifiers

In the Galileo system you will encounter several types of account identifiers:

PRN

The payment reference number is a unique, 12-digit Galileo-generated account identifier. Galileo recommends that you use this number to identify accounts, instead of card numbers or customer IDs, because a customer's SSN or a card's PAN can change but a PRN never does. A permanent identifier prevents maintenance headaches when the other identifiers change.

The PRN is also the number that customers provide to their banks when setting up ACHACH - Automated clearing house. A method of transferring funds from one bank to another, maintained by the U.S. Federal Reserve. The transfers are processed in batches, and it can take up to 72 hours for a transaction to clear a bank. The ACH is separate from card networks and Galileo processing. accounts or bill payments.

PAN

The primary account number is the number that is displayed on a card. See Card Identifiers in the About Cards guide.

Galileo account number

Also called the "balance ID," the Galileo account number is an identifier that points to the bank account that the product transacts on.

External account ID

An external account ID is a number you provide that can be used for your own purposes. Some examples uses of this value are:

  • Mapping the customer to your back-end systems
  • Communicating with the embosser to specify which art to use on the card

The externalAccountId parameter is passed in the Create Account and Create Virtual Card Account endpoints. You can retrieve the external account number with the Verify Account endpoint and edit it with the Update Account endpoint.

Do not pass this number for primaryAccount or accountNo.

ACH account number

An ACH account is a customer's external bank account that can be used for such transactions as bill payment or to deposit funds into an account. An ACH account is set up using the Add ACH Account endpoint. See About ACH for more information.

Account identifiers in the Galileo system

Consult this table to see how account identifiers are represented across the Galileo system.

Galileo systemPRNGalileo account numberExternal account IDACH account number
Auth APIprnn/an/an/a
Events APIprnbalance_idn/an/a
External Trans APIaccount_number

prn
n/an/an/a
Program API requestsaccountNo

primaryAccount
n/aexternalAccountIdachAccountNo
Program API responsespmt_ref_nogalileo_account_no

bal_id
external_account_idach_account_id
RDFsPRNGALILEO ACCOUNT IDEXTERNAL ACCOUNT NUMBERn/a

Virtual card accounts

A virtual card exists only on a customer's mobile device, on the web, or in an email: it is not issued as a physical card. See the Digital Cards guide for information on setting up virtual card accounts.

Account status

An account's status is designated by a single capital letter in the Galileo system. See the Account Statuses enumeration.

📘

Note

Account status is not the same as card status. The statuses may be similar in some cases, but they operate independently. See the Card Statuses enumeration.

When an account is first created, it is in status: W (waiting to be processed). The Galileo system then runs an account-setup process, a cron job that runs every 5–30 minutes, depending on your product settings. When successful, the account is put into its next state, according to your product parameters. Most virtual cards and Digital First cards are put into status: N (active).A physical card would be moved into status: X (waiting for emboss).

To change an account status use the Modify Account or Card Status endpoint, which requires an integer to designate the type of change to make. Consult the Account and Card Status table in the Modify Account or Card Status reference for a list of numbers and their corresponding types of status change.

Also see Lost, Stolen, or Damaged Cards.

Account features

Most of an account's features are set at the product level; however, a few features can be set or modified at the account level, such as allowing international transactions or sending paper statements. To set or change these features use the Set Account Feature endpoint. Defaults for these features can also be set at a product level. Contact Galileo for assistance.

New account creation

When you create a new account for a customer—using either the Create Account endpoint or the Create Virtual Card Account endpoint—the Galileo system creates an customer record and a corresponding account object. See the Creating an Account procedure for instructions on using the Create Account and Create Virtual Card Account endpoints. A customer record may be associated with multiple account objects.

Customer record

  • Customer name
  • Customer billing address
  • Customer shipping address
  • Phone numbers
  • Date of birth
  • Email address
  • Identifiers such as SSN or driver license number
  • Occupation and income source

Account object

  • PRN — Payment reference number. A Galileo-generated account identifier that is unique across the Galileo system.
  • Status — The account status. See the Account Statuses enumeration.
  • Balance — The amount of funds present in the account that is available to spend.
  • Balance ID — An identifier that corresponds to the bank account where customer funds reside.
  • Application date — The date the customer is first onboarded to the Galileo system.
  • Currency code — The denomination of the funds, such as U.S. dollar or Mexican peso.
  • Routing number — The identifier for the bank where the account's funds reside.
  • Product ID — The identifier for the specific offering of a program.
  • Customer record — The information in the customer record.
  • Savings interest object — Where applicable, the amount of interested accrued.
  • Transactions — List of settled transactions made on the account.
  • Authorizations — List of pending authorizations for the account.
  • Pending fees — List of fees to be charged to the account.
  • Holds — List of holds for the account.

Card object

See The card object in the About Cards guide.

Depositing funds into accounts

According to your product settings you have the option of depositing funds into an account at the time that you create the account or of depositing funds into the account later. Customers can also deposit funds into their accounts if your product settings permit it.

Consult this table to see how to use the endpoints for each use case.

Use caseEndpointParameters
You deposit funds into an account at the time of account creationCreate AccountloadAmount — Must be within the limits in your product settings

loadType — Valid values arranged with Galileo

loadFromAccountNo — Use only if you have created an account within the program for depositing funds into customer accounts; otherwise, the funds come from the account you have set up with Galileo for that purpose
You deposit funds into the account at a time other than account creation, using the account you have set up with Galileo for depositing funds into customer accountsCreate PaymentaccountNo — Account to receive the deposit

type — Valid values arranged with Galileo
You deposit funds into the account at a time other than account creation, using an account within your program for depositing funds into customer accountsCreate Account TransferaccountNo — Account to transfer funds from

type — Valid values arranged with Galileo

transferToAccountNo — Account to receive the deposit
The customer deposits funds into their account from an external bank accountCreate ACH TransactionaccountNo — Account to receive the deposit

achAccountId — The ACH account to draw from

debitCreditIndicatorD to move funds from the ACH account to the customer account
The customer deposits funds into their account from another account that they have with youCreate Account TransferaccountNo — Account to transfer funds from

transferToAccountNo — Account to receive the deposit

Joint accounts and shared balances

It is not currently possible to set up true joint accounts in the Galileo system, wherein one account has multiple account holders. Instead, you can use the shared balance feature. A shared balance is a bank account that multiple products (accounts) can transact on. The accounts can belong to the same customer or to different customers.

With shared balances you can support scenarios such as these:

  • A customer wants multiple products from the same provider and wants all of those accounts to transact on the same bank account.
  • A parent wants a separate card for a child, and both the parent and child will transact on the same bank account.
  • A customer wants to add a virtual card to share the same bank account as their physical card.
  • Two spouses want the same product, and want both product accounts to transact on the same bank account.

There is no technical limit to the number of accounts that can share a balance; however, product settings may limit the number of secondary accounts or secondary products a primary account can have.

A secondary account can share a balance only with the specified primary account. Secondary accounts cannot directly share balances with each other.

👍

Warning

Once you share a balance between accounts, you cannot "unshare" the balance. Instead, you would have to close the accounts and create new ones without shared balances. Likewise, you cannot share balances after the accounts have already been created.

Shared balances scenarios

The following scenarios demonstrate some of the ways to set up shared balances.

One customer, two products

In this scenario, an existing customer wants another product and would like the second product to transact on the same bank account as the first product.

For this scenario, call the Create Account endpoint to create the customer's first account (primary account), and then call the Add Account endpoint to create the secondary account. In the Add Account request pass the customer's primary account number for accountNo and set sharedBalance: 1.

This is the relationship that is set up:

Two customers, one product

In this scenario an existing customer wants to add an account for a different person, and both accounts will transact on the same account balance. In this example, a parent provides a child with a secondary product that is linked to the parent's account.

For this scenario, call the Create Account endpoint to create the first customer's account (primary account), and then for the second customer call Create Account again with these parameters:

  • The second customer's name and personal information
  • The secondary product ID that corresponds to the first customer's product
  • The first customer's primary account number for accountNo
  • sharedBalance: 1

This is the relationship that is set up:

Getting related account information

When two or more accounts share a balance, you can pass includeRelated: 1 with some of the endpoints to retrieve information for all accounts that share the same balance. For example, with the Get Transaction History endpoint you can pass a secondary account number for accountNo and includeRelated: 1 to retrieve data on all accounts with the same balance ID. If accountNo: 333, as in the above example, data for both Simón Ramírez and Simón Ramírez Jr.'s accounts are returned, because they share the same balance ID. If includeRelated: 0, only information for account 333 is returned. If you pass a primary account number for accountNo, by default all accounts with the same balance ID are returned.

Create Account vs Add Account

Whether to use the Create Account endpoint (or Create Virtual Card Account endpoint) instead of Add Account is determined by whether the customer already exists in the Galileo system and whether you want to deposit funds into the account at account creation time:

  • Create an account to onboard new customers for a spending account (account with a card), including a new customer who will be associated with an existing customer as the owner of a secondary account.
  • Add an account to an existing customer who wants additional products such as savings or overdraft accounts. You cannot use Add Account to deposit funds into the account, nor does it run CIPCIP - Customer identification program. In the United States, financial entities that want to engage in financial transactions with a potential customer must have a CIP to ensure that potential customers are not on terrorist watch lists. This provision of the Patriot Act is designed to increase security and guard against money-laundering. Galileo sometimes uses this term to encompass CIP and Know Your Customer (KYC)..

Create Account and Add Account use cases

Use caseEndpointParameters
Onboard a new customerCreate AccountprimaryAccount — Do not populate

prodId — Can be a physical or virtual card product

sharedBalance — Do not populate.
Add a secondary account (another product) to an existing customer but do not create a card or deposit funds into the account.Add AccountaccountNo — Primary account of existing customer

prodId — Can be a physical or virtual product; must be permitted by the primary account product settings

sharedBalance — (Optional) 1 to share the balance with the primary account; otherwise, set to 0 or do not populate
Add a secondary account to an existing customer and deposit funds into the accountCreate AccountprimaryAccount — Primary account of existing customer

prodId — Can be a physical or virtual account; must be permitted by the primary account product settings; must be a spending account

loadAmount — Required

loadType — Required

sharedBalance — Required. 1 to share the balance with the primary account; otherwise, set to 0.
Add an account for a dependent minor (under 18) to a parent's account, with shared balanceCreate AccountprimaryAccount — Parent's primary account

prodId — Secondary product ID; must be permitted by the primary account product settings

sharedBalance — Required. 1 to share the balance with the primary account

cipStatus2 if you are using Galileo's CIP; otherwise, do not populate

dateOfBirth — Required if product settings have a minimum age
Add an account for a child to a parent's account, without shared balanceCreate AccountprimaryAccount — Parent's primary account

prodId — Secondary product ID

sharedBalance — Required. Set to 0

cipStatus2 if you are using Galileo's CIP; otherwise, do not populate

dateOfBirth — Required if product settings have a minimum age
Onboard a new customer who will be sharing a balance with an existing customer's accountCreate AccountprimaryAccount — Primary account of existing customer

sharedBalance1
Create a virtual card account for a new customer (You must be PCI compliant to use this endpoint.)Create Virtual Card AccountprimaryAccount — Do not populate

prodId — Must be a virtual product
Add a virtual card account to an existing customer and deposit funds into the account (You must be PCI compliant to use this endpoint.)Create Virtual Card AccountprimaryAccount — Primary account of existing customer

prodId — Must be a virtual product

loadAmount — Required

loadType — Required

sharedBalance — Required. Pass 1 to share the balance with the primary account; otherwise, set to 0.

Retrieving account information

Use these endpoints to retrieve the desired account information. To get individual types of transactions, see Specialized transaction lists in the Transaction History guide.

Use these endpoints to retrieve the desired account information.

Column header key

AttributeABCDEFGH
PRNXXX
BalanceXXXX
Currency codeX
StatusXXX
Product IDX
Galileo account no. (balance ID)X
Merchant category codeX
Application dateX
Customer recordX
Transaction countX
Transactions (list)X
Authorization countX
Authorizations (list)X
Pending fees (list)X
Savings interest objectXX
Account features (array)X
Max load amountX
External account IDX
Overdraft balance (array)X
Customer notes (array)X

ACH accounts

An ACHACH - Automated clearing house. A method of transferring funds from one bank to another, maintained by the U.S. Federal Reserve. The transfers are processed in batches, and it can take up to 72 hours for a transaction to clear a bank. The ACH is separate from card networks and Galileo processing. account is a record in the Galileo system that corresponds to a customer's external bank account. Customers use ACH accounts to deposit funds into their accounts or to pay bills.

See the About ACH guide for further information.

Modifying account information

After you have created a new account you can modify customer record attributes using the Update Account endpoint. When sending the Update Account call you pass only the parameters to be modified. Parameters that are not being modified can be left blank. Do not pass null unless you want to set the parameter's value to null.

📘

Note

According to the settings in your product parameters, some customer record information may not be modifiable.

You can input either a primary or secondary account number to change the associated customer record attributes.

Closing accounts

Because the Galileo system is an official system of record, it is not possible to delete an account from the Galileo system. Legal requirements specify that all activity, including account creation, be stored for a period of several years for auditing purposes.

However, an account may be closed, which prevents further transactions from being made on it and deactivates any cards associated with it.

Your product settings determine some of the events that trigger an account closing, such as an account having zero or negative balance for a specified period. Other events such as a stolen or lost card can result in a closed account. (See Lost, Stolen, or Damaged Cards.)

Your product settings also determine which procedures must be followed when an account is closed, such as whether to send a check for the remaining balance or whether the cardholder must return the card before receiving a check.

This table shows some of the states that can represent a closed or unusable account and the type parameter in the Modify Account or Card Status endpoint that moves the account to that status. See the Account and Card Status table in the Modify Account or Card Status reference for all Modify Status types. Follow your business plan to decide when to use these Modify Status types. Also see Cancelling cards in the About Cards guide.

📘

Note

A card that is in status: Z cannot be modified, but an account in status: Z can.

Use caseTypeAccount statusNotes
Close the account2CChanges the account to status: C but does not change the status of associated cards. When the account is closed the cards cannot be used.
Deactivate account and cancel cards13CChanges both the account and associated cards to status: C.

Also closes any related savings accounts.
Deactivate account and cards16ZChanges both the account and associated cards to status: Z.

Does not affect related secondary accounts.
Cancel without refund all accounts and cards for a customer and all related accounts and cards20ZChanges both the account and associated cards to status: Z.

Affects all accounts and cards of the customer, including secondaries.
Disable account and active cards23DChanges both the account and associated cards to status: D.

Does not affect related secondary accounts.

Reversing an account creation

If you have created an account in error, follow these steps:

  1. Optional. Call Update Account to set the id and id2 values to null, so that the customer can attempt to join again.
  2. Call Modify Account or Card Status with type: 2 to cancel the account.

Alternatively, you can use the Customer Service Tool to reverse out an account creation.


Did this page help you?