Switching Products
When you create an account on the Galileo system you input a product ID, which specifies the type of account (spending, savings, overdraft) as well as specific characteristics of the account such as velocity limits or card type. At a later time you may want to change an account to a different product.
When to switch products
Switching to a new product is a good solution in these circumstances, among others:
- You have existing virtual-card customers who want a physical version instead.
- You want to switch your virtual-card customers to a Digital First product.
- You want to reward customers who fulfill certain requirements with better account features such as higher velocity limits, better fees, or fewer hold days.
- You are phasing out an old product and want to move customers to a new product.
- You are switching a customer from an instant-issue card to a personalized card.
Whether to reissue or replace
At the time that you switch to a new card product you might also want to reissue or replace the card. (See Reissuing vs. replacing in the Reissuing Cards guide to understand the difference.)
When to reissue
Reissuing a card with a product switch is desirable when:
- You are switching from a virtual-only product to a Digital First product so that you can continue to provide the virtual card while the physical card is being embossed.
- You are switching from a virtual-only card product to a physical-only card product, and you want to retain the same PAN and expiry for the physical card. (In this scenario, the virtual card is cancelled after the physical card is activated.)
- Any time you want to retain the PAN for the new card but generate a new expiry date.
When to replace
Replacing a card with a product switch is desirable when you want to issue a net-new card with a new PAN and expiry, and you want the old PAN to be deactivated.
Prerequisites for switching products
To switch products successfully, the following must be true:
- Both products must have the same program ID.
- If both the new and old products have cards, both cards must have the same BIN. If they do not have the same BIN, follow the Switching Products with Different BINs procedure.
- The new and old products must be of the same product category. For example, a spending product can be switched only to another spending product and a savings product to another savings product.
Warning
If you attempt to switch to a different product category (such as savings to spending) the endpoint might change the
prod_id
of the account without returning an error, but the account will not properly function as the new product type. For example, a savings account that is switched to a card product will not generate a card.
How to switch products
Galileo offers several methods to switch products (with or without reissue/replacement). For most use cases, Galileo strongly recommends that you use the Switch Product endpoint—it is the newer, more flexible choice that does not involve complicated product parameter setup.
- Check the product category — You have two methods to check the product category to ensure that the new
prod_id
is compatible with the oldprod_id
:- Use the Get Product Config endpoint with
section: info
to retrieve the product category. - In the GCC, open the Product Info page for each product to verify that the type is the same.
- Use the Get Product Config endpoint with
- Switch Product endpoint — Use the input parameters in the Switch Product endpoint to control whether to reissue or replace the card, as well as whether to generate a new PAN and expiry.
- This method is valid only for card products (except for secured credit); for non-card products, use Set Account Feature, as described below.
- If you already have product parameters such as NOISS and STOCK set up, you can use this endpoint to override those settings.
- Go to Using the Switch Product endpoint for instructions.
- Set Account Feature endpoint — Set product parameters to control whether a product switch triggers a reissue and whether a new expiry should be generated.
- This method is valid for both card and non-card products, except Digital First products; however, using the Switch Product endpoint is recommended for most card products.
- The old PAN is always retained.
- This method is used by legacy Galileo clients and can be used to set up a predictable product-switch and reissue sequence of events where variation is not desired.
- For instructions on using this method, see Switching Products with Set Account Feature.
- Batch processing — This method is similar to using Set Account Feature in that it uses the same product parameters that control reissue behavior.
- To see how to set the product parameters for reissue (or to prevent reissue), see Switching Products with Set Account Feature.
- Contact Galileo for information on batch-file formatting.
- Add Account endpoint — This method should be used only when switching from one card product to another card product with a different BIN.
- This method results in a new account with a new PRN, PAN, and expiry.
- See Switching Products with Different BINs for instructions.
Using the Switch Product endpoint
This section explains how to change an account's product to a new product using the Switch Product endpoint, and optionally to reissue (same PAN) or replace (new PAN) the card. With this method there are no product parameters to set to affect product-reissue behavior. If you have already set product parameters such as STOCK and NOISS, this process will not be affected by those parameter settings.
Result of calling Switch Product
When Switch Product has been called successfully, the following are true:
- The account has a new product ID.
- If you have specified that the card be reissued, the card is flagged for reissue.
- If you have specified a net-new card, the new-card flag is set.
- Galileo sends the
PSWC: product_switched
event message.
After Switch Product has finished running, automated processes complete these tasks when reissue or replacement has been requested:
- If the card is flagged to be created new, the emboss process creates a new card record with a new CAD and PAN.
- If
oldCardStatus
is set, the emboss process changes the old card status toC
orD
.
- If
- The emboss process creates a new emboss record for the card and assigns it a new expiry date and CVV.
- All emboss records are included in a batch file to send to the embosser. For each emboss record in the file, Galileo sends the
SHIP: card_shipped
event message.
The emboss process runs every 15 minutes in CV but only once per day in Production (unless you specify another interval). Because it is the emboss process that generates new PANs, expiry dates, and CVVs—not the Switch Product endpoint—you do not receive the new card data in the Switch Product response. To get the new card data, wait until after the emboss process has run (the SHIP: card_shipped
event is sent) and then call Get Account Cards.
According to your arrangements with Galileo, Galileo sends event messages to notify when the emboss record is created, when the fee is assessed (if any) and when the card is activated. There is no event message for card reissue or replacement.
Note
A reissue is represented in the CST on the Card Info screen under Reissued Card History and Emboss History.
Program parameters
These program parameters are related to card-activation behavior when using the Switch Product endpoint.
Parameter | Description |
---|---|
CANCS | Used in conjunction with CANOC, it specifies the status that a card must be in to be canceled when a new card is activated. Default: N,X,Y,W |
CANOC | When this parameter is set and the new card (new PAN) is activated, other cards in the statuses specified in CANCS and belonging to the same cardholder are canceled (status: C ):Y — Cancel all cards regardless of prod_id .Prod — Cancel only the cards with the same prod_id .When this parameter is not set, other active cards are not canceled. If you set oldCardStatus to C or D , this parameter is not checked. |
Endpoint parameters
This table explains the parameters that are specific to the Switch Product endpoint. See the Switch Product endpoint reference for details.
Parameter | Description |
---|---|
prodId | Required. The product ID of the product to switch to. |
doReissue | Pass Y to reissue the card. When this value is Y then emboss: Y is required. |
newPan | Pass Y to generate a new card with a new PAN. When this value is Y then newExpiryDate: Y is required. |
newExpiryDate | Pass Y to generate a new expiry date for the card. |
emboss | Pass Y to emboss a physical card for the new product. When this value is Y then doReissue: Y is required. |
oldCardStatus | Specify the status for the card that is being replaced. This should be populated only when newPan: Y . The new status is applied when the emboss process runs. Use D (disabled) or C (canceled). If you want the old card to be usable until the new card is activated, leave this parameter blank. Default: Blank |
Valid parameter combinations
Only these emboss-related parameter combinations are permitted. See the Use cases for how to use these combinations.
Use case | doReissue | newPan | newExpiryDate | emboss | oldCardStatus |
---|---|---|---|---|---|
1: Product switch only | N or blank | N | N | N | blank |
2: Reissue, same PAN and expiry | Y | N | N | Y | blank |
3: Reissue, new expiry | Y | N | Y | Y | blank |
4: Replace card | Y | Y | Y | Y | C , D or blank |
Note
In many cases, if you pass incorrect parameters, the product switch will be successful but the reissue will not. To recover, call Reissue Card with the proper parameters. See Status codes for more information.
Switch Product workflow
- Galileo receives the Switch Product endpoint request.
- Galileo performs these checks:
- The current product ID and the new product ID (
prodId
) must be different. If they are not, the endpoint returnsstatus_code: 590-01
. - The new product ID must exist. If it does not, the endpoint returns
status_code: 590-02
.
- The current product ID and the new product ID (
- Galileo checks the value of
doReissue
:Y
— Galileo checks the value ofemboss
.Y
— The card is flagged for reissue and emboss.N
— The endpoint returnsstatus_code: 590-08
.
N
or blank — Galileo checks the rest of the parameters.- One or more is populated — The endpoint returns
status_code: 590-08
. - All are
N
or blank andoldCardStatus:
blank — Galileo changes the product ID to the value ofprodId
, returnsstatus_code: 0
(success), sends thePSWC: product_switched
event message, and the process ends.
- One or more is populated — The endpoint returns
- Galileo checks the value of
newPan
:Y
— Galileo checks the value ofnewExpiryDate
:Y
— Galileo sets a flag for a new PAN for a net-new card.N
— The endpoint returnsstatus_code: 590-11
N
— Galileo assigns the old PAN to the reissued card.
- Galileo checks the value of
newExpiryDate
:Y
— Galileo sets a flag for a new expiry date for the reissued card. This value is valid only whendoReissue: Y
andemboss: Y
.N
— Galileo assigns the old expiry date to the reissued card. This value is valid only whennewPan
is notY
.
- Galileo checks the value of
oldCardStatus
.C
orD
— Galileo checks the value ofnewPan
:Y
— Galileo sets a flag for the old card status to changeN
— The endpoint returnsstatus_code: 590-04
- Blank — The old card is not flagged for a status change.
- If the reissue fee (REI) is configured, Galileo attempts to assess the fee.
- If there are insufficient funds in the cardholder account, the endpoint returns
status_code: 590-09
. - If there is another problem with assessing the fee, Galileo returns
590-10
.
- If there are insufficient funds in the cardholder account, the endpoint returns
- Galileo changes the product ID to the value of
prodId
, returnsstatus_code: 0
, and sends thePSWC: product_switched
event message.
Note
The
expiry_date
andcard_security_code
(CVV) that are returned by the endpoint are not the new values. The new values are generated later by the emboss process, as shown in the next section.
After the endpoint response
You may need to protect the physical card while it is in transit, but only when all of these conditions are true:
- The PAN and expiry are the same as the old card.
- The new card is a physical card.
- The old card is a virtual card.
Right after calling Switch Product, call the Set Account Feature endpoint with these values, according to your use case. Both of these options permit mobile-wallet and AVS transactions:
- Block card-present and card-not-present transactions:
featureType: 20
featureValue: Y
- Block card-present transactions only:
featureType: 21
featureValue: Y
These next steps are performed only when doReissue: Y
and emboss: Y
.
- The emboss process:
- Generates a new card record with a new CAD and PAN if
newPan: Y
. - Generates a new expiry date and CVV if
newExpiryDate: Y
. - Creates a new emboss record in
status: Y
. - Includes the emboss record in a batch file to send to the embosser.
- Sends the
SHIP: card_shipped
event message. - If
newPan: Y
andoldCardStatus
isC
orD
, changes the old card to that status. - If the reissue fee (REI) is configured, assesses the fee and sends the
BFEE: fee
event message.
- Generates a new card record with a new CAD and PAN if
- The emboss vendor creates the card and mails it to the cardholder.
- The cardholder activates the new card in one of these ways, according to your setup:
- IVR
- Activate Card endpoint
- CST
- If the card has a new PAN, then the PIN must also be reset using your preferred method.
- When you receive notification that the card has been activated (
BACT: card_activated
event message), perform these tasks, as needed:- If you put restrictions on the card using Set Account Feature, call Set Account Feature again to remove the restrictions.
- If
newPan: Y
,oldCardStatus: blank
, and CANOC is notY
, the old card is still active. Call Modify Status with these parameters:accountNo:
CAD or PAN of old card; do not use PRNtype: 5
Sample endpoint request and response
Consult the Switch Product endpoint reference to see how to build the API request and to see the response schema. Go to Switch Product status codes at the end of this guide to see how to respond to different statuses.
View the new product ID
The Switch Product endpoint returns the new prod_id
in the response. You can also retrieve the prod_id
with the Get Account Cards endpoint immediately after Switch Product responds.
View the new card information
Because the emboss process generates new PANs, CADs, expiry dates and CVVs after the Switch Product endpoint is called, the Switch Product endpoint cannot return that data. After you receive the SHIP: card_shipped
event message, you can retrieve the new information using Get Account Cards or Get Card. You can see the new PAN, CVV and expiry only if you are PCI compliant.
Use cases
Use the Switch Product endpoint for these use cases:
- Use case 1: Product switch without reissue — Use this method for a simple product switch without producing a new card. If the products being switched do not have cards, such as savings accounts, go to Switching Products with Set Account Feature.
- Use case 2: Product switch and reissue with same PAN and expiry — Use this method to switch a virtual card to a physical card with the same PAN and expiry or to switch to a Digital First product. Can also be used when both products are virtual.
- Use case 3: Product switch and reissue with same PAN and new expiry — Use this method when you want to reissue the card with the new product but do not want a new PAN. This method is best when both cards are physical.
- Use case 4: Product switch and issue with new PAN and expiry — Use this method to issue a new card for the new product with a new PAN and then deactivate the old PAN.
Use case 1: Product switch without reissue
The cardholder has a virtual card (product ID 5555) and wants to upgrade the card to another virtual card (product ID 6666). Because the new card is a virtual card, it cannot be reissued. Use this method for any product switch—physical card, virtual card, or non-card account—when a new card is not possible or not desired.
- Call Switch Product with these parameters:
prodId: 6666
doReissue: N
or blanknewPan: N
newExpiryDate: N
emboss: N
oldCardStatus:
blank
- Galileo returns
prod_id: 6666
and sends thePSWC: product_switched
event message.
End result
The account has product ID 6666. No card or emboss records were created or modified.
Use case 2: Product switch with reissue and same PAN and expiry
If you want to offer a virtual version of a card that cardholders can use until the physical version of the card is shipped, use Digital First cards. You can switch to a Digital First product using this example. You can also switch existing virtual-only card holders to a physical-only card using this process.
Warning
Galileo strongly recommends that you not switch from one physical card to another physical card while retaining both the PAN and expiry, because the new physical card would be unprotected in transit—to protect it, you would have to set account feature 20 or 21, and that would affect the existing card, making it mostly unusable. Instead, go to Use case 3 to set a new expiry date for the new card.
The cardholder has a virtual card (product ID 3333) and wants to upgrade to a physical card (product ID 4444). The physical card will have the same PAN and expiry date as the virtual card. The virtual card will be usable until the physical card is activated.
- Call Switch Product with these parameters:
prodId: 4444
doReissue: Y
newPan: N
newExpiryDate: N
emboss: Y
oldCardStatus:
blank
- Galileo returns
prod_id: 4444
and sends thePSWC: product_switched
event message. - You need to protect the physical card in transit. (If the old card is physical, this step will block card-present transactions for the existing card.) You call Set Account Feature with these parameters:
accountNo:
PRN, PAN, or CAD. Use PAN or CAD if there are multiple active cards associated with the account.featureType: 20
or21
featureValue: Y
- The emboss process:
- Creates an emboss record with
prod_id: 4444
andstatus: Y
(ready to emboss). - Assigns the old PAN, CAD, expiry date, and CVV to the new card.
- Includes the emboss record in the batch file to be sent to the embosser.
- Sends the
SHIP: card_shipped
event message.
- Creates an emboss record with
- The physical card is embossed and mailed to the cardholder.
- The cardholder activates the card using your preferred method and Galileo sends the
BACT: card_activated
event message. - Because the PAN is the same, the cardholder does not need to reset the PIN.
- If you protected the physical card in transit, you need to lift the restrictions. Call Set Account Feature with these parameters:
accountNo:
PRN, PAN, or CADfeatureType: 20
or21
featureValue: N
End result
The account has product ID 4444. The new emboss record with prod_id: 4444
is in status: N
(active). The physical card with the same PAN as the virtual card is active.
Use case 3: Product switch with reissue and new expiry date
The cardholder has a physical card (product ID 7777) and wants to switch to another physical-card product with better features (product ID 8888). The card will be reissued with the same PAN but new expiry date. The old card will be usable until the new card is activated, and then it is canceled.
- Call Switch Product with these parameters:
prodId: 8888
doReissue: Y
newPan: N
newExpiryDate: Y
emboss: Y
oldCardStatus:
blank
- Galileo returns
prod_id: 8888
and sends thePSWC: product_switched
event message. - Because the new card has a different expiry date, you do not need to protect it in transit.
- The emboss process performs these steps:
- Creates an emboss record with
prod_id: 8888
andstatus: Y
(ready to emboss) - Assigns the same PAN to the new card.
- Generates a new expiry date and CVV.
- Includes the emboss record in the batch file to be sent to the embosser.
- Sends the
SHIP: card_shipped
event message.
- Creates an emboss record with
- The physical card is embossed and mailed to the cardholder.
- The cardholder activates the card using your preferred method, and Galileo sends the
BACT: card_activated
event message. - Because the card has the same PAN, the cardholder does not need to reset the PIN.
End result
The account has product ID 8888. The new emboss record is in status: N
(active). The new card with the same PAN but new expiry as the old card is active.
Use case 4: Product switch with new PAN and expiry
The cardholder has a physical card (product ID 1111) and wants to upgrade to a product with improved features (product ID 2222). A new card will be issued for the new product with a new PAN and new expiry date.
This scenario has two methods for canceling the old card, depending on the timing that you desire:
- Cancel shortly after switching the product — Set
oldCardStatus
toC
orD
. - Cancel when the new card is activated — Leave
oldCardStatus
blank.
- Call Switch Product with these parameters:
prodId: 2222
doReissue: Y
newPan: Y
newExpiryDate: Y
emboss: Y
oldCardStatus: C
,D
or blank
- Galileo returns
prod_id: 2222
and sends thePSWC: product_switched
event message. - Because the new card has a different PAN, you do not need to protect it in transit.
- The emboss process:
- Creates a new card record with a new CAD.
- Generates a new PAN, expiry date and CVV.
- Creates an emboss record with
prod_id: 2222
andstatus: Y
(ready to emboss). - Includes the emboss record in the batch file to be sent to the embosser.
- Changes the old card status to the value in
oldCardStatus
. IfoldCardStatus
is blank, no change is made. - Sends the
SHIP: card_shipped
event message.
- The new card is embossed and mailed to the cardholder.
- The cardholder activates the card using your preferred method, and Galileo sends the
BACT: card_activated
event message. - Because the PAN is new, the cardholder must reset the PIN using your preferred method.
- If
oldCardStatus
was blank and CANOC is notY
, then the old card is still active. Call Modify Status with these parameters:accountNo:
PAN or CAD of old card; do not use the PRNtype: 5
End result
The account has product ID 8888. There is a new card record in status: N
(active) with a new emboss record in status: N
. The old card record is in status: C
or status: D
.
Status codes
Consult the Switch Product endpoint reference for status codes and next steps. Some status codes indicate that the product was successfully switched but that the reissue failed. In most cases, it is because you did not pass Valid parameter combinations. In such a case, you cannot fix the problem by calling Switch Product again with the correct parameters, because you cannot switch to the same product. Instead, call Reissue Card with the proper reissue parameters set.
Updated about 2 months ago