Why Upgrade? #
Over the years Chargent has released various fixes, updates, and new features. As we move forward, we want to ensure that all of our customers are on the most current version of Chargent. Upgrading will also make sure that Chargent continues to work with the most current versions of Salesforce.
To help you upgrade from versions earlier than Chargent 5.20, we have put together a list of things to look for and help guide you through the process.
Test in the Sandbox First #
Chargent always recommends upgrading in your Sandbox first. Your Production Org will process real credit card transactions. Testing in Sandbox will allow you to verify compatibility with your Salesforce customizations without jeopardizing your data. This will help prevent any damage to the existing data or accidentally processing erroneous charges to your customers. That is why it’s always important to update and test in your Sandbox first.
Once everything is upgraded and tested thoroughly in Sandbox, we also recommend running a live transaction (with a real credit card) from the Sandbox to test. To do this you will need to use the endpoint override field, which you can find information about on the configuration documentation Chargent provides specific to your payment gateway.
Update Using the PIM #
You should always use the Chargent Package Installation Manager (PIM) on the AppFrontier website to upgrade. Upgrading using the PIM selects the correct versions of Chargent for your setup, and ensures you are on the most current version of Chargent.
Card Security Code (CSC) Wizard #
In version 5.20 Chargent released the CSC Wizard. The CSC Wizard was designed to walk you through removing the CSC field and it’s data from your Salesforce Org. This was done to help make your Salesforce Org more PCI Compliant. If you are upgrading from a version prior to 5.20 you will need to be aware of a few things.
- Tokenization should be enabled if you are processing recurring payments. If you are not currently using tokenization with Recurring Billing then removing the CSC field could cause some payments to decline. You should make sure you have tokenization enabled and it is working as expected prior to the upgrade.
- The CSC field can be required in both your gateway portal as well as in the Gateway record in Chargent. When you upgrade you want to make sure this is disabled from both. To disable the CSC in the Chargent Record you can navigate to the gateway, edit the page, select Advanced Settings, and uncheck the “Require Security Code” box. On the Gateway side, log in to your gateway web site to check any settings there.
Do you have Rules, Processes or Code that use the CSC field? #
Since Validation Rules can often prevent records from being saved when the data is not there, you should check over any Validation Rules that may rely on the CSC field. Processes in Process Builder and Apex Code have a similar result so you should make sure there isn’t a process or code that could potentially break by removing the CSC field. Remember the field will no longer exist after the upgrade to 5.20, so anything that relies on that field will also break.
Validation Rule Needs to Be Deleted #
Some people who are upgrading from an earlier version of Chargent may get the following message:
There is a validation rule(s) that needs to be deleted in order to move to the next step. (We wanted to do this for you but, alas, we are unable)
This error message happens when you are trying to upgrade your Chargent package from one that was prior to 5.20. Since there is a Validation Rule that uses the Card Security Code (CSC) you need to delete the CSC field from the Validation Rule.
Manually remove the validation rule(s) on the following setup page(s) in your Salesforce instance.
- Click Setup
- Object Manager
- Chargent Order
- Fields & Relationships
- Click on ‘Card Security Code’ field
- Scroll to Validation Rules section
- If a Validation Rule is present
- Click ‘Del’ next to the rule
- When asked ‘Are you sure?’ Click OK button
You can now continue the upgrade process.
Card Security Code Popup #
After upgrading, when processing a payment from the Payment Console or Payment Request, there will be no change. If you are processing a payment from the Chargent Order or Opportunity record, you will see a new popup window asking for the CSC to be entered, but it will not be stored.
You may see a message in the popup window when processing a credit card saying a “CSC is Required”. We recommend using tokenization and disabling the Require Security Code box from your Gateway settings. When this setting is disabled, your staff can either enter the card security code or not.
We recommend enabling tokenization with your payment gateway, if you are not already using it. Tokenization allows you to store a token corresponding to the payment information stored at your payment gateway, for use in recurring billing or future charges, without needing to store sensitive payment information in Salesforce.
In newer versions of Chargent, when the “Charge” or “Authorize” button is clicked, a popup window will ask for the Card Security Code to send to the payment gateway.
This is purely optional and no information should need to be entered, unless you have the “Require Card Security Code” checked on the Gateway record in Salesforce. For most use cases, this field should not be checked.
If you are seeing any issues with your testing, you may be able to adjust Card Security Code verification settings with your Payment Gateway. Most payment gateways allow you to adjust settings related to the Card Security Code including whether it is needed and validated.
Upgrading in Classic #
For those who are still using Salesforce Classic, you can still upgrade to the most current version the same way as Lightning users.
In version 5.0 Chargent became Lightning Ready. Since Salesforce is eventually going to switch all users to Lightning we encourage you to consider moving to Lightning soon. In addition, many new Chargent features are only available in Lightning.
If you are interested in upgrading to Lightning, make sure of the following items.
- You are on version 5.0 or newer of Chargent
- My Domain is setup in your Salesforce Lightning Org
- There is a time delay from registering My Domain to deployment that needs to happen so the completion of this step could take up to 24 hours.
- Chargent Components are on the Page (Salesforce no longer uses the old buttons)
- The Page is Activated
Error Messages #
When upgrading from older versions of Chargent, you may encounter an error when installing. If you encounter an “Install Script Exception” error, please look at the following solution.
- Open the Chargent Settings tab
- Navigate to “Advanced Settings” sub-tab
- Click “Save” button (no need to change or enter any values)
You should then be able to continue updating the Chargent packages.
Upgrade Tips #
If you are upgrading from an older version of Chargent, here are some tips to consider:
1. Upgrade in Sandbox first, and test!
You should test all of your current payment flows, ideally as both an Admin but also logged in as an end user.
2. Upgrade in Production
Run all of the same tests, and make sure you run a live transaction — either a customer transaction you have prepared for the switch, or use your own credit card and void it afterwards.
UPGRADE TIPS:
Tip 1: If you are using Payment Request, in Sandbox you have to make sure that the PR site URL matches the URL on the Chargent Settings or all your links will show as expired.
Site URL: Setup > Sites > Payment Request Site > Site URL
Match Here: Chargent Settings > Advanced Settings > Salesforce Sites Page URL
Tip 2: If upgrading from Chargent versions prior to 5.55, there will be some additional VF and Apex to add to your Chargent User profile permissions (just look for things with the word Chargent they do not have access to). You can also add the new Chargent Permission Sets to those users.
