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.
  • The new and old products must be of the same general type. For example, a spending product should be changed to another spending product and a savings product to another savings product. Although it is technically possible, if you switch to an incompatible product type—such as a spending product to a savings product—you will get unexpected and undesirable results.
  • If both the new and old products have cards, both cards must have the same BIN. If they do not, follow the Switching Products with Different BINs procedure.

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.

  • Switch Product endpoint — Use the endpoint variables in Switch Product to control whether to reissue or replace the card, as well as whether to generate a new PAN and expiry. If you already have product parameters such as NOISS and STOCK set up, you can still use this endpoint to override those settings. Go to Using the Switch Product endpoint for instructions.
  • 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.
  • Set Account Feature endpoint — Set product parameters to control whether a product switch triggers a reissue and whether a new expiry should be generated. 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 sequence of events where variation is not desired. If you are not already using this method, Galileo strongly recommends using the Switch Product endpoint instead. For instructions on using this method, ask Galileo for the Switching Products with Set Account Feature PDF.
  • 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), ask Galileo for the Switching Products with Set Account Feature PDF. Also contact Galileo for information on batch-file formatting.

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: prod_switch 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 to C or D.
  • 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 CVCV - Client Validation. A test environment where you can test your implementation before moving it to Production. but only once per day in ProductionProduction - The live Galileo environment where real transactions are performed. (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 webhooks 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 webhook for card reissue or replacement.

📘

Note

A reissue is represented in the CSTCST - Customer Service Tool. Software that the Galileo customer service team uses, which is also available to providers, to view and manage customers and their accounts. 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.

ParameterDescription
CANCSUsed 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
CANOCWhen this parameter is set to Y and a new PAN is generated, cards that have the same program ID and cardholder as the newly activated card—and that have statuses specified in CANCS—are changed to status C (canceled) when the new card is activated.

When this parameter is not set, other active cards are not canceled. This parameter must be set at the program level to cancel cards with different product IDs.

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.

ParameterDescription
prodIdRequired. The product ID of the product to switch to.
doReissuePass Y to reissue the card. When this value is Y then emboss: Y is required.
newPanPass Y to generate a new card with a new PAN. When this value is Y then newExpiryDate: Y is required.
newExpiryDatePass Y to generate a new expiry date for the card.
embossPass Y to emboss a physical card for the new product. When this value is Y then doReissue: Y is required.
oldCardStatusSpecify 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 casedoReissuenewPannewExpiryDateembossoldCardStatus
1: Product switch onlyN or blankN or blankN or blankN or blankblank
2: Reissue, same PAN and expiryYN or blankN or blankYblank
3: Reissue, new expiryYN or blankYYblank
4: Replace cardYYYYC, D or blank

Switch Product workflow

  1. Galileo receives the Switch Product endpoint request.
  2. Galileo performs these checks:
    • The current product ID and the new product ID (prodId) must be different. If they are not, Galileo returns 590-01.
    • The new product ID must exist. If it does not, Galileo returns 590-02.
  3. Galileo checks the value of doReissue:
    • Y — Galileo checks the value of emboss.
      • Y — The card is flagged for reissue and emboss.
      • N or blank — Galileo returns 590-08.
    • N or blank — Galileo checks the rest of the parameters.
      • One or more is populated — Galileo returns 590-08.
      • All are N or blank and oldCardStatus: blank — Galileo changes the product ID to the value of prodId, returns status: 0 (success), sends the PSWC: prod_switch event webhook, and the process ends.
  4. Galileo checks the value of newPan:
    • Y — Galileo checks the value of newExpiryDate:
      • Y — Galileo sets a flag for a new PAN for a net-new card.
      • N or blank — Galileo returns 590-11
    • N or blank — Galileo assigns the old PAN to the reissued card.
  5. 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 when doReissue: Y and emboss: Y.
    • N or blank— Galileo assigns the old expiry date to the reissued card. This value is valid only when newPan is not Y.
  6. Galileo checks the value of oldCardStatus.
    • C or D — Galileo checks the value of newPan:
      • Y — Galileo sets a flag for the old card status to change
      • N — Galileo returns 590-04
    • Blank — The old card is not flagged for a status change.
  7. If the reissue fee (REI) is configured, Galileo attempts to assess the fee.
    • If there are insufficient funds in the cardholder account, Galileo returns 590-09.
    • If there is another problem with assessing the fee, Galileo returns 590-10.
  8. Galileo changes the product ID to the value of prodId, returns status: 0, and sends the PSWC: prod_switch event webhook.

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 AVSAVS - Address verification service. An authentication method whereby the merchant submits a card's billing address in an authorization request. 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.

  1. 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 webhook.
    • If newPan: Y and oldCardStatus is C or D, changes the old card to that status.
    • If the reissue fee (REI) is configured, assesses the fee and sends the BFEE: fee event webhook.
  2. The emboss vendor creates the card and mails it to the cardholder.
  3. The cardholder activates the new card in one of these ways, according to your setup:
    • IVRIVR - Interactive voice response. A telephone-answering system that can recognize caller speech and touch-tone input. Galileo offers an IVR for customers to activate their cards and set their PINs.
    • Activate Card endpoint
    • CSTCST - Customer Service Tool. Software that the Galileo customer service team uses, which is also available to providers, to view and manage customers and their accounts.
  4. If the card has a new PAN, then the PIN must also be reset using your preferred method.
  5. When you receive notification that the card has been activated (BACT: card_activated event webhook), 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 not Y, the old card is still active. Call Modify Status with these parameters:
      • accountNo: CAD or PAN of old card; do not use PRN
      • type: 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 webhook, 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

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.

  1. Call Switch Product with these parameters:
    • prodId: 6666
    • doReissue: N or blank
    • newPan: N or blank
    • newExpiryDate: N or blank
    • emboss: N or blank
    • oldCardStatus: blank
  2. Galileo returns prod_id: 6666 and sends the PSWC: prod_switch event webhook.

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 the Digital First Program. 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 do 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.

  1. Call Switch Product with these parameters:
    • prodId: 4444
    • doReissue: Y
    • newPan: N or blank
    • newExpiryDate: N or blank
    • emboss: Y
    • oldCardStatus: blank
  2. Galileo returns prod_id: 4444 and sends the PSWC: prod_switch event webhook.
  3. 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 or 21
    • featureValue: Y
  4. The emboss process:
    • Creates an emboss record with prod_id: 4444 and status: 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 webhook.
  5. The physical card is embossed and mailed to the cardholder.
  6. The cardholder activates the card using your preferred method and Galileo sends the BACT: card_activated event webhook.
  7. Because the PAN is the same, the cardholder does not need to reset the PIN.
  8. 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 CAD
    • featureType: 20 or 21
    • 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.

  1. Call Switch Product with these parameters:
    • prodId: 8888
    • doReissue: Y
    • newPan: N or blank
    • newExpiryDate: Y
    • emboss: Y
    • oldCardStatus: blank
  2. Galileo returns prod_id: 8888 and sends the PSWC: prod_switch event webhook.
  3. Because the new card has a different expiry date, you do not need to protect it in transit.
  4. The emboss process performs these steps:
    • Creates an emboss record with prod_id: 8888 and status: 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 webhook.
  5. The physical card is embossed and mailed to the cardholder.
  6. The cardholder activates the card using your preferred method, and Galileo sends the BACT: card_activated event webhook.
  7. 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 to C or D.
  • Cancel when the new card is activated — Leave oldCardStatus blank.
  1. Call Switch Product with these parameters:
    • prodId: 2222
    • doReissue: Y
    • newPan: Y
    • newExpiryDate: Y
    • emboss: Y
    • oldCardStatus: C, D or blank
  2. Galileo returns prod_id: 2222 and sends the PSWC: prod_switch event webhook.
  3. Because the new card has a different PAN, you do not need to protect it in transit.
  4. 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 and status: 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. If oldCardStatus is blank, no change is made.
    • Sends the SHIP: card_shipped event webhook.
  5. The new card is embossed and mailed to the cardholder.
  6. The cardholder activates the card using your preferred method, and Galileo sends the BACT: card_activated event webhook.
  7. Because the PAN is new, the cardholder must reset the PIN using your preferred method.
  8. If oldCardStatus was blank and CANOC is not Y, then the old card is still active. Call Modify Status with these parameters:
    • accountNo: PAN or CAD of old card; do not use the PRN
    • type: 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.

Switch Product status codes

Status codeDescriptionNext steps
590-01Product cannot be switched to same productVerify that prodId is different from the account's current product ID.
590-02Product cannot be switched to an invalid productVerify that prodId is a valid product ID.
590-03Product has been successfully switched but card reissue failed: The valid values for newPanFlag and newExpiryDate include Y/NVerify that newPanFlag and newExpiryDate are set to Y, N or blank
590-04Product has not been successfully switched and card reissue failed: Trying to update card status without requesting new PANIf newPan is N or blank then oldCardStatus must be blank.
590-05Product has been successfully switched but card reissue failed: The valid values for oldCardStatus include D/CVerify that oldCardStatus is set to C, D or blank.
590-06Product has been successfully switched but card reissue failed: Trying to update card status without requesting new PANIf newPan is N or blank then oldCardStatus must be blank.
590-07Product has been successfully switched but card reissue failed: Failure getting data associated with account/card. (Cannot retrieve CAD, ENP or product ID.)Contact Galileo for troubleshooting.
590-08Product has been successfully switched but card reissue failed: Failure getting data associated with account/card. (CAD or XID is null.)Contact Galileo for troubleshooting.
590-09Product has been successfully switched but card reissue failed: Insufficient funds to cover reissue feeFollow your business process for this use case.
590-10Product has been successfully switched but card reissue failed: Failure, generic error processing reissue fee.Contact Galileo for troubleshooting.
590-11If new_pan='Y' then new_expiry_date needs to be 'Y' tooVerify that newExpiryDate: Y when newPan: Y.
590-12Product has been successfully switched but card reissue failed: card has pending reissue records. There is an emboss record in status: Y with the same product ID as the new product ID.

This is a common status during testing when switching the same account repeatedly between products.
If the existing emboss record is the desired emboss record, take no action. That card will be sent to the cardholder.

If you are testing, call Activate Card to activate the existing emboss record and then try again.

Did this page help you?