This guide explains how physical and digital spending cards are represented in the Galileo system and which card types are relevant to the API consumer. This guide does not explain the banking functions that a program or product may support, such as whether the card is a debit or prepaid card.
A customer uses a card to initiate a transaction, such as making a purchase at a point of sale or paying a bill online.
Cards in the Galileo system are categorized by their tangibility:
- Physical — A piece of plastic with the card number printed on it.
- Digital — An electronic representation of a card that resides only on a web site, a mobile app, or in a mobile wallet. Digital cards are further categorized as:
- Virtual — Exists only as an image that is displayed inside a mobile app, on a website, or in an email.
- Digital image of a physical card — Electronic representation of a physical card, with the same 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. as the physical card.
- Tokenized — Provisioned to a mobile wallet.
Cards are also categorized by their relationship to the cardholdercardholder - An account holder who has been issued a card.:
- Personalized — A card that is issued to a specific cardholder, with the cardholder's name displayed on it.
- Instant issue — A card that is not issued to a particular cardholder, with no cardholder name displayed on it.
Every card must be associated with an account in the Galileo system. Multiple cards can be associated with an account, but multiple accounts cannot be associated with a card.
This diagram shows how one account holder can have multiple accounts, and each account can have one or more cards associated with it; however, only one card per account should be active at a time. (The dotted lines represent inactive cards.)
See About Accounts for more information about cards and accounts.
You can use one of four endpoints to create a card account. This table shows which endpoint to use for the specified use case. In some cases you can use one of two endpoints for the use case.
|Use case||Endpoint||More information|
|Onboard a new customer and create a physical or virtual card, with the option to deposit funds||Create Account||Creating an Account|
|Onboard a new customer and create a virtual card only||Create Virtual Card Account||Creating an Account|
|Create another primary account for an existing account holder||Create Account||Creating an Account|
|Create a new card account (secondary account) for an existing account holder||Create Account|
|Creating an Account|
Adding an Account
|Add an instant issue card to an existing card account||Add Card|
|Add a virtual card to an existing account to temporarily replace a lost or stolen card||Add Card|
|Replace a card||Modify Account or Card Status with Add Card||Lost, Stolen, or Damaged Cards|
In the Galileo system you will encounter these types of identifiers related to cards. Also see Account identifiers in the About Accounts guide.
The primary account number is the 16-digit number that is displayed on a card, either physical or digital. The first six or eight digits are the BINBIN - Bank identification number. Assigned by a bank, it is the first six or eight digits of a PAN.. You can receive the full PAN 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; otherwise, you receive a masked PAN in API responses.
In API calls you can pass the PAN for
primaryAccount if you are PCI compliant. If you are not PCI compliant you can use the CAD.
The card identifier (CAD or
card_id) is a Galileo-generated identifier for a specific card. This identifier is not the same as the PAN but it does map one-to-one with the PAN, meaning that when the PAN changes, the CAD changes. You do not need to be PCI compliant to receive the CAD.
In most API calls you can pass the CAD for
primaryAccount. Where there are multiple cards associated with an account, you must pass the CAD.
This table summarizes how the PAN and CAD are represented in the Galileo system.
|Program API requests|
|Program API responses|
Galileo creates a card object for each card. The object contains:
- CAD — The card identifier, a Galileo-generated number.
- PAN* — The 16-digit card number, displayed on the card. Encrypted in the Galileo system.
- 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.* — This 3-digit number is displayed on a card and helps authenticate a card at the point of sale. Encrypted in the Galileo system.
- Expiration date* — The date when the card expires. This value is generated at the time of card issue. Product settings determine the expiration date for a particular card. Encrypted in the Galileo system.
- Customer record — Referenced from the account holder's record.
- PIN data — Record of PIN failures, last failure date, and hashed PIN.
- Create date — Date when the card object was created.
- Activation date — Date when the card was activated.
* You can receive these values in API responses only if you are PCI compliant; otherwise, you get a masked PAN and no CVV or expiry date.
A card's status is designated by a single capital letter in the Galileo system, as shown in the Card Statuses enumeration.
Card status is not the same as account status. The statuses may be similar in some cases, but they operate independently. See the Account Statuses enumeration.
A card with
status: N (active) can be used to initiate transactions, as long as the account is also active. Cards in other statuses generally cannot be used.
When changing a card status using the Modify Account or Card Status endpoint, make sure the type affects what you want it to affect—some types affect both the card and the account, whereas others affect only the account or only the card.
Card networks are business entities that have set up standards, conventions, and networks for processing their cards. Prominent networks are Mastercard, Visa, and Discover. When a cardholder initiates a transaction at a point of sale, the transaction is routed through the network to Galileo. See About Card Transactions for details.
In some cases an authorization is routed through a different network than the network printed on the card — for example, a Visa card authorization could be routed through a Mastercard network. This is expected behavior.
A physical card must be activated before it can be used, unless the card is part of the Digital FirstDigital First - A program feature that Galileo offers wherein you give your customers a digital card to use while their physical cards are being embossed. The digital and physical cards have the same PAN and expiry date. program, where physical cards are automatically activated upon issuance. (See the Digital First Program guide for more information.) Virtual cards are often activated upon card creation, depending on your product settings.
See the Activating a Card procedure for instructions.
Personal identification numbers are 4-digit numbers that customers input at a point of sale or ATM to help verify their identities as legitimate cardholders. Typically, customers set their PINs at the time of card activation.
See PIN-Set Procedures for more information.
Physical cards are created by embossing companies. You will partner with an embossing vendor to print and fulfill your card orders. Galileo has integrated with several embossing vendors and will introduce you to any that you choose. The embossing companies differ in their support for card characteristics such as the number of characters per line, the material used for the card, and chip inclusion.
To specify which card art to use, you can use one of several methods, such as populating the
externalAccountId parameter in the Create Account endpoint to specify which card art to use or to add other information for the embosser. You can also set up a separate product for each type of artwork, and then call the Set Account Feature endpoint to switch to the new product. Contact Galileo for information on using these methods.
An automated process in the Galileo system gathers the card information for all accounts with
status: X and sends it to the configured embosser. According to product settings, new accounts for physical cards have
status: X upon creation, or you can manually change an account to
status: X using the Modify Account or Card Status endpoint with
If a card is in a Digital First program, the card is issued first as an active digital card while a physical card with the same PAN/CVV/expiry is sent to the embosser, even if it is not in
status: X. (See the Digital First Program guide for more information.)
The embossing vendor mails cards to your customer's primary address, as passed with the Create Account endpoint. If you need to ship the card to a different address than the primary address, pass the address in the
shipTo fields in the Create Account or Update Account endpoint. Set the
shipToAddressPermanent parameter if subsequent cards should always be shipped to the
shipTo address instead of the primary address. If you do not set the
shipToAddressPermanent parameter, the next time the embosser mails a card, it will be sent to the primary address.
To retrieve card information use these endpoints. Keep in mind that to receive an unmasked PAN, the card expiry, and the CVV, you must be PCI compliant; otherwise, you will receive only the masked PAN.
Use the Get Card endpoint to retrieve information about a specific card and the Get Account Cards endpoint to get a list of cards that are associated with the holder of the specified account, including related secondary accounts.
|Attribute||Get Card||Get Account Cards|
|External card ID||X||X|
|Encrypted card number||X|
|Embossed cards object (array)||X||X|
|Freeze info object||X||X|
|PIN fail count||X||X|
|PIN fail date||X||X|
|Cardholder date of birth||X|
|Express mail setting||X|
|Cardholder income source||X|
|Account active status||X|
|Account application date||X|
|Bill cycle day||X|
|Galileo account number (balance ID)||X|
|Activation date (||X|
* Only when provider parameters are set.
A frozen card cannot be used for purchases but has not been cancelled. An account with a frozen card can still receive payments and deposits. As soon as the card is unfrozen it is usable again without reissuing the card or creating a new card. Reasons for freezing a card rather than disabling or cancelling it include:
- The cardholder cannot locate their card but is not ready to report it lost or stolen.
- Parents want to stop their teenager from accessing funds for a time.
- A company wants to temporarily withdraw fund access for an employee.
To freeze a card call the Modify Account or Card Status endpoint with
type: 17. To unfreeze it use
When you reissue a card, you create a new card order for the embosser that retains the same PAN as the original card but that has a new expiry.
You may choose to reissue cards under these circumstances:
- The cardholder reports the card as damaged and needs a new card. Follow the Damaged cards instructions in the Lost, Stolen, or Damaged Cards guide. This procedure follows the default reissuance process, which retains the PAN but sets a new expiry.
- The cardholder's account switches from one product to another using the Set Account Feature endpoint. You can control whether a product switch triggers a reissue, and also whether it triggers a new expiry, by configuring product parameters. Contact Galileo for instructions on setting these parameters.
Before a card reaches its expiry date, you can arrange for the new card to be automatically embossed and shipped a set number days before.
In the case of an expiring virtual card, ask Galileo to send you the
RBEX: card_expiring event webhook to notify you that a card is expiring. When you receive the webhook, use Add Card to create the replacement virtual card.
Your product settings can specify some cancellation policies, such as account inactivity or negative balance. A customer can also ask to cancel a card, either because they want to discontinue the product or because it is lost or stolen. See Lost, Stolen, or Damaged Cards for the latter cases.
These three statuses indicate that a card cannot be used:
- C — Cancelled. The PAN cannot be used and should not be reactivated.
- D — Disabled. The PAN cannot be used, but it can be reactivated at a later time.
- Z — Cancelled without refund. ("Without refund" refers to the account.)
To cancel a card use the Modify Account or Card Status endpoint, passing the appropriate type according to the use case.
- If multiple cards are associated with the account, you must pass the PAN or CAD for
- If you pass a Modify Status type that disables or cancels only the account, the associated card status may not change but the card(s) still cannot be used.
|Use case||Type||Account status||Card status||Notes|
|Update card status to Cancelled||5||no change||Changes the card to |
Does not affect related secondary accounts.
|Deactivate account and cancel card(s)||13||Changes both the account and associated cards to |
Also closes any related savings accounts.
|Account deactivated and card(s) cancelled through the Galileo API||16||Changes both the account and associated cards to |
Does not affect related secondary accounts.
|Cancel without refund all accounts and cards for a customer and all related accounts and cards||20||Affects all accounts and cards of the account holder, including secondaries.|
|Disable account and active cards||23||Changes both the account and associated active cards to |
Updated 4 months ago