Creating an Account

This guide describes the procedure for creating a new customer account using the Create Account endpoint or Create Virtual Card Account 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 KYC and CIP. Consult the Customer ID Verification (KYC/CIP) guide for instructions. You should also read the About Accounts 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:

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 New account creation in the About Accounts gude 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 PAN/CVV/expiry date values only if you are PCI compliant.

Parameters

This table explains the parameters that are specific to the Create Account and Create Virtual Card Account endpoints. See the Create Account or the Create Virtual Card Account reference for details.

ParameterUsage
accountNoPopulate only for instant-issue cards. For all others leave blank.
idRequired for Galileo CIP. Primary ID number. See Using the id and idType parameters for instructions. If you are not using Galileo CIP you may still populate these ID fields for your own records.
idTypeRequired 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 Customer ID Types enumeration for valid values.
id2Optional or required for Galileo CIP, depending on your product settings. Secondary ID number.
idType2Required when id2 is populated. Secondary ID type.
locationTypeDo not populate.
locationDo not populate.
localeCustomer 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 parametersRequired for Galileo CIP and for the customer record. For customer ID verification you must include the name parameters, the address parameters, and the date of birth. See the Customer ID Verification (KYC/CIP) guide for more information.
webUidDo not populate.
webPwdDo not populate.
secretQuestionDo not populate.
secretAnswerDo not populate.
incomeSourceCreate Account only. The name of the customer's employer or income source.
occupationCreate Account only. Job title of the customer.
prodIdThe identifier for the product the customer is signing up for. Galileo generates a unique product ID for each of your products.
loadAmountPopulate only if the product is configured to deposit funds into the account at creation time.
loadTypeRequired when passing loadAmount; valid values are created in cooperation with Galileo.
externalAccountIdThis field is for your own purposes. Galileo stores but does not process this parameter; however, it can be updated with the Update Account endpoint (active accounts only), you can retrieve it using the Verify Account endpoint, and it is provided in the RDFs. 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.
primaryAccountPopulate only when creating a secondary account
sharedBalanceRequired 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.
userDataThis 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.
offlineDo not populate.
verifyOnlyPass 1 to verify the parameter values in your API request without creating an account or running CIP.
cipStatusPopulate only when using Galileo CIP. See Overriding your ID verification setting for more information.
embossLine2A second line to be printed under the name on the card.
providerAssessedFeeDo not populate.
loadFromAccountNoFor depositing funds into the new account from another account in the same program. You must also pass loadAmount and loadType when populating this parameter.
sweepDateDo not populate.
expressMailCreate Account only. Populate to ship the card via accelerated delivery. Valid values come from your emboss vendor.
shipToAddressPermanentCreate 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 parametersCreate Account only. Populate for physical cards, when the shipping address is different from the primary address..
businessNameRequired when prodId is a business account. See businessName parameter for the validation rules.
mobilePhoneCountryCodeRequired when any of the phone parameters are populated. This value determines how the phone numbers are validated

Account-creation workflow

Consult these flowcharts and explanations for the Create Account and Create Virtual Card Account 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 Create Account endpoint and subsequent backend processes when not using Galileo's CIP. This diagram is also valid for the Create Virtual Card Account endpoint. The actual sequence of events in the Galileo system may vary.

πŸ“˜

Note

The Account Events messages are sent to you according to the arrangements you have made with Galileo.

887887
  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 Create Account 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 Galileo returns status: 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 PAN, the expiry date, and the CVV. The full contents of this object are returned to you in the API response only if you are PCI compliant.
  7. If all processes have been successful, Galileo sends two messages:
  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 β€” Account status
    • Third character β€” Card 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.

Create Account using Galileo CIP

This flowchart shows the logical progression of the Create Account endpoint and subsequent backend processes when using Galileo's integrated CIP. This diagram is also valid for the Create Virtual Card Account endpoint. The actual sequence of events in the Galileo system may vary.

921921
  1. Retrieve customer information from your web page or mobile app.
  2. Populate the Create Account 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 PAN, the expiry date, and the CVV. The full contents of this object are returned to you in the API response only if you are PCI compliant.
  7. Galileo verifies whether CIP was successful:
    • If CIP was successful, Galileo sends you two messages:
    • If CIP was not successful, Galileo sends two messages:
      • API response with status: 407-11 (CIP failed) with the R, F or S verdict in the cip field.
      • Account Events webhook FTID: fail_id.
  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 PTID: pass_id.
      • If you complete validation and the customer passes, you call the Force Pass CIP endpoint to move the account to status: N and you receive the Account Events webhook PTID: pass_id.
  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 β€” Account status
    • Third character β€” Card 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.

πŸ“˜

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 Activating a Card guide for more information. To see account status, call an endpoint such as Get Account Overview or see Retrieving account information in the About Accounts guide for a list of endpoints that retrieve the account status.

Sample endpoint request and response

Consult the Create Account or the Create Virtual Card Account endpoint 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
407-03Invalid instant issue card. An attempt was made to issue an instant-issue card that has already been issued.Retry with an unissued instant-issue card number.
407-04The value in loadAmount was outside what product settings permit. Account not created.Retry with an appropriate amount in loadAmount, or check your maxLimit and minLimit settings.
407-05Could not create account.Contact Galileo for troubleshooting.
407-06Could not load card.Contact Galileo for troubleshooting.
407-07Primary account is invalid.The account number in primaryAccount cannot be an instant-issue card.
407-08Secondary accounts cannot be added to secondary accounts.The account number in primaryAccount cannot be a secondary account.
407-09Maximum number of secondary accounts was exceeded, according to product settings.Verify that your product settings are correct.
407-10idType: 2 (SSN) is required by your product settings for running CIP, and you provided a different ID type.Pass idType: 2 with a valid SSN in the id field.
407-11The product is configured to use Galileo CIP, and the customer failed CIP.Take action depending on the result in the response:

F β€” Fail. Take no action: the customer does not qualify for an account.

R β€” Refer. Depending on your arrangement with Galileo, request valid documents from the customer or wait for Galileo's third-party CIP to complete.
407-12An account with the same government ID has already been created.Follow your business plan for this outcome.
407-13You passed cipStatus: 1 and Galileo ran CIP on the customer. No account was created.Take action depending on the result in the response:

P β€” Pass. Contact Galileo for instructions on creating the account. Do not run Create Account again.

F β€” Fail. Take no action: the customer does not qualify for an account.

R β€” Refer. Depending on your arrangement with Galileo, request valid documents from the customer or wait for Galileo's third-party CIP to complete.
407-14Card successfully loaded, but load limit was violated. Only the amount permitted by project settings was loaded.Contact Galileo for troubleshooting.
407-15The account was created but funds were not loaded onto the card because of limit violations. An attempt will be made tomorrow to load the card.Contact Galileo for troubleshooting.
407-16Card is marked as fraudulent. An instant-issue card was swiped before it was issued.Retry with another instant-issue account.
407-17Card not allocated to your store for issuance. The location does not match the location that this batch of cards was created for.Change the location on the account or retry with another instant-issue account number.
407-18The loadFromAccountNo parameter contained an account number that does not exist in the Galileo system.Resend with a valid account number.
407-19A load was attempted for a non-positive amount. The value in loadAmount was negative.Retry with positive amount.
407-20Maximum number of allowed secondary accounts has been reached.Set SECLM on the secondary account to a higher number.

View the new account

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