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 printed in bulk, with no cardholder name displayed on it. May or may not be issued to an individual cardholder. See Instant-Issue Cards for more information.

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.

This table shows which endpoint to use for the specified 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
Issue an instant-issue card to an individualCreate AccountInstant-Issue Cards
Add an instant-issue card to an existing card accountAdd CardInstant-Issue Cards
Add a virtual card to an existing account to temporarily replace a lost or stolen cardAdd CardLost, Stolen or Damaged Cards
Replace a damaged cardReissue CardReissuing Cards
Replace a virtual cardModify Status with Add CardLost, Stolen, or Damaged Cards

Card identifiers

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

PAN

The primary account number (PAN) 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., depending on the network. A PAN is unique in all the world. 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 and the RDFs.

CAD

The card identifier (CAD or card_id) is a Galileo-generated identifier for a specific card. This identifier corresponds to a PAN. The CAD is unique per client. You do not need to be PCI compliant to receive the CAD.

The card record

Each client has a cards table that records all of the cards in the program. Every time you create a new card, Galileo adds a row in that table. The row number is the CAD, and included in that row are the following columns:

  • CAD — The card identifier, a Galileo-generated number.
  • PAN — The 16-digit card number, displayed on the card. Encrypted in the Galileo system.
  • Expiration date — The date when the card expires. Encrypted in the Galileo system.
  • Account number — Value that links the card record to the account record.
  • Cardholder ID — Value that links the card record to the cardholder record.
  • Create date — Date when the card record was created.
  • Activation date — Date when the card was activated.
  • PIN data — Record of PIN failures, last failure date, and hashed PIN.
  • Card status — Single-letter designation of the card's status. See Card statuses for more information.

Every time a new PAN is generated, a new row is added to the cards table, meaning that a new CAD is also generated. This 1:1 relationship between a PAN and a CAD means that when you are not PCI-compliant, you can pass the CAD in an API call for accountNo and it will point to the same card record.

In general, when passing the accountNo for an API call, you should use the CAD or PAN when the endpoint is intended to affect a single card rather than the card account as a whole. When you pass the PRN for accountNo and there is more than one active card associated with the PRN, most endpoints will return an error. On the other hand, some endpoints do not accept PAN or CAD for accountNo. Check the endpoint reference for each individual endpoint to verify.

A PAN also has a 1:1 relationship with a PIN. When you generate a new PAN, you have to set a new PIN for the card. In contrast, if you reissue the card with the same PAN, you do not have to set a new PIN. See PIN-Set Procedures for more information.

A new PAN (and therefore new CAD) is generated under these circumstances:

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

Galileo systemPANCAD
Program API requestsaccountNoaccountNo
Program API responsescard_numbercard_id
Events APIcard_numbercad
Auth APIcard_numbercad
RDFsCARD NUMBERCARD IDENTIFIER

Emboss records

The emboss table stores emboss records. An emboss record is created only for physical cards, and it is created every time that the card is sent to the embosser. It is therefore possible for one card to have multiple emboss records: one when the card is first created, and then one each time the card is reissued with the same PAN. The row number is identified by the emboss UUID, and each row includes these columns:

  • Emboss UUID — A globally unique identifier for the row in the emboss table.
  • Expiration date — The date when the card will expire.
  • CVV — The three-digit code displayed on a card to authenticate the card for card-not-present transactions. Encrypted in the Galileo system.
  • Created date — The date the emboss record was created.
  • Emboss date — The date the emboss record was sent to the embosser.
  • Emboss status — The status of the emboss record:
    • Y — Sent to the embosser
    • N — Card has been activated
  • Shipping type — Whether the card was shipped standard or express.
  • Product ID — The product ID for the embossed card.

A new emboss record is generated by the emboss process, which runs every 15 minutes in CVCV - Client Validation. A test environment where you can test your implementation before moving it to Production.. In ProductionProduction - The live Galileo environment where real transactions are performed., the interval of the process varies according to client settings, but is at least once per day. When you create a new card, a new CAD is created immediately, but the emboss record is not created until after the emboss process runs. For this reason, you will often not see an emboss record right after creating or reissuing a card.

The emboss process generates both the expiry date and the CVV. These two values have a 1:1 relationship, meaning that any time you generate a new expiry date for a card, you also generate a new CVV.

An emboss record is generated under these circumstances.

Emboss UUID

You can use the emboss UUID to identify which emboss record is the latest. When the emboss_uuid field is returned by a Program API endpoint, it is nested in the embossed_cards object. When the embossed_uuid field is outside the embossed_cards object, the value identifies the latest emboss record.

Also see Card embossing for more information.

Card identifiers in Program API responses

When you call endpoints that return card information, the card and emboss records are nested as follows:

customer: [
    accounts: [
        cards: [
            emboss_records: [ ]
       ]
    ]
]

Open these Recipes to see examples of multiple accounts, cards and emboss records.

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. Compare with the Account Statuses enumeration.

During the authorization process, the Galileo system checks to see whether the card is in status: N (active). The account must also be in status: N for the transaction to be approved. When a card or account is not in status: N, the authorization request is denied.

When changing a card status using the Modify 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 Networks for details.

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 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. Any time you generate a new PAN, you must set a new PIN. If you reissue a card without a new PAN, you can use the same PIN as before..

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.

An automated process in the Galileo system gathers the card information for all accounts in 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 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 art

In conjunction with your bank, you design the appearance of your card products. Typically, you create one image for each of your card products, but you might also decide to offer customers a choice of card designs for the same product ID.

To specify which card design to use, you have several options. For each option you will have to coordinate with your emboss vendor to determine which value means which image, and you will have to arrange with Galileo to pass that value to the embosser (or the card network for mobile wallets):

  • Pass a value in the Create Account or Start Enrollment endpoint.
    • id2 — When passing card art information in this field, you must also pass idType2: 14 so that id2 does not have to pass a validation test. This option requires that the EMBFL parameter be set to GID2. If you are not using Galileo's integrated CIP process, also set IDSSN to optional and VLDLV to null; otherwise, you must populate id with unique values such as the account holder's phone number.
    • externalAccountId — This value will also be included in the Customer Master RDF. (This value is in the Complete Enrollment endpoint instead of Start Enrollment.) Not valid for mobile wallets.
  • After account creation, call the Set Account Feature endpoint with these settings:
    • featureType: 16
    • featureValue: string|A

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.

According to your arrangements with your emboss partner, you can offer customers the option to have their cards shipped via express mail. To enable express shipping, call the Set Account Feature endpoint with these parameters:

  • accountNo — PAN or CAD or the card
  • featureType: 5
  • featureValue: Y — Some emboss vendors use values 0–9: verify with your vendor which value to use.

Viewing card information

For every new or updated card record, Galileo includes that record in the daily Account Card RDF.

To retrieve card information with the Program API, use Get Card or Get Account Cards. 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 objectXX
Emboss UUIDXX
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.

Open these Recipes to see examples of the Get Card and Get Account Cards responses.

Freezing cards

A frozen card cannot be used for purchases but has not been canceled. 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 canceling 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 Status endpoint with type: 17. To unfreeze it use type: 18.

When you call Modify Status with type: 17 to freeze a card, and you do not pass startDate and endDate, the card is frozen for 24 hours starting with the current date-time. When unfreezing a card with type: 18, the startDate and endDate parameters are ignored and the card is unfrozen immediately.

📘

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

See Reissuing Cards.

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. If you would rather reissue expiring cards yourself, follow the instructions in Use case 1: Reissue card with same PAN and new expiry in the Reissuing Cards guide.

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 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?