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.
- 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.
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.)
See About Accounts for more information about cards and accounts.
See Card-Creation Endpoints for specific use cases and their respective endpoints.
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:
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
lastName parameters in the enrollment endpoints such as Create Account.
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.
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).
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.
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 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.
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 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.
Canceling or pausing a card emboss
If you need to cancel or pause the embossing for a card, you can call Set Account Feature 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
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
expressMailparameter 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:PAN or CAD of the card
featureValue:Value supported by your emboss vendor.
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 Activating a Card guide.
Virtual cards are activated upon creation. If a card is a 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 Setup for Digital First 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 PIN-Set Procedures for more information.
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 Use case 1: Reissue card with same PAN and new expiry 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
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. 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 Reissuing Cards guide for a list of circumstances when you would reissue a card, along with the procedure to do so.
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
- 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 |
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) canceled 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 |
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.
Updated 21 days ago