{"title":"Upgrade guide — v20 to v21 — Payments","slug":"upgrade-guide-v20-to-v21-payments","url":"https://support.storeconnect.com/articles/upgrade-guide-v20-to-v21-payments","url_markdown":"https://support.storeconnect.com/articles/upgrade-guide-v20-to-v21-payments.md","subtitle":null,"summary":"Upgrade steps for payment configuration changes in v21, including multi-gateway refund support, CyberSource MLE, the replacement of Zippay v1 with ZippayAu, and the eWay API Mode value check required by the rewritten eWay integration.","type":"Release_Notes","video_url":"","keywords":null,"last_modified":"2026-08-21T07:12:35+0000","body_markdown":"Skip this section if you are not adopting a new payment gateway or changing payment configuration, and if you do not use Zippay or eWay.\n\n\n## Refund support\n\n### Review: Multi-gateway refund support\n\nv21 extends refund support to a wider range of payment gateways. Refunds can now be initiated from within StoreConnect for the following additional providers:\n\n| Gateway | Notes |\n|---|---|\n| Adyen | Full refund support added |\n| ZippayAu | Replaces legacy Zippay v1 (see below) |\n| Windcave | Full refund support added |\n| Tyro | Full refund support added |\n| PayWay | Full refund support added |\n| CyberSource | Full refund support added, including pre-auth refunds |\n\nThese gateways previously required refunds to be processed directly in the gateway's own portal or back-office system.\n\nReview your current refund process for each gateway your store uses. If you have manual steps or external processes for initiating refunds, assess whether those can now be replaced with the built-in StoreConnect refund flow.\n\n\n## Salesforce package changes\n\n### Review: New fields on Payment__c\n\nTwo new fields on `Payment__c` support the refund workflows added in this release.\n\n| New field | Purpose |\n|---|---|\n| `Linked_Payment_Id__c` | Lookup to a related `Payment__c` record, linking a refund payment to its original payment |\n| `Reason__c` | Text field recording the reason for the payment action, such as a refund reason |\n\nThese fields are populated automatically when a refund is processed through StoreConnect. Review whether they should be added to your `Payment__c` page layouts.\n\n\n## Existing gateway changes\n\n### Action required: eWay API Mode value must be lowercase\n\nv21 replaces the eWay integration with a new implementation that adds 3DS2 support, subscription payments, wallet payments (Apple Pay and Google Pay), and express checkout.\n\nThe new integration only sends payments to the live eWay environment when the Payment Provider **API Mode** field contains exactly the lowercase value `production`. Any other value, including `Production` with a capital P, causes every eWay payment to be sent to the eWay sandbox after the upgrade. When this happens, card payments fail at checkout with the message \"We were unable to verify your payment!\", and no transactions appear in your live eWay dashboard. Earlier versions accepted the value regardless of capitalisation, so a store that worked on v20 can break on v21 without any configuration change.\n\nBefore upgrading:\n\n1. Open each eWay Payment Provider record in the Web Console.\n2. Check the **API Mode** field.\n3. If the value is not exactly `production` in lowercase, change it to `production`.\n4. Repeat for every eWay Payment Provider record, including inactive ones.\n\nAfter upgrading, place a test card payment and confirm it appears in your live eWay dashboard.\n\nSee [Eway Payment Provider](eway-payment-provider) for configuration documentation.\n\n\n### Review: CyberSource Message Level Encryption\n\nCyberSource now supports Message Level Encryption (MLE), an additional layer of encryption for payment data in transit between StoreConnect and the CyberSource API.\n\nIf you use CyberSource, contact your CyberSource account manager to determine whether MLE is available for your account and what configuration changes are required on the gateway side before enabling it in StoreConnect.\n\nSee [CyberSource Payment Provider](cybersource-payment-provider) for configuration documentation.\n\n\n### Action required: ZippayAu replaces Zippay v1\n\nThe legacy Zippay v1 API integration has been replaced with ZippayAu. This affects both web store and POS Zippay configurations. Existing Zippay v1 credentials will not work after upgrading to v21.\n\n1. Contact your ZippayAu account manager to confirm your credentials are compatible with the ZippayAu API.\n2. In the StoreConnect Config app, navigate to your payment provider configuration and update your Zippay integration to use the ZippayAu provider.\n3. Test a Zippay transaction on your web store and, if applicable, at the POS to confirm the new integration is working before going live.\n\nIf you do not use Zippay, no action is needed. See [Zip Pay Payment Provider](zip-pay-payment-provider) for configuration documentation."}