A card is a payment device that enables a customer to purchase goods or services from a merchant or business. This guide covers what you need to know about cards to set up a successful program with Galileo. This includes general information about cards, the relationship between cards and account, the data elements of a card, and the lifecycle of a card in the Galileo system.
<a href="doc:choose-a-card-strategy" target="_blank">**Choose a Card Strategy**</a> — How to choose which card to issue and when
<a href="doc:card-creation-endpoints" target="_blank">**Card-Creation Endpoints**</a> — A developer resource of endpoints to use when creating cards.
## Card networks
A card network (also called a "payments network" or "card association") is a business entity that comprises banks, dedicated networks, and messaging systems to facilitate card transactions. The card network defines the standards and conventions for processing their cards. When a cardholder initiates a transaction, the transaction is routed through a network to Galileo.
One of the first decisions you make when setting up a card program is to choose your primary network: Visa, Mastercard or Discover. See <a href="doc:networks" target="_blank">Networks</a> for details on primary and secondary networks as well as signature vs PIN networks.
## Decisions to make
These are some of the decisions you will need to make when setting up a card program:
Which type of card to issue. See <a href="doc:choose-a-card-strategy" target="_blank">Choose a Card Strategy</a> for more information.
Whether to charge a fee for issuing, reissuing or replacing cards
How your cardholders will <a href="doc:activate-card-procedure" target="_blank">activate their cards</a> and <a href="doc:pin-set-procedures" target="_blank">set their PINs</a>
Number of years until the card expires
Whether to generate <<glossary:PAN>>s in sequential order or at random
Whether to permit cardholders to load cash onto cards, and if so, how much and by what means (such as GreenDot, Visa Money Transfer or Maestro Loads)
In which countries the card is valid
Whether to block PIN transactions at ATMs or points of sale
## Cards and accounts
Every card, physical or digital, must be associated with an account in the Galileo system. In the simplest setup, one account is associated with one card. Multiple cards can also be associated with an account, but multiple accounts cannot be associated with a card.
The diagram above 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 <a href="doc:about-accounts" target="_blank">About Accounts</a> for more information about cards and accounts.
See <a href="doc:card-creation-endpoints" target="_blank">Card-Creation Endpoints</a> for specific use cases and their respective endpoints.
## Card elements
A card, either physical or digital, has the data necessary for a merchant to obtain authorization for a transaction. Galileo creates a **cards** table for your program that records all of the cards that you create. See <a href="doc:retrieving-card-information" target="_blank">Retrieving Card Information</a> to learn more about card records and how they are created.
The card consists of the following elements, among others:
For personalized cards the cardholder’s name is displayed on the front of the card. For instant-issue cards the cardholder's name is not displayed. You input the name for the card in the `
middleName` and `
lastName` parameters in the enrollment endpoints such as <a href="ref:post_createaccount" target="_blank">Create Account</a>.
### Primary account number
The <<glossary:PAN>> is a globally unique 16-digit number that is displayed on a card, either physical or digital. The first six or eight digits are the <<glossary:BIN>>, depending on the card network. The PAN is called the `
card_number` in the API responses and `
CARD NUMBER` in the RDFs.
You can receive the full PAN only if you are PCI compliant. Otherwise, you receive a masked PAN in API responses and the <a href="doc:about-the-raw-data-files-rdfs" target="_blank">raw data files (RDFs)</a>.
### Expiry date
The date when the card expires. As you set up each card product you specify how many years until expiration. You have the option of randomizing the expiration month for each card so that it's harder for a fraudster to guess the expiry date for any of your cards.
The expiry date is encrypted in the Galileo system. It is called `
expiry_date` in Program API responses and `
EXPIRATION DATE` in the RDFs.
### Card verification value (CVV)
The 3-digit number that appears on the back of the card is used for security purposes in card-not-present transactions, such as online purchases. This value has a 1:1 relationship with the expiry date—when a card gets a new expiry date, it also gets a new CVV.
The CVV is called the `
card_security_code` in Program API responses.
### Card identifier
In addition to the basic card elements, the Galileo system generates a card identifier (CAD). Every time you create a new card, Galileo adds a row in the **cards** table, and the row number is the CAD. A CAD has a 1:1 relationship with a PAN, so any time a card gets a new PAN, it also gets a new CAD. The CAD is unique across your entire program.
You do not need to be PCI compliant to receive the CAD, which means that any time you can pass the PAN in an endpoint, you can pass the CAD instead.
The CAD is called `
card_id` in Program API responses, `
cad` in the Events API webhooks, and `
CARD ID` in the RDFs.
## Lifecycle of a card
A physical card follows a lifecycle that starts with issuance and ends when the card expires or is canceled. The following diagram outlines this lifecycle:
For a virtual card, the lifecycle omits the "Emboss" and "Reissue" steps.
Issuance occurs when you choose to create a card record for a new customer. In most cases, when onboarding a new customer, you use the <a href="ref:post_createaccount" target="_blank">Create Account</a> endpoint. This endpoint creates a new customer record, a new account, and a new card.
See other use cases, such as issuing a virtual card, and the specific endpoints in the <a href="doc:card-creation-endpoints" target="_blank">Card-Creation Endpoints</a> guide.
### Card embossing
All physical cards are embossed, meaning the card material is imprinted with the card details. You must partner with an embossing vendor to print and fulfill your card orders. Galileo has integrated with several embossing vendors and will introduce you to the vendors you choose.
The embossing companies differ in their support for card characteristics such as the material used for the cards and security features. See <a href="doc:design-a-card" target="_blank">Design a Card</a> for information on how to customize the look and feel of your cards.
#### Preparation for the embosser
In most cases, new physical cards are in `
status: X` (set to emboss) upon creation. You can also manually change a card to `
status: X` using the <a href="ref:post_modifystatus" target="_blank">Modify Status</a> endpoint with `
type: 22`. An automated process in the Galileo system gathers the card information for all accounts in `
status: X` and sends it to the configured embosser. This process runs once per day in <<glossary:Production>> for most programs. In <<glossary:CV>> the process runs every 15 minutes.
An exception is a <<glossary:Digital First>> card, which is in `
status: N` (normal, active) upon creation. The internal process picks up Digital First cards for embossing even though they are not in `
status: X`. At the same time, you can present a digital image to the cardholder for use until the physical card arrives in the mail. See <a href="doc:choose-a-card-strategy#digital-first-cards" target="_blank">Digital First cards</a> in the _Choose a Card Strategy_ guide for more information.
When the automated process picks up the card for embossing, it changes the card status to `
Y` (ready to activate).
See <a href="doc:retrieving-card-information#emboss-records" target="_blank">Emboss records</a> in the _Retrieving Card Information_ guide for more information.
#### Canceling or pausing a card emboss
If you need to cancel or pause the embossing for a card, you can call <a href="ref:post_setaccountfeature" target="_blank">Set Account Feature</a> with these parameters:
startDate:` as desired; default is current date-time
endDate:` as desired; default is 3000-01-01
You can set the end date to a predetermined number of hours from the current time, or you can accept the default of the year 3000 (which is "never"). If the emboss process has not yet run, the emboss process skips the card for emboss; otherwise, it is too late to cancel or pause the emboss.
To resume the emboss process for the card, you can let the feature expire, or you can call Set Account Feature again to set feature type 30 to `
#### Card shipment
The embossing vendor is responsible for mailing cards to your customer. The card is sent to the customer’s primary address by default, which is set using <a href="ref:post_createaccount" target="_blank">Create Account</a> or other enrollment endpoint.
To ship the card to a different address from the primary address, you can pass the shipping address in the `
shipTo` fields in the <a href="ref:post_createaccount" target="_blank">Create Account</a> or <a href="ref:post_updateaccount" target="_blank">Update Account</a> 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 to ship the card via express mail. To enable express shipping you have two options:
Set the `
expressMail` parameter in the Create Account endpoint call. Verify which value to use with your emboss vendor.
After the account has been created, call the <a href="ref:post_setaccountfeature" target="_blank">Set Account Feature</a> endpoint with these parameters:
accountNo:` PAN or CAD of the card
featureValue:` Value supported by your emboss vendor.
### Card activation
A physical card is sent to the customer inactive and it must be activated before it can be used to make purchases. Follow the procedure to activate a physical card outlined in the <a href="doc:activate-card-procedure" target="_blank">Activating a Card</a> guide.
Virtual cards are activated upon creation. If a card is a <<glossary:Digital First>> card, the digital card and the physical card that arrives subsequently are active upon issuance; however, you may have protected the physical card in transit, and so you need to remove the protection as soon as the cardholder sets the PIN. See the <a href="doc:setup-for-digital-first" target="_blank">Setup for Digital First</a> guide for more information.
When a card is activated, both the emboss status and the card status are changed to `
N` (normal, active).
#### Personal identification number
Personal identification numbers (PINs) are 4-digit numbers that customers input at a point of sale or ATM to verify their identity as the legitimate cardholder. Typically, customers set their PINs as part 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, a customer can use the same PIN.
A PIN must be set for all debit cards. You can also assign a PIN to a credit card if you want, which is recommended if the card will be used in jurisdictions where a PIN is required for all card purchases, such as in most of Europe.
See <a href="doc:pin-set-procedures" target="_blank">PIN-Set Procedures</a> for more information.
### Card expires
Cards are assigned an expiration date. This date is on the card, known to the customer, and recorded in the **cards** table.
Before a card reaches its expiry date, you can arrange for Galileo to automatically reissue and ship a new card to ensure the cardholder does not have any disruption in their purchasing ability. Typically, cards that are within 30 days of the expiry date are reissued and shipped, but you can change that interval in your product settings. These reissued cards have the same PAN as the original card but a new expiry and CVV. As soon as the reissued card is activated, the original card is set to `
If you would rather reissue expiring cards yourself, follow the instructions in <a href="doc:reissuing-cards#use-case-1-reissue-card-with-same-pan-and-new-expiry" target="_blank">Use case 1: Reissue card with same PAN and new expiry</a> in the _Reissuing Cards_ guide.
As desired, you can determine that an expiring card that has not been used for a specified period will not be automatically reissued.
#### Virtual card expiry
In the case of an expiring virtual card, ask Galileo to send you the <a href="ref:api-reference-events-api-card-expiring" target="_blank">`
RBEX: card_expiring`</a> event webhook to notify you that a card is expiring. When you receive the webhook, use <a href="ref:post_addcard" target="_blank">Add Card</a> to create the replacement virtual card. A virtual card cannot be reissued, and so a net-new card with a new PAN is generated.
After initially issuing a card to a customer, you might need to manually reissue a new version of their card, such as when it is damaged. Consult the <a href="doc:reissuing-cards" target="_blank">Reissuing Cards</a> guide for a list of circumstances when you would reissue a card, along with the procedure to do so.
### Card cancelation
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 <a href="doc:lost-stolen-or-damaged-cards" target="_blank">Lost, Stolen, or Damaged Cards</a> for the latter cases.
These three statuses indicate that a card cannot be used:
**C** — Canceled. 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** — Canceled without refund. ("Without refund" refers to the account.)
To cancel a card use the <a href="ref:post_modifystatus" target="_blank">Modify Status</a> 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 Canceled||5||no change||`||Changes the card to `|
|Deactivate account and cancel card(s)||13||`||`||Changes both the account and associated cards to `|
|Account deactivated and card(s) canceled through the Galileo API||16||`||`||Changes both the account and associated cards to `|
|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 `|
#### Returning a canceled card
As desired, you can ask cardholders to return cards that they have canceled before they can get a refund for the remaining funds. Set the CRCHK parameter for refund checks to require a returned card.