This guide describes the card records that Galileo stores, as well as emboss records for physical cards, and how you can retrieve this information. This guide also includes instructions for retrieving a digital card image.
<a href="doc:setting-up-a-card-program" target="_blank">**Setting Up a Card Program**</a> — General explanation of the card lifecycle
<a href="doc:choose-a-card-strategy" target="_blank">**Choose a Card Strategy**</a> — How to decide which cards to issue and when
<a href="doc:design-a-card" target="_blank">**Design a Card**</a> — Specifications for card designs
## Card records
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 to that table. The row number is the <<glossary: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 the <a href="doc:card-statuses" target="_blank">Card Statuses</a> guide 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 often pass the CAD in an API call for `
accountNo` and it will point to the same card record as the PAN. Consult each endpoint to see if `
accountNo` accepts the CAD.
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 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 <a href="ref:program-api-intro" target="_blank">endpoint reference</a> 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 <a href="doc:pin-set-procedures" target="_blank">PIN-Set Procedures</a> for more information.
A new PAN (and therefore new CAD) is generated under these circumstances:
A new card account is created using the <a href="ref:post_createaccount" target="_blank">Create Account</a>, <a href="ref:post_addaccount" target="_blank">Add Account</a>, <a href="ref:post_createvirtualcard" target="_blank">Create Virtual Card Account</a>, <a href="ref:post_addcard" target="_blank">Add Card</a> or <a href="ref:post_completeenrollment" target="_blank">Complete Enrollment</a> endpoint.
A card is reissued with a new PAN with the <a href="ref:post_reissuecard" target="_blank">Reissue Card</a> or <a href="ref:post_switchproduct" target="_blank">Switch Product</a> endpoint.
A card is replaced through the <a href="doc:lost-stolen-or-damaged-cards" target="_blank">lost/stolen process</a>.
This table summarizes how the PAN and CAD are represented in the Galileo system.
|Program API requests||`||`|
|Program API responses||`||`|
## Emboss records
The **emboss** table stores emboss records. An emboss record is created only for physical cards, and it is created every time 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 <<glossary:CV>>. In <<glossary:Production>>, the interval of the process varies according to your 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.
A new physical card account is created using the <a href="ref:post_createaccount" target="_blank">Create Account</a>, <a href="ref:post_addaccount" target="_blank">Add Account</a>, <a href="ref:post_addcard" target="_blank">Add Card</a> or <a href="ref:post_completeenrollment" target="_blank">Complete Enrollment</a> endpoint.
A physical card is reissued with a new expiry (but not new PAN) using the <a href="ref:post_reissuecard" target="_blank">Reissue Card</a> or <a href="ref:post_switchproduct" target="_blank">Switch Product</a> endpoint. (The legacy method of reissuing using <a href="ref:post_modifystatus" target="_blank">Modify Status</a> also generates a new expiry date.)
A physical card is reissued with a new PAN (because a new PAN must have a new expiry date), using the Reissue Card or Switch Product endpoint.
A physical card is replaced through the <a href="doc:lost-stolen-or-damaged-cards" target="_blank">lost/stolen process</a>.
### 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. The `
new_embossed_uuid` field specifies which `
emboss_uuid` is the most recent.
### Card identifiers in program API responses
When you call endpoints that return card information, the card and emboss records are nested as follows:
## Viewing card information
For every new or updated card record, Galileo includes that record in the daily <a href="doc:rdf-reference#account-card-rdf" target="_blank">Account Card RDF</a>.
In the <<glossary:CST>>, you can see card information on the landing page for a card.
To retrieve card information with the Program API, use <a href="ref:post_getcard" target="_blank">Get Card</a> or <a href="ref:post_getaccountcards" target="_blank">Get Account Cards</a>. 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.
|Attribute||Get Card||Get Account Cards|
|External card ID||X||X|
|Encrypted card number||X|||
|Embossed cards object (`||X||X|
|Emboss UUID (`||X||X|
|Freeze info object (`||X||X|
|PIN fail count||X||X|
|PIN fail date||X||X|
|Cardholder date of birth||||X|
|Express mail setting||||X|
|Cardholder income source||||X|
|Account active status||||X|
|Account application date||||X|
|Bill cycle day||||X|
|Galileo account number (balance ID)||||X|
|Product ID (`||||X|
|Activation date (`||||X|
\* Only when provider parameters are set.
Open these Recipes to see examples of multiple accounts, cards and emboss records.
## Digital card images
This section describes the steps to retrieve a dynamically generated card image that displays full PAN, expiry, cardholder name, and CVV. You do not need to be PCI compliant to use this method.
Do not use this method with mobile wallets.
To present a virtual card or a digital image of a physical card in your application, follow these steps:
Provide a digital card template to Galileo. See <a href="doc:design-a-card#digital-card-design" target="_blank">Digital card design</a> in the _Design a Card_ guide for specifications.
From your app or your website, retrieve a token from Galileo
Send the token and the image request to Galileo
Present the image in your app or on your website
Galileo generates a configuration ID that corresponds to a card template and font specification, meaning if your product offers three possible templates for a card, you would have a different configuration ID for each image/font combination. You can use the same configuration ID across multiple programs as long as all programs use the same template. The configuration ID is a required parameter when you build the URL to Galileo's asset application to retrieve the generated card image—this is the `
config` parameter in the [HTTP request for the image](🔗).
To retrieve a card image you must send two requests to Galileo: a Get Access Token call and an HTTP request to retrieve the card image from Galileo's asset application.
### Get Access Token call
These parameters are required for the <a href="ref:post_getaccesstoken" target="_blank">Get Access Token</a> call:
accountNo` — Galileo recommends using the CAD (`
card_id`) or PAN, but the PRN is valid as long as only one card has ever been associated with the account.
type` — Pass `
0` to retrieve a card-related token.
The response will contain these fields:
token` — A case-sensitive alphanumeric string, for example, `
expires` — The date/time the token expires, formatted as `
The token has two properties: the expiration (default: 300 seconds) and the maximum times an access token can be used (default: 3). You can change the defaults in your program or product parameters.
**TSECV** — Controls the maximum seconds of access-token validity.
**TUSEC** — Controls the maximum times an access token can be used.
### HTTP request for the image
With the token assemble an HTTP call to retrieve the card image, as shown in the example. The URL is an AWS instance that Galileo sets up for each client. Request an AWS URL from Galileo if you do not already have one. This example is for the <<glossary:CV>> environment. For <<glossary:Production>> change the `
cv` in the URL to `
clientname` — The name of your tenanted AWS instance
token` — The `
token` you retrieved with the <a href="ref:post_getaccesstoken" target="_blank">Get Access Token</a> call
config_id` — The configuration ID that corresponds with the image to retrieve
Galileo returns the PNG or JPG binary.