Upgrade Guide for Unaric Payments
This guide explains how to manage and upgrade Unaric Payments in a Salesforce Sandbox.
Use this guide if you are:
- Refreshing your Salesforce Sandbox
- Upgrading Unaric Payments in Sandbox before a Production upgrade
- Moving across multiple Unaric Payments versions
- Checking whether version-specific changes apply to your org
Prerequisites
Pre-upgrade checklist
Use this checklist before making any changes:
Identify your current Unaric Payments package version and the target version you want to install
Review release notes for every version in the upgrade path
Confirm whether your Sandbox has been refreshed recently
Decide whether to reuse your existing Unaric Payments Sandbox Customer ID or create a new one
Check whether any version-specific upgrade considerations apply to your org. At minimum, you should assess:
Permissions and permission sets
Record types
Merchant Group configuration
Multi-Merchant behaviour
Page layouts and object fields
Dashboards
Paypage behaviour
PSP connection setup
Any customisations tied to older object or field names
Confirm whether you are using Merchant Groups (upgrading from multi-merchant), Certinia or Outbound payments for specific upgrade steps
Plan time for post-upgrade validation and testing
Best practices
- Always perform and test upgrades in Sandbox first
- Review all release notes between your current and target versions
- Upgrade in manageable steps where possible
- Complete the full testing checklist before promoting to Production
- Notify Unaric Payments Support after each Sandbox upgrade with:
- your Sandbox Customer ID
- your installed package version
1. Refresh your Salesforce Sandbox
To learn how to refresh your sandbox, see Refresh Sandbox. For details on setting up the sandbox post-refreshing, see Post-Refresh Sandbox Configuration.
Reuse an existing Sandbox Customer ID
When you refresh your Salesforce Sandbox, you can either create a new Unaric Payments Sandbox Customer ID or reuse an existing one. Reusing the existing Customer ID will preserve its Sandbox configuration, including:
- Customised paypages
- Merchant Groups
- Test Payment Service Provider (PSP) connections
There is a 1:1 relationship between your Salesforce Sandbox Org ID and your Unaric Payments Customer ID. If your Sandbox Org ID changes as part of the refresh, this must be considered when managing the associated Unaric Payments Sandbox setup.
2. Upgrade Unaric Payments in Sandbox
For Sandbox installations, ensure your installation URL domain is test.salesforce.com instead of login.salesforce.com.
Salesforce does not support package rollbacks. For that reason, all upgrades should be completed and fully tested in Sandbox before Production. There are two supported upgrade approaches.
The simplest route is to install the latest supported Unaric Payments version from the Salesforce AppExchange:
We strongly recommend upgrading no more than 4–5 versions at a time to ensure you can review all intermediate changes and considerations.
Required after each upgrade
If you are upgrading from versions prior to 2.18, notify Unaric Payments Support with:
- your Sandbox Customer ID
- the installed package version
This allows the Unaric Payments team to align support you with any of the older version changes requiring back office support.
3. Release notes and upgrade review
Before upgrading, review the release notes covering the full path from your current version to your target version. Releases may include:
- New features
- Behaviour changes
- Configuration changes
- Permission updates
- Object or field changes (including field names or new fields)
- Compatibility considerations
Review every release in between, especially if you are moving across multiple versions.
If you use Certinia (formerly FinancialForce) with Unaric Payments, confirm that you are using the recommended compatible package versions before upgrading. To learn this, see Certinia Integration.
Version-specific upgrade considerations
The following version changes are particularly important to review when planning your upgrade path.
For a full list of changes, see Release Notes.
Version | Why this matters | Action required | Affects |
|---|---|---|---|
2.13 | Merchant Groups introduced | Review Merchant Groups setup and usage | Clients using merchant segmentation |
2.15 | Validation rule introduced affecting Multi-Merchant record creation | Check whether Multi-Merchant users can create records after upgrade | Multi-Merchant clients |
2.17 | Data Integrity Token (DIT) introduced | Review whether custom permissions need to be updated | Clients with custom permission models |
2.18 / 2.18.1+ | Record type changes following outbound (Supplier/Vendor) payments | Add the correct Record Type to existing Unaric Payments users’ profiles; review outbound payment record types | Clients using Unaric Payments users, especially with outbound payments |
2.19 | Dynamic Dashboards introduced | Review dashboard behaviour if step-upgrading through 2.19 | Clients step-upgrading through 2.19 |
2.21 | Merchant Group field changes and Unaric Payments object naming changes | Since Merchant Groups is now a picklist, add the new picklist field in Object Manager if upgrading from earlier versions; review references to object names now prefixed with “Unaric Payments” | Clients upgrading from pre-2.21 versions |
2.37 | All references to Asperato have been replaced with Unaric Payments. | Unaric Payments object names are now prefixed with “Unaric Payments”, so any references or assumptions based on older naming should be reviewed | Clients upgrading to this version, Certinia clients |
4. Testing after upgrade
After the upgrade is complete, testing should include:
Card payment flow testing
Direct Debit payment flow testing
PSP connection testing
Paypage rendering checks
Error handling and logs
Reconciliation of expected outcomes in Salesforce records and objects
For complete testing guidance, see Sandbox Installation & Testing.
Do not promote to Production until the Sandbox upgrade has been validated end-to-end.
Contact support
Contact Unaric Payments support when:
- You are unsure which upgrade path is best
- You are moving across multiple versions and want the key considerations highlighted
- You have refreshed your Sandbox and need Customer ID guidance
- You have completed an upgrade and need the back-office components aligned
If you reach support, provide:
- Your current version
- Your target version
- Your Sandbox Customer ID
- Confirmation of the installed package version after upgrade