Retrieving Card Information

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.

Related guides:

• Setting Up a Card Program — General explanation of the card lifecycle
• Choose a Card Strategy — How to decide which cards to issue and when
• Design a Card — 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 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 Card Statuses 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 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:

• A new card account is created using the Create Account, Add Account, Create Virtual Card Account, Add Card or Complete Enrollment endpoint.
• A card is reissued with a new PAN with the Reissue Card or Switch Product endpoint.
• A card is replaced through the lost/stolen process.

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

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 CV. In 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 is created using the Create Account, Add Account, Add Card or Complete Enrollment endpoint.
• A physical card is reissued with a new expiry (but not new PAN) using the Reissue Card or Switch Product endpoint. (The legacy method of reissuing using Modify Status 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 lost/stolen process.

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:

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

Viewing card information

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

In the CST, you can see card information on the landing page for a card.

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.

* 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.

This method of retrieving digital card images is designed to minimize PCI compliance scope and make your review with your Qualified Security Assessor (QSA) as easy as possible. However, your PCI scope is ultimately determined between you and your QSA, so please consult with them on the implications of using this feature.

📘

Note

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:

1. Provide a digital card template to Galileo. See Digital card design in the Design a Card guide for specifications.
2. From your app or your website, retrieve a token from Galileo
3. Send the token and the image request to Galileo
4. 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 Get Access Token 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, hpSVyayQScHmhJS6_MVXT1WlsFRQoDJrRu_fi_JlX2Jo2dgg5p
• expires — The date/time the token expires, formatted as YYYY-MM-DD hh:mm:ss

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 CV environment. For Production change the cv in the URL to pd.

https://asset-[clientname].cv.gpsrv.com/asset/image?token=[token]&config=[config_id]

where:

• clientname — The name of your tenanted AWS instance
• token — The token you retrieved with the Get Access Token call
• config_id — The configuration ID that corresponds with the image to retrieve

Galileo returns the PNG or JPG binary.