Setting Up a Card Program

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.

Related documents:

• Choose a Card Strategy — How to choose which card to issue and when
• Card-Creation Endpoints — 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 Networks 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 Choose a Card Strategy for more information.
• Whether to charge a fee for issuing, reissuing or replacing cards
• How your cardholders will activate their cards and set their PINs
• Number of years until the card expires
• Whether to generate PANs 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.)

📘

Note

See About Accounts for more information about cards and accounts.

See Card-Creation Endpoints 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 Retrieving Card Information to learn more about card records and how they are created.

The card consists of the following elements, among others:

Name

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 firstName, middleName and lastName parameters in the enrollment endpoints such as Create Account.

When a cardholder's full name is longer than the name limit (as established by the embosser and other factors), Galileo uses an algorithm to determine how to display or truncate the name:

• Names on cards — Default algorithm
• Names in Latin America — Optional algorithm to accommodate Latin American naming conventions.

Primary account number

The 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 BIN, depending on the card network. The PAN is called the card_number in the API responses and CARD NUMBER in the RDFs.

📘

Note

You can receive the full PAN only if you are PCI compliant. Otherwise, you receive a masked PAN in API responses and the raw data files (RDFs).

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.

📘

Note

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 webhook messages, 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

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 Create Account 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 Card-Creation Endpoints 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.

📘

Note

The embossing companies differ in their support for card characteristics such as the material used for the cards and security features. See Design a Card 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 Modify Status 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 Production for most programs. In CV the process runs every 15 minutes.

An exception is a 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 Digital First cards 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 Emboss records in the Retrieving Card Information guide for more information.

Pausing the emboss process

If you need to pause the emboss process for a card, you can call Set Account Feature with these parameters:

• featureType: 30
• featureValue: Y
• 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 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 N.

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 Create Account 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 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 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 Set Account Feature endpoint with these parameters:
  • accountNo: PRN, PAN or CAD
  • featureType: 5
  • featureValue: Value supported by your emboss vendor

Card activation

Both the card account and the card itself must be active (status: N) for the card to be used. A physical card is typically mailed to a cardholder in an inactive state, to protect it in transit, and so it must be activated before it can be used to make purchases. A virtual card, on the other hand, is typically created in an active state.

With a Digital First card, both the digital card and the physical card are active upon creation. To protect a Digital First card in transit, you set an account feature to prevent the physical card from being used by an unauthorized user, while permitting the digital card to be used. Rather than activate a physical Digital First card, you remove the protection as soon as the cardholder receives the card and sets the PIN. See Protecting the physical card in the Setup for Digital First guide for instructions.

There are several methods for activating a card:

• Activate Card endpoint — This is the preferred endpoint for activating a physical card. The endpoint cancels old cards (if any), sets the card-activation date, updates the emboss record to active status, and sets both the account and the card to status: N (normal, active). With this endpoint you can validate the CVV, expiry date, and last four digits of the PAN, which makes this the most secure of the methods. See Activating a Card for instructions.
• Modify Status endpoint — This endpoint offers these options:
  • type: 6 — This legacy method only permits you to validate the last four digits of the PAN, and then it performs the same activation tasks as the Activate Card endpoint. Use this for physical cards only.
  • type: 7 — This method changes a card to status: N but it does not perform any of the card-activation tasks. Use this method to activate virtual cards that are not activated upon creation, and also to restore any card to status: N if it was previously in another status such as D (disabled) or C (canceled). Do not use this method to activate a new card.
• IVR — The cardholder calls a phone number and interacts with an automated phone process to activate the card. The result is the same as with the Activate Card endpoint.
• CST — Agents can activate cards in the CST. The result is the same as with the Activate Card endpoint.

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 PIN-Set Procedures for more information.

Card expires

Cards are assigned an expiration date. This date is printed on the card, is known to the customer, and is recorded in the cards table. The expiry date is expressed as the month and the year, with the card expiring on the last day of the month. Beginning at 00:00 (midnight, Galileo system time) on that last day, the card can no longer be used, so if the card's expiry is 6/26, the card's last valid day is 29 Jun 2026, and at midnight on 30 Jun 2026, the card cannot be used.

When Galileo returns the expiry_date to you in Program API responses, the day of the month is included: for example, expiry date: 2026-06-13 (because the card was created on the 13th day of the month). However, the card expires on 30 Jun 2026, not on the 13th.

Reissuance

Before a card expires, you have the option to reissue it, meaning that you create a new card with the same PAN but new expiry date and CVV. You also might need to manually reissue a card, such as when it is damaged. Consult the Reissuing Cards 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 Lost, Stolen, or Damaged Cards 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 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.

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.

Card reactivation

In some cases, you may want to return a card to status: N after it has been canceled (status: C) or changed to another non-active status.

• To reactivate a card, call Modify Status with type: 7 to change the card to status: N. This method only changes the status—it does not trigger other card-activation processes, so you should not use type: 7 to activate a card for the first time.
• If you also need to reactivate the card's account, call Modify Status with type: 11. Likewise, this method changes only the status, so it should not be used for initial activation of an account.

📘

Note

If you want to prevent non-active cards from ever being reactivated, use logic on your side to prevent cards in selected statuses from being reactivated.