Log into Pro Sandbox

This guide describes the procedure for creating a new customer account using the <a href="ref:post_createaccount" target="_blank">Create Account</a> endpoint or <a href="ref:post_createvirtualcard" target="_blank">Create Virtual Card Account</a> endpoint. With these endpoints you can optionally issue a card and deposit funds into the account at the same time that you create the new account.

Note

When creating an account for a new customer you must perform <<glossary:KYC>> and <<glossary:CIP>>. Consult the <a href="doc:customer-id-verification" target="_blank">Customer ID Verification (KYC/CIP)</a> guide for instructions. You should also read the <a href="doc:about-accounts" target="_blank">About Accounts</a> guide to familiarize yourself with Galileo's account structure and conventions.

Follow this procedure to:

  • Onboard a new customer for a physical card.

  • Onboard a new customer for a virtual card.

  • Create a secondary account for a different customer than the primary account holder, such as a spouse or child.

Do not follow this procedure to:

  • Add a secondary account to an existing customer; instead, see the <a href="doc:add-account-procedure" target="_blank">Adding an Account</a> guide.

  • Add an overdraft account; instead, see the <a href="doc:creating-an-overdraft-account" target="_blank">Creating an Overdraft Account</a> guide.

  • Create an <<glossary:instant-issue card>>; instead, see <a href="doc:setup-for-instant-issue" target="_blank">Setup for Instant Issue</a>.

  • Create an account for a Digital First account, where you provide a digital version of the card for customers to use while the physical card arrives; instead, consult <a href="choose-a-card-strategy#digital-first-cards" target="_blank">Digital First cards</a> in the _Choose a Card Strategy_ guide.

  • Break out the account-creation steps into component parts, such as passing Galileo <<glossary:CIP>> before creating an account; instead, use <a href="ref:post_startenrollment" target="_blank">Start Enrollment</a> and <a href="ref:post_completeenrollment" target="_blank">Complete Enrollment</a>. For directions see <a href="doc:customer-id-verification#start-enrollment-process" target="_blank">Start Enrollment process</a> in _Customer ID Verification (KYC/CIP)_.

## Result of calling Create Account or Create Virtual Card Account

When Create Account or Create Virtual Card Account has run successfully, these new items are created in the Galileo system. See <a href="doc:about-accounts#new-account-creation" target="_blank">New account creation</a> in the _About Accounts_ guide for details.

  • **Customer record** — Contains the customer's personal data such as address, date of birth, and contact information.

  • **Account record** — Contains general account information.

  • **Card record** (for card products) — Contains card information. You can receive unmasked <<glossary:PAN>>/<<glossary:CVV>>/<<glossary:expiry date>> values only if you are <<glossary:PCI>> compliant.

## Parameters

This table explains the parameters that are specific to the Create Account and Create Virtual Card Account endpoints. See the <a href="doc:post_createaccount" target="_blank">Create Account</a> or the <a href="doc:post_createvirtualcard" target="_blank">Create Virtual Card Account</a> reference for details.

ParameterUsage
`accountNo`Populate only for instant-issue cards. For all others leave blank.
`id`**Required for Galileo CIP**. Primary ID number. See <a href="doc:customer-id-verification#using-the-id-and-idtype-parameters" target="_blank">Using the **id** and **idType** parameters</a> for instructions. If you are not using Galileo CIP you may still populate these ID fields for your own records.
`idType`**Required for Galileo CIP**. Required when `id` is populated. Primary ID type. Your product settings might require `idType: 2` (SSN) for the primary ID. See the <a href="ref:api-reference-customer-id-types" target="_blank">Customer ID Types</a> enumeration for valid values.
`id2`Optional or required for Galileo CIP, depending on your product settings. Secondary ID number.
`idType2`Required when `id2` is populated. Secondary ID type.
`locationType`Do not populate.
`location`Do not populate.
`locale`Customer localization preferences. If the customer address is outside the U.S., pass a non-`_US` value for this parameter to disable U.S. address validation.
Customer profile parameters**Required for Galileo CIP and for the customer record**. <li>For <a href="doc:customer-id-verification" target="_blank">customer ID verification</a> you must include the name parameters, the address parameters, and the date of birth.<li>The `mobilePhone` parameter is required for provisioning cards to mobile wallets. You must also populate `mobilePhoneCountryCode` if you pass any phone parameters.
`webUid`Do not populate.
`webPwd`Do not populate.
`secretQuestion`Do not populate.
`secretAnswer`Do not populate.
`incomeSource`_Create Account only._ The name of the customer's employer or income source.
`occupation`_Create Account only._ Job title of the customer.
`prodId`The identifier for the product the customer is signing up for. Galileo generates a unique product ID for each of your products.
`loadAmount`Populate only if the product is configured to deposit funds into the account at creation time.
`loadType`**Required when passing `loadAmount`**; valid values are created in cooperation with Galileo.
`externalAccountId`This field is for your own purposes. Galileo stores but does not process this parameter; however, it can be updated with the <a href="ref:post_updateaccount" target="_blank">Update Account</a> endpoint (active accounts only), you can retrieve it using the <a href="ref:post_verifyaccount" target="_blank">Verify Account</a> endpoint, and it is provided in the <<glossary:RDF>>s. You can use this parameter in cooperation with your card embosser to dynamically select card art, or you can input customer identifiers for your own back-end systems.
`primaryAccount`Populate only when creating a secondary account.
`sharedBalance`**Required when passing `primaryAccount`**. Pass `1` when creating a secondary account that will transact on the same balance as the `primaryAccount`. Pass `0` if the account balances will not be shared.
`userData`This field is for your own purposes. Galileo does not process this parameter and it cannot be updated using the Update Account endpoint. You might want to use this field to track internal groups or advertising campaigns or for other similar purposes.
`offline`Do not populate.
`verifyOnly`Pass `1` to verify the parameter values in your API request without creating an account or running CIP.
`cipStatus`Populate only when using Galileo CIP. See <a href="doc:customer-id-verification#overriding-your-id-verification-setting" target="_blank">Overriding your ID verification setting</a> for more information.
`embossLine2`A second line to be printed under the name on the card.
`providerAssessedFee`Do not populate.
`loadFromAccountNo`For depositing funds into the new account from another account in the same program. You must also pass `loadAmount` and `loadType` when populating this parameter.
`sweepDate`Do not populate.
`expressMail`_Create Account only_. Populate to ship the card via accelerated delivery. Valid values come from your emboss vendor.
`shipToAddressPermanent`_Create Account only_. Pass `1` to make the ship-to address information permanent, meaning that you don't have to provide a new ship-to address every time you send a new card to the embosser.
`shipTo` parameters_Create Account only_. Populate for physical cards, when the shipping address is different from the primary address.
`businessName`**Required** when `prodId` is a business account. See <a href="ref:api-reference-special-characters#businessname-parameter" target="_blank">`businessName` parameter</a> for the validation rules.
`mobilePhoneCountryCode`**Required** when any of the phone parameters are populated. This value determines <a href="ref:api-reference-phone-validation" target="_blank">how the phone numbers are validated</a>

## Account-creation workflow

Consult these flowcharts and explanations for the <a href="ref:post_createaccount" target="_blank">Create Account</a> and <a href="ref:post_createvirtualcard" target="_blank">Create Virtual Card Account</a> endpoint workflows: the first when using your own CIP and the second when using Galileo's CIP.

Note

Call the Create Account or the Create Virtual Card Account endpoint only once per customer when onboarding. Because these endpoints create a customer record, it is important that only one record be created per customer.

### Create Account using your own CIP

This flowchart shows the logical progression of the <a href="ref:post_createaccount" target="_blank">Create Account</a> endpoint and subsequent backend processes when not using Galileo's CIP. This diagram is also valid for the <a href="ref:post_createvirtualcard" target="_blank">Create Virtual Card Account</a> endpoint. The actual sequence of events in the Galileo system may vary.

Note

The <a href="ref:account-events-webhook" target="_blank">Account Events</a> messages are sent to you according to the arrangements you have made with Galileo.

887


<!--createAccount-client-CIP.png-->

  1. Retrieve customer information from your web page or mobile app.

  2. Send the customer information to your third-party CIP provider.

  3. When CIP is successful, populate the <a href="ref:post_createaccount" target="_blank">Create Account</a> request with that information and send.

  4. Galileo performs a number of preliminary checks. Failures return the status codes shown in the diagram. Consult the [Status codes](🔗) table for next steps.

  5. Galileo creates an account with `status: W` (Waiting to Be Processed). If the account cannot be created the endpoint returns `status_code: 407-05`.

  6. According to product settings, Galileo creates a card object and deposits funds into the account. The account that receives the funds is identified by the balance ID, also called "Galileo account number." If depositing funds is not successful, the status codes shown in the diagram are returned. Consult the [Status codes](🔗) table for next steps. The card object contains the <<glossary:PAN>>, the <<glossary:expiry date>>, and the <<glossary:CVV>>. The full contents of this object are returned to you in the API response only if you are <<glossary:PCI>> compliant.

  7. If all processes have been successful, Galileo sends two messages:

    • API response with `status_code: 0` (successful)

    • Account Events webhook <a href="ref:api-reference-events-api-app-completed" target="_blank">`CAPP: app_completed`</a>.

  8. 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 character** — <a href="ref:api-reference-account-statuses" target="_blank">Account status</a>

    • **Third character** — <a href="ref:api-reference-card-statuses" target="_blank">Card status</a> (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 <a href="doc:setting-up-a-card-program#lifecycle-of-a-card" target="_blank">Lifecycle of a card</a> in _Setting Up a Card Program_ for the next steps when the account has a card.

### Create Account using Galileo CIP

This flowchart shows the logical progression of the <a href="ref:post_createaccount" target="_blank">Create Account</a> endpoint and subsequent backend processes when using Galileo's integrated CIP. This diagram is also valid for the <a href="ref:post_createvirtualcard" target="_blank">Create Virtual Card Account</a> endpoint. The actual sequence of events in the Galileo system may vary.



<!--createAccount-Galileo-CIP,png-->

  1. Retrieve customer information from your web page or mobile app.

  2. Populate the <a href="ref:post_createaccount" target="_blank">Create Account</a> request with that information and send.

  3. Galileo performs a number of preliminary checks. Failures return the status codes shown in the diagram. Consult the [Status codes](🔗) table for next steps.

  4. Galileo sends the customer information to its CIP provider.

  5. Galileo creates the customer account with `status: W` (Waiting to Be Processed).

  6. According to product settings, Galileo creates a card object and deposits funds into the account. The account that receives the funds is identified by the balance ID, also called "Galileo account number." If depositing funds is not successful, the status codes shown in the diagram are returned. Consult the [Status codes](🔗) table for next steps. The card object contains the <<glossary:PAN>>, the <<glossary:expiry date>>, and the <<glossary:CVV>>. The full contents of this object are returned to you in the API response only if you are <<glossary:PCI>> compliant.

  7. Galileo verifies whether CIP was successful:

    • If CIP was successful, Galileo sends you two messages:

      • API response with `status_code: 0` (successful).

      • Account Events webhook <a href="ref:api-reference-events-api-app-completed" target="_blank">`CAPP: app_completed`</a>.

    • If CIP was not successful, Galileo sends two messages:

      • API response with `status_code: 407-11` (CIP failed) with the `R`, `F` or `S` verdict in the `cip` field.

      • Account Events webhook <a href="ref:api-reference-events-api-fail-id" target="_blank">`FTID: fail_id`</a>.

  8. Galileo launches an account setup process, which verifies whether all criteria for account creation have been fulfilled. If CIP was not successful Galileo moves the account to `status: F` (failed CIP). You take your next steps according to the failed CIP status that was returned:

    • `S` — System failure. CIP was not performed because the CIP-related data was not valid. See [Testing ID verification](🔗) in the _Customer ID Verification (KYC/CIP)_ guide for CIP validations.

    • `F` — Failed. The customer is on a watch list or is unlikely to be a real person and therefore does not qualify for an account. The account will not be activated.

    • `R` — Referral. The customer is likely a real person because there was a partial match for the personal information and identifier. In this case, either you or Galileo performs further steps to identify the customer, such as requesting that valid documents be sent.

      • If Galileo completes validation and the customer passes, Galileo moves the account to `status: N` and sends the Account Events webhook <a href="ref:api-reference-events-api-pass-id" target="_blank">`PTID: pass_id`</a>.

      • If you complete validation and the customer passes, you call the <a href="ref:post_forcepasscip" target="_blank">Force Pass CIP</a> endpoint to move the account to `status: N` and you receive the Account Events webhook <a href="ref:api-reference-events-api-pass-id" target="_blank">`PTID: pass_id`</a>.

  9. 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 character** — <a href="ref:api-reference-account-statuses" target="_blank">Account status</a>

    • **Third character** — <a href="ref:api-reference-card-statuses" target="_blank">Card status</a> (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 <a href="doc:setting-up-a-card-program#lifecycle-of-a-card" target="_blank">Lifecycle of a card</a> in _Setting Up a Card Program_ for the next steps when the account has a card.

Note

The account setup process is a cron job with an interval between 5 and 30 minutes, according to your product settings. For this reason, you will receive the `CAPP: app_completed` or `PTID: pass_id` webhooks and the API response before the account is usable. See the <a href="doc:activate-card-procedure" target="_blank">Activating a Card</a> guide for more information. To see account status, call an endpoint such as <a href="ref:post_getaccountoverview" target="_blank">Get Account Overview</a> or see <a href="doc:about-accounts#retrieving-account-information" target="_blank">Retrieving account information</a> in the _About Accounts_ guide for a list of endpoints that retrieve the account status.

## Sample endpoint request and response

Consult the <a href="ref:post_createaccount" target="_blank">Create Account</a> or the <a href="ref:post_createvirtualcard" target="_blank">Create Virtual Card Account</a> endpoint to see how to build the API request and to see the response schema.

## Status codes

Consult the <a href="ref:post_createaccount" target="_blank">Create Account</a> or the <a href="ref:post_createvirtualcard" target="_blank">Create Virtual Card Account</a> endpoint for status codes and next steps.

## View the new account

Use the <a href="doc:post_getaccountcards" target="_blank">Get Account Cards</a> endpoint to retrieve account status and other information. Consult <a href="doc:about-accounts#retrieving-account-information" target="_blank">Retrieving account information</a> in the _About Accounts_ guide for a list of endpoints and the specific account information they retrieve.