--- title: Upgrade Guide for Unaric Payments slug: payments/upgrade-guide-for-unaric-payments description: Follow the upgrade guide to move to the latest version of Unaric Payments with zero downtime in Salesforce. image: https://archbee-image-uploads.s3.amazonaws.com/10Nod6Ww95R3dPr0k0TCJ/cauCYn3e8lT2eBr6_8CPo_unaric-payments.png docTags: createdAt: 2026-03-24T09:12:34.362Z --- This guide explains how to manage and upgrade Unaric Payments in a Salesforce Sandbox. :::hint{type="info"} **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 :::hint{type="success"} - 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](docId:1RXVEfnvFhIUlWT_5SXfR). For details on setting up the sandbox post-refreshing, see [Post-Refresh Sandbox Configuration](docId\:B2pXtdAJ92D_8txmBidqJ). ### 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 :::hint{type="info"} 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 :::hint{type="danger"} 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. :::::Tabs ::::Tab{title="Upgrade to the latest version"} The simplest route is to install the latest supported Unaric Payments version from the Salesforce AppExchange: :::CtaButton{label="Unaric Payments App Exchange listing" externalHref="https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3A00000EcrOnUAJ" openInNewTab="true"} ::: :::hint{type="warning"} We strongly recommend upgrading **no more than 4–5 versions at a time** to ensure you can review all intermediate changes and considerations. ::: :::: :::Tab{title="Upgrade sequentially"} Upgrading in incremental versions can help you test if any contain breaking changes related to your org or any customisations you may have. Our support team can advise if you need additional details. If you need to install a version that is not the current latest release, use the installation links provided in the relevant release notes or ask them to support at [support@unaric.com](mailto\:payment-support@unaric.com). ::: ::::: ### 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 :::hint{type="warning"} Review every release in between, especially if you are moving across multiple versions. ::: :::hint{type="danger"} 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](docId\:gUw7YO-ycqDEQA2_k8Dz0). ::: ### Version-specific upgrade considerations The following version changes are particularly important to review when planning your upgrade path. :::hint{type="info"} For a full list of changes, see [Release Notes](https://docs.unaric.com/payments/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](docId\:qMPpUk9rKjuswRJL_uCjb). :::hint{type="warning"} Do not promote to Production until the Sandbox upgrade has been validated end-to-end. ::: ## Contact support [Contact Unaric Payments](mailto\:payment-support@unaric.com) 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