About Cards

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.

Card types

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.

Cards and accounts

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.)

📘

Note

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 caseEndpointMore information
Onboard a new customer and create a physical or virtual card, with the option to deposit fundsCreate AccountCreating an Account
Onboard a new customer and create a virtual card onlyCreate Virtual Card AccountCreating an Account
Create another primary account for an existing account holderCreate AccountCreating an Account
Create a new card account (secondary account) for an existing account holderCreate Account
or
Add Account
Creating an Account

Adding an Account
Add an instant issue card to an existing card accountAdd Card
Add a virtual card to an existing account to temporarily replace a lost or stolen cardAdd Card
Replace a cardModify Account or Card Status with Add CardLost, Stolen, or Damaged Cards

Card identifiers

In the Galileo system you will encounter these types of identifiers related to cards. Also see Account identifiers in the About Accounts guide.

PAN

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 accountNo or primaryAccount if you are PCI compliant. If you are not PCI compliant you can use the CAD.

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 accountNo or primaryAccount. Where there are multiple cards associated with an account, you must pass the CAD.

Card identifiers in the Galileo system

This table summarizes how the PAN and CAD are represented in the Galileo system.

Galileo systemPANCAD
Program API requestsaccountNo

primaryAccount
accountNo

primaryAccount
Program API responsescard_numbercard_id
Events APIcard_numbercard_id
Auth APIcard_numbercad
RDFsCARD NUMBERCARD IDENTIFIER

The card object

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.

Card statuses

A card's status is designated by a single capital letter in the Galileo system, as shown in the Card Statuses enumeration.

📘

Note

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

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.

📘

Note

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.

Card activation

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.

PINs

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.

Card embossing

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 type: 22.

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.)

Card shipment

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.

Viewing card information

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.

AttributeGet CardGet Account Cards
PANXX
ExpiryXX
CVV (card_security_code)X
CAD (card_id)XX
StatusXX
External card IDXX
PRNXX
Cardholder nameXX
Encrypted card numberX
Encrypted expiryX
Embossed cards object (array)XX
Freeze info objectXX
PIN fail countXX
PIN fail dateXX
SSN*X
Cardholder addressX
Cardholder phoneX
Cardholder emailX
Cardholder date of birthX
Ship-to addressX
Express mail settingX
Cardholder occupationX
Cardholder income sourceX
Account active statusX
Account application dateX
Bill cycle dayX
Galileo account number (balance ID)X
Product IDX
Activation date (start_date)X

* Only when provider parameters are set.

Freezing cards

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 type: 18.

📘

Note

Modify Status types 17 and 18 do not change the card or account status. To see whether a card is frozen call the Get Card or Get Account Cards endpoint and check the freeze_info object.

Lost or stolen cards

See Lost, Stolen, or Damaged Cards.

Reissuing cards

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.

Card expiry

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.

Cancelling cards

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 accountNo.
  • 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 caseTypeAccount statusCard statusNotes
Update card status to Cancelled5no changeCChanges the card to status: C. Does not change the account.

Does not affect related secondary accounts.
Deactivate account and cancel card(s)13CCChanges both the account and associated cards to status: C.

Also closes any related savings accounts.
Account deactivated and card(s) cancelled through the Galileo API16ZZChanges both the account and associated cards to status: Z.

Does not affect related secondary accounts.
Cancel without refund all accounts and cards for a customer and all related accounts and cards20ZZAffects all accounts and cards of the account holder, including secondaries.
Disable account and active cards23DDChanges both the account and associated active cards to status: D.

Did this page help you?