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:

• 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 card; instead, see Setup for Instant Issue.
• 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 Digital First cards in the Choose a Card Strategy guide.
• Break out the account-creation steps into component parts, such as passing Galileo CIP before creating an account; instead, use Start Enrollment and Complete Enrollment. For directions see Start Enrollment process 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 New account creation 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 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.

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.

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.
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. 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:
   • API response with status_code: 0 (successful)
   • Account Events webhook message CAPP: app_completed.
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.

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.
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. 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:
     • API response with status_code: 0 (successful).
     • Account Events webhook message CAPP: app_completed.
   • 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 message 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 message 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 message 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 webhook messages 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 the Create Account or the Create Virtual Card Account endpoint for status codes and next steps.

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.