Creating an Account

This guide describes the procedure for creating a new customer debit 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 KYCKYC - Know your customer. Banks are required to verify the identities of potential customers. KYC requirements are specific to each country. Galileo sometimes uses the term "CIP" (customer identification program) to refer to the combination of KYC and CIP. and 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).. 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 debit card.
  • Onboard a new customer for a virtual debit card.
  • Create a secondary account for a different customer than the primary account holder, such as a spouse or child.

📘

Note

This procedure contains the basic instructions for the simplest use case: onboarding a new customer for 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. (debit) account. If you need a different account type or to customize features beyond what is provided here, contact Galileo.

Do not follow this procedure to:

  • Add a secondary account to an existing customer; instead, see the Adding an Account guide.
  • Add an overdraft account; instead, see the Creating an Overdraft Account guide.
  • Create an instant-issue cardinstant-issue card - A card that is not issued to a particular customer. For example, a business could have cards loaded with $50 on them that they give to their customers as a bonus or promotion. In contrast, a personalized card has the cardholder's name displayed on it.; instead, contact Galileo.
  • Create an account for a Digital First Program account, where you provide a digital version of the card for customers to use while the physical card arrives; instead, consult the Digital First Program guide.
  • Break out the account-creation steps into component parts, such as passing Galileo 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). before creating an account; instead, contact Galileo.

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 object — Contains general account information.
  • Card object (if configured) — An entity that describes a card. You can receive unmasked PANPAN - Primary account number. The 16-digit number that is printed on a card, beginning with the BIN. This number is not the same as the account identifier, which is the PRN, or the card identifier, which is the CAD./CVVCVV - Card verification value. A number that is included on a card to help verify that a cardholder has the actual card (physical or virtual) in hand. CVV1 is a value that is embedded in a card's magnetic stripe, CVV2 is a 3- or 4-digit number printed on the actual card, and iCVV is a number embedded in security chips. In most cases, "CVV" refers to CVV2./expiry dateexpiry date - The date that a card expires. This date is displayed on a virtual or physical card and is randomly set at the time the card is created. The expiry date is encrypted in the Galileo system and cannot be retrieved by anyone who is not PCI compliant. values only if you are PCIPCI - Payment card industry. The PCI comprises all of the systems and organizations that are associated with credit, debit, pre-paid, and other card processing systems. The PCI sets security standards that card issuers must comply with to handle sensitive data such as a full card number, CVV, and expiration date. 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
accountNoDo not populate.
idRequired for Galileo CIP. Primary ID number. See Using the id and idType parameters for instructions on using the ID parameters. 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.
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.
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. Valid values are configured in cooperation with Galileo.
loadAmountOnly 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 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. 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.
primaryAccountOnly when creating a secondary account; cannot be a secondary account number
sharedBalanceRequired when passing primaryAccount; Pass 1 when creating a secondary account that will transact on the same balance as the specified 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.
cipStatusOnly when using Galileo CIP, to override program settings.
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 using this parameter.
sweepDateDo not populate.
expressMailCreate Account only. To ship the card via accelerated delivery. Valid values depend on the emboss partner for your program.
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. When a physical card is to be issued at account-creation time.

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

Run the Create Account or the Create Virtual Card Account endpoint only once per customer when onboarding. If you need to run an account-creation or onboarding step again, contact Galileo for instructions.

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.

  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 PANPAN - Primary account number. The 16-digit number that is printed on a card, beginning with the BIN. This number is not the same as the account identifier, which is the PRN, or the card identifier, which is the CAD., the expiry dateexpiry date - The date that a card expires. This date is displayed on a virtual or physical card and is randomly set at the time the card is created. The expiry date is encrypted in the Galileo system and cannot be retrieved by anyone who is not PCI compliant., and the CVVCVV - Card verification value. A number that is included on a card to help verify that a cardholder has the actual card (physical or virtual) in hand. CVV1 is a value that is embedded in a card's magnetic stripe, CVV2 is a 3- or 4-digit number printed on the actual card, and iCVV is a number embedded in security chips. In most cases, "CVV" refers to CVV2.. The full contents of this object are returned to you in the API response only if you are PCIPCI - Payment card industry. The PCI comprises all of the systems and organizations that are associated with credit, debit, pre-paid, and other card processing systems. The PCI sets security standards that card issuers must comply with to handle sensitive data such as a full card number, CVV, and expiration date. 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. If all criteria are fulfilled, the account is put into status: N with the active flag set to Y, which means the account is active and ready to use.

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.

  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 PANPAN - Primary account number. The 16-digit number that is printed on a card, beginning with the BIN. This number is not the same as the account identifier, which is the PRN, or the card identifier, which is the CAD., the expiry dateexpiry date - The date that a card expires. This date is displayed on a virtual or physical card and is randomly set at the time the card is created. The expiry date is encrypted in the Galileo system and cannot be retrieved by anyone who is not PCI compliant., and the CVVCVV - Card verification value. A number that is included on a card to help verify that a cardholder has the actual card (physical or virtual) in hand. CVV1 is a value that is embedded in a card's magnetic stripe, CVV2 is a 3- or 4-digit number printed on the actual card, and iCVV is a number embedded in security chips. In most cases, "CVV" refers to CVV2.. The full contents of this object are returned to you in the API response only if you are PCIPCI - Payment card industry. The PCI comprises all of the systems and organizations that are associated with credit, debit, pre-paid, and other card processing systems. The PCI sets security standards that card issuers must comply with to handle sensitive data such as a full card number, CVV, and expiration date. 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. The account setup process determines whether all other criteria for the account have been fulfilled, as determined by your product settings. When all criteria are fulfilled, the account is put into status: N (if needed) with the active flag set to Y, which means the account is active and ready to use.

📘

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. According to your product settings, the account will be put into status: N (active) or status: X (set to emboss). See the Activating a Card guide for more information. To see account status, run an endpoint such as Get Account Overview. 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. Statuses that are not displayed in this table are not applicable to debit accounts.

Status codeDescriptionNext steps
0SuccessNone
2Your API call contained one or more values that were not valid for the parameter.Retry with a valid value.
24This API call was already submitted and successfully completed. The transaction IDs were identical.None. Duplicate transactions have no effect on the Galileo system.
28The value in prodId was not valid for the provider.Retry with a valid product ID.
100The value in verifyOnly was 1 and all parameter values passed verification.None
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-08The value in primaryAccount was a secondary account number. A secondary account can be added only to a primary account.Retry with a valid primary account number.
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-18The loadFromAccountNo parameter contained an account number that does not exist in the Galileo system.Resend with a valid account number.
-1System failure. Possibly a network or database issue.Consult the response to see which steps to take.

View the new account

Use the Get Account Overview 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.


Did this page help you?