--- title: "Upgrade guide — v21 to v22 — Payments" source: https://support.storeconnect.com/articles/upgrade-guide-v21-to-v22-payments type: article format: markdown site: StoreConnect Support — product and developer documentation for StoreConnect site_index: https://storeconnect.com/llms.txt docs_index: https://support.storeconnect.com/llms.txt note: Append .md to any page or article URL on this site to get its Markdown form. --- # Upgrade guide — v21 to v22 — Payments Skip this section if you are not adopting a new payment gateway or changing payment configuration, and if you do not use eWay, Latitude, SecurePay, or Vii gift cards. The guide assumes you are on the latest v21 website release. Changes that already shipped in v21 patch releases are not repeated here. ## Existing gateway changes ### Action required: The eWay preauthorization setting now takes effect This applies only if your eWay payment provider has `use_preauth: true` in its **API Options**. That setting was previously ignored for eWay, so every checkout charge was captured immediately. After the upgrade it is honored: card payments are preauthorized at checkout and must be captured before the money is taken, and capturing or releasing an eWay preauthorization from Salesforce now works. 1. Open each eWay Payment Provider record and check **API Options** for `use_preauth`. 2. If you do not want preauthorized payments, remove the `use_preauth` option before upgrading. 3. If you do, confirm your order handling captures payments, and place a test order after upgrading to see the preauthorization and capture it. See [eWay payment provider](eway-payment-provider). ### Review: eWay charges with no answer are held, not retried This applies only if you use eWay. When StoreConnect charges a cart through eWay and cannot find out whether the charge went through, the charge is recorded as unresolved instead of failed. The cart stays in payment processing, the shopper is told the payment is being checked, and another eWay charge under the same order number is refused. Every five minutes StoreConnect asks eWay again, settles declines, writes a payment for a charge eWay confirms, and holds the rest for StoreConnect support to settle. Previously a lost answer was treated as a decline and the shopper was invited to pay again, which could charge twice. eWay requests now also carry the customer's IP address, so eWay's own fraud rules see the shopper rather than the server. No configuration is needed. ### Review: Latitude web payments settle and authenticate per outlet This applies only if you use Latitude on the web store. Web purchases now use the same per-outlet mapping as the POS, `pos_outlet_api_keys`, for settlement and for credentials: a cart checkout settles to the outlet in context, and a balance payment to the order's own outlet. A dedicated web merchant can be set with `web_api_key` and `web_api_secret` in the provider's **API Options**. See [Latitude payment provider](latitude-payment-provider). ### Review: Declined Afterpay and Windcave charges are no longer recorded as paid An Afterpay capture answered with a declined status, or a declined Windcave hosted-page transaction, was previously recorded as a charge. Only approved charges are recorded now, and Afterpay captures carry a request identifier so a retried capture cannot charge twice. No configuration is needed. If you had a manual check for declined Afterpay or Windcave orders showing as paid, it can be retired. ### Review: New refund coverage Refunds can now be initiated from within StoreConnect for these additional providers: | Gateway | Notes | |---|---| | SecurePay | Full and partial refunds | | Afterpay | Refund requests now carry idempotency fields, so a retried refund is not applied twice | Review your refund process for each gateway you use. If you have manual steps for initiating refunds in the gateway's own portal, assess whether they can be replaced with the StoreConnect refund flow. See [Processing refunds for web orders](processing-refunds-for-web-orders). ## Salesforce package changes ### Review: Saved payment methods and per-product capture Customers can save a card against their contact and reuse it at checkout, and products can be sold as save-card-only or preauthorize-only using the **Payment Capture Type** field on **Product**. Saved methods are stored as `Payment_Method__c` records. Saving a payment method is supported by Stripe, Stripe ACH, and Square only. A save-card-only cart shows a **Save card** button at checkout instead of **Pay now**. An external application can also embed a hosted save-card form that stores a card for a contact without creating a cart or order. Review whether `Payment_Method__c` should appear on your **Contact** page layouts. See [Payment methods](payment-methods) and [Payment Method Object Reference](payment-method-object-reference). ### Review: Vouchers and gift cards on balance payments A customer paying an order balance through the payment link can now apply StoreConnect vouchers and Vii gift cards on the payment page, and the amount due is reduced before the remaining payment is taken. Vouchers are redeemed when the payment succeeds. If your theme overrides the balance payment page, see the template table in the E-commerce section. See [Salesforce order payment link](salesforce-order-payment-link). ### Review: Web checkout deposits Customers can pay a deposit at web checkout when the `checkout.deposit.enabled` store variable is `true`, with an optional minimum set by `checkout.deposit.minimum_percentage`. The deposit is recorded in `Checkout_Deposit_Amount__c` on **Cart** and **Order**, and the balance is collected through the existing additional payment flow. Checkout deposits are disabled for a cart that contains a product with a per-item deposit mode. See [Accept deposits for purchases](deposits). ## New payment options ### Review: PayPal Fastlane PayPal Fastlane is available as an accelerated checkout for returning PayPal customers. It is configured on the PayPal payment provider and adds its own translations and checkout step. See [PayPal payment provider](paypal-payment-provider). ### Review: Vii gift cards are applied through the vouchers component This applies only if you accept Vii gift cards. A Vii gift card is no longer a payment method with its own form at the payment step. It is applied with the vouchers component on the cart and checkout, beside StoreConnect vouchers, and on the balance payment page. The `payment_providers/vii_form` template is removed. If your theme overrides `components/checkout/vouchers` or renders `vii_form`, see the template table in the E-commerce section. ### Review: Apple Pay and Google Pay line items Apple Pay now always charges the real cart total and shows itemized lines, including shipping, discounts, tax, and surcharges, in the payment sheet. PayPal receives item amounts at the currency's precision. No configuration is needed. --- ## Follow StoreConnect - [Email Newsletter](https://storeconnect.com/c/lp-newsletter) - [LinkedIn Newsletter](https://www.linkedin.com/build-relation/newsletter-follow?entityUrn=7444956928444862464) - [YouTube](https://www.youtube.com/channel/UCngKdP2x8l1wcbAKW3tvU8g) - [LinkedIn](https://www.linkedin.com/company/storeconnect) - [X / Twitter](https://x.com/storeconnecthq) ## Popular Links - [Partners](https://storeconnect.com/partners) - [Become a Partner](https://storeconnect.com/become-a-partner) - [News](https://storeconnect.com/articles/news) - [Events](https://storeconnect.com/articles/events) - [Feature Comparison](https://storeconnect.com/how-we-compare) - [Download a free trial](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3A00000FMkeKUAT) - [Book a Demo](https://storeconnect.com/contact) ## Documentation - [Help documentation](https://support.storeconnect.com/help-documentation) - [AI agents](https://support.storeconnect.com/ai) - [Videos & tutorials](https://support.storeconnect.com/videos-tutorials) - [Developer reference](https://support.storeconnect.com/developer-reference) - [Release notes](https://support.storeconnect.com/release-notes) - [Troubleshooting](https://support.storeconnect.com/troubleshooting) - [Trust Center](https://trust.getstoreconnect.com/) - [Status Page](https://status.storeconnect.com/) ## Contact - info@getstoreconnect.com - US +1 415 745 3230 - AUS +61 2 8365 2308 100 S Ashley Dr, Suite 600-2461 Tampa FL 33602-600 USA Level 22, Sydney Place 180 George Street Sydney, NSW, 2000, AUS ## Machine-readable - [Site index for agents](https://storeconnect.com/llms.txt): curated map of the StoreConnect site in llms.txt format - [Documentation index for agents](https://support.storeconnect.com/llms.txt): full technical and product documentation map Every page and article on this site has a Markdown rendering: append `.md` to its URL. Continue in Markdown: [Help documentation](https://support.storeconnect.com/help-documentation.md) · [Developer reference](https://support.storeconnect.com/developer-reference.md) · [Videos & tutorials](https://support.storeconnect.com/videos-tutorials.md) · [Release notes](https://support.storeconnect.com/release-notes.md) --- StoreConnect Support — https://support.storeconnect.com/articles/upgrade-guide-v21-to-v22-payments