Adding an Account

This guide describes the procedure for creating a secondary account using the Add Account endpoint. With this endpoint you can add a secondary account to an existing account holder without running CIP on that account holder.

Follow this procedure to:

  • Add a secondary account to an existing account holder, such as a savings or overdraft account. For overdraft accounts, also consult the Creating an Overdraft Account guide.
  • Add a secondary card product to an existing account holder, either a virtual or personalized card

Do not follow this procedure to:

  • Onboard a new customer for a physical or virtual card; instead, see the Creating an Account guide.
  • Deposit funds into an account at the time of account creation; instead, see the Creating an Account guide.
  • Create a secondary account for a different customer than the primary account holder, such as a spouse or child; instead, see the Creating an Account guide.

📘

Note

Before following this procedure read the About Accounts guide to familiarize yourself with Galileo's account structure and conventions, especially the Create Account vs Add Account use cases.

Result of calling Add Account

When Add Account has been called successfully, these items are created or updated in the Galileo system. See New account creation in the About Accounts guide for details.

  • Customer record — Referenced from the customer record of the primary account. However, the customer ID and ID type fields are not referenced, because Add Account does not perform CIP.
  • Account record — Contains general account information.
  • Card record (for card products) — Contains card information. You can receive unmasked PAN/CVV/expiry date values only if you are PCI compliant.

Relationship to primary account

Accounts that are added with the Add Account endpoint are associated with the primary account such that the primary account holder is also the secondary account holder. At the time you call this endpoint you must decide whether to share the balance with the primary account. You cannot share or unshare balances after the secondary account has been created. See Joint accounts and shared balances in the About Accounts guide for more information.

Additional product, separate balances

In this scenario the secondary account does not share a balance with the primary account.

To create this scenario, follow these steps:

  1. Call the Create Account endpoint to create the customer's first account (primary account).
  2. Call the Add Account endpoint to create the secondary account. In the request to the Add Account endpoint pass these parameters:
    • accountNo: primary account number
    • sharedBalance: 0 or leave blank

This is the relationship that is set up:

751751

Additional product, shared balance

In this scenario the secondary account shares a balance with the primary account.

751751

To create this scenario, follow these steps:

  1. Call the Create Account endpoint to create the first customer's account (primary account).
  2. Call the Add Account endpoint to create the secondary account. In the request to the Add Account endpoint pass these parameters:
    • accountNo: primary account number
    • sharedBalance: 1

Parameters

This table explains the parameters that are specific to the Add Account endpoint. See the Add Account reference for details.

ParameterUsage
accountNoThe primary account to associate with this secondary account. This can be a primary account number or a secondary account number.
prodIdIdentifier for the product. Product parameters must permit this product to be a secondary account to the product of the account specified in accountNo.
sharedBalancePass 1 when creating a secondary account that will transact on the same balance as the specified accountNo; otherwise, do not populate.

📘

Note

If you want to add an external account ID to an account created with addAccount, call updateAccount and populate externalAccountId.

Add Account workflow

Consult this flowchart and explanation for the Add Account workflow. The actual sequence of events in the Galileo system may vary.

📘

Note

Before calling Add Account, you must have already performed the Creating an Account procedure to onboard the customer.

757757
  1. Populate the Add Account request and send.
  2. Galileo performs a number of preliminary checks. Failures return the status codes shown in the diagram. Consult the Status codes table for next steps.
  3. Galileo references the account holder profile information and creates a new account with status: W (waiting to be processed).
    • If sharedBalance: 1 the balance ID is set to the primary account balance ID.
    • If sharedBalance: 0 the balance ID is unique.
  4. If the account cannot be created Galileo returns status: -1.
  5. If account creation was successful, Galileo sends two messages:
    • API response with status: 0 (successful)
    • Account Event CAPP: app_completed, if you are configured to receive it.
  6. Galileo runs an account setup process to determine whether other criteria for the account have been fulfilled, according to product settings. When all criteria are fulfilled, the Galileo system checks the XAACT product parameter for how to set the account status:
  • First character — Account active/inactive (Y/N)
  • Second characterAccount status
  • Third characterCard status (if any)
    For example, if the product is a card account, and XAACT is YNX, then when account setup is completed these are the settings:
  • Account active: Y
  • Account status: N (active)
  • Card status: X (set to emboss)
    See Lifecycle of a card in Setting Up a Card Program for the next steps when the account has a card.

Sample endpoint request and response

Consult the Add Account reference to see how to build the API request and to see the response schema.

Status codes

Consult this table to see an explanation of what each status code means and which next steps to take, if any.

Status CodeDescriptionNext steps
456-01Product cannot be added using the Add Account endpoint.Retry with a supported product ID.
456-02Your product settings require a customer to have a specified amount in their primary account to add this product.Notify customer that their primary account funds are insufficient for adding this product.
456-03Your product settings do not permit a customer to have multiple accounts for the same product.Notify customer that they cannot have multiple accounts for this product.
456-04Your product settings do not permit this savings account to be added.Notify customer that this product cannot be added.
456-05Your product settings do not permit the primary account to have this product as a secondary account.Retry with a valid primary account, or notify the customer that this account is ineligible, or verify that your product settings are correct.

View the new account

Use the Get Account Overview endpoint to retrieve account status and other information. Consult Retrieving account information in About Accounts for a list of endpoints and the specific account information they retrieve.