{"title":"Upgrade guide — v21 to v22 — Payments","slug":"upgrade-guide-v21-to-v22-payments","url":"https://support.storeconnect.com/articles/upgrade-guide-v21-to-v22-payments","url_markdown":"https://support.storeconnect.com/articles/upgrade-guide-v21-to-v22-payments.md","subtitle":null,"summary":"Upgrade steps for payment configuration moving from v21 to v22, covering the eWay preauthorization setting that now takes effect, unresolved eWay charges, Latitude web credentials, SecurePay refunds, saved payment methods, vouchers on balance payments, PayPal Fastlane, and the move of Vii gift cards into the vouchers component.","type":"Release_Notes","video_url":"","keywords":null,"last_modified":"2026-10-22T05:03:23+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 eWay, Latitude, SecurePay, or Vii gift cards.\n\nThe guide assumes you are on the latest v21 website release. Changes that already shipped in v21 patch releases are not repeated here.\n\n## Existing gateway changes\n\n### Action required: The eWay preauthorization setting now takes effect\n\nThis 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.\n\n1. Open each eWay Payment Provider record and check **API Options** for `use_preauth`.\n2. If you do not want preauthorized payments, remove the `use_preauth` option before upgrading.\n3. If you do, confirm your order handling captures payments, and place a test order after upgrading to see the preauthorization and capture it.\n\nSee [eWay payment provider](eway-payment-provider).\n\n### Review: eWay charges with no answer are held, not retried\n\nThis 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.\n\neWay 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.\n\n### Review: Latitude web payments settle and authenticate per outlet\n\nThis 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).\n\n### Review: Declined Afterpay and Windcave charges are no longer recorded as paid\n\nAn 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.\n\n### Review: New refund coverage\n\nRefunds can now be initiated from within StoreConnect for these additional providers:\n\n| Gateway | Notes |\n|---|---|\n| SecurePay | Full and partial refunds |\n| Afterpay | Refund requests now carry idempotency fields, so a retried refund is not applied twice |\n\nReview 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).\n\n## Salesforce package changes\n\n### Review: Saved payment methods and per-product capture\n\nCustomers 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**.\n\nAn external application can also embed a hosted save-card form that stores a card for a contact without creating a cart or order.\n\nReview 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).\n\n### Review: Vouchers and gift cards on balance payments\n\nA 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).\n\n### Review: Web checkout deposits\n\nCustomers 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).\n\n## New payment options\n\n### Review: PayPal Fastlane\n\nPayPal 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).\n\n### Review: Vii gift cards are applied through the vouchers component\n\nThis 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.\n\n### Review: Apple Pay and Google Pay line items\n\nApple 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."}