Upgrade guide — v21 to v22 — Payments
On this page
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.
- Open each eWay Payment Provider record and check API Options for
use_preauth. - If you do not want preauthorized payments, remove the
use_preauthoption before upgrading. - If you do, confirm your order handling captures payments, and place a test order after upgrading to see the preauthorization and capture it.
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.
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.
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 and 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.
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.
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.
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.
Was this article helpful?
Thanks for your feedback! It helps us improve our docs.