1. Documentation /
  2. WooCommerce Square: Startup Guide /
  3. WooCommerce Square: Payment Settings

WooCommerce Square: Payment Settings

WooCommerce Square can be used for managing inventories and also as a payment gateway. You can configure the plugin to use either one of them or both!

This guide walks through the settings for using WooCommerce Square as a payment gateway. Before jumping into the payment settings, please make sure that your site meets these requirements and that you have connected your Square account to your site.

Payment Settings

↑ Back to top

From WooCommerce > Settings > Payment > Square, you can configure the following settings for the Square payment gateway:

  • Enable / Disable: Enable to allow customers to use this gateway at checkout.
  • Title: Determine how the gateway should be labeled for customers at checkout and on the Order Received page.
  • Description: The text shown under the Title during checkout. Limited HTML is allowed.
  • Transaction Type: Controls how transactions are submitted to Square. Select “Charge” to automatically capture payments. If you select “Authorization”, you must manually capture and settle payments on the WooCommerce orders screen or from your Square account after the transaction has been submitted (and Authorizations do not display under Square transactions). This defaults to “Charge”.
    Note that Square authorizations are only valid for 6 days, so they cannot be captured after this time.
  • Charge Virtual-Only Orders: If Transaction Type is set to “Authorization”, enable to automatically capture charges for orders with only Virtual products. For downloadable products, this will grant immediate access to downloads.
  • Capture Paid Orders: If Transaction Type is set to “Authorization”, enable to automatically capture charges when orders move to a paid status (i.e. Processing or Completed).
  • Accepted Card Logos: This doesn’t determine which cards are accepted, only which card logos are shown during checkout. See the cards Square accepts.
  • Customer Profiles: Customers can save their payment methods for future use at checkout. This is required for Subscriptions and Pre-Orders.
  • Digital Wallet Settings: Enable/disable and customize Square digital wallets (Apple Pay and Google Pay) on your store. These settings will only be available when the following conditions are met:
    • The store’s base location should be in the US, UK, CA, IE, FR, ES or AU
    • The store must use SSL (HTTPS)
    • The store’s base currency should be any one of the following: ‘USD’, ‘GBP’, ‘CAD’, ‘EUR’, or ‘AUD’.
  • Detailed Decline Messages: Display detailed messages to customers to provide reasoning for declines instead of a generic error message when possible.
  • Debug Mode: Enable when there are problems processing transactions. You can choose to log API requests directly on the checkout page, save them to the WooCommerce > Status > Logs page, or both.

Digital Wallets

↑ Back to top

Take payments across your store with Apple Pay and Google Pay (available to Square accounts located in the United Kingdom, United States, Canada, Ireland, France, Spain, and Australia).

When digital wallets are enabled, Apple Pay and Google Pay buttons will be displayed on the Product, Cart, and Checkout pages, depending on which is available to the customer.

Screen Shot on 2021-02-02 at 11-22-09.png
Product page with Square digital wallets enabled.

Apple Pay Setup

↑ Back to top

To start accepting payments with Apple Pay your store’s domain must first be verified with Square and Apple. When you enable Digital Wallets in the gateway settings (found WooCommerce > Settings > Payments > Square) we will automatically verify your store’s domain for you.

To check if your domain has been properly verified:

Production Mode

  1. Make sure Square logging is enabled in WooCommerce > Settings > Square.
  2. With logging enabled, visit your Square settings page or your Square payment method settings page (loading either of these pages will try to verify your domain with Apple Pay)
  3. Go into your latest Square log to confirm Apple Pay has been verified.
Screen Shot on 2021-02-10 at 15-18-05.png

If there was an error, search your log file for “Unable to verify domain” and you should find the reason. Here’s an example of what an error looks like:

Screen Shot on 2021-02-10 at 15-20-37.png

If your store has already been successfully verified before logging was enabled, you may not see any logs similar to the above. If this is the case, come back in a few hours and try these steps again.

Sandbox Mode

  1. Log into your Square Developer Dashboard (https://developer.squareup.com/)
  2. Open the application which connects your Square account and Woo
  3. On the side panel, click on Apple Pay
  4. Make sure you’re viewing the correct environment (sandbox/production)
  5. Confirm your store is found on the list of verified domains
Screen Shot on 2021-02-10 at 14-56-44.png

To see the Apple Pay buttons on your store, you must be viewing your site from a supported Apple device, browser and have a valid card in your Apple wallet. You can find a list of supported Apple devices here.

Google Pay Setup

↑ Back to top

To accept payments with Google Pay, make sure that digital wallets are enabled in your Square settings (WooCommerce > Settings > Payments > Square).

For customers on Android devices, the Google Pay app must be installed.
For computer/desktop users, you must have a supported payment method available on your google account. Visit https://pay.google.com/ to add or edit your payment methods on your account.

Digital Wallet Settings

↑ Back to top

When Square’s digital wallets are available to your store (US, UK, CA, IE, FR, ES and AU), you’ll see the following options in your gateway settings:

Button Type – Changes the button text on the Apple Pay button.
Apple/Google Pay Button Color – Changes the color of the Apple Pay and Google Pay buttons separately.

Apple Pay button color options are:

  • Black
  • White
  • White with outline

Google Pay button color options are:

  • Black
  • White
Screen Shot on 2021-01-14 at 15-03-38.png

When choosing a button color or customizing the buttons with custom CSS, please make sure to follow the Apple Pay and Google Pay brand guidelines.

Hide Digital Wallet Buttons – Allows you to remove the Apple Pay or Google Pay buttons from being displayed.

Note that you must have a compatible device and payment method in a supported region, otherwise, the Apple Pay and Google Pay buttons will not show up.

For Apple Pay, customers need to have a payment method from a supported bank or payment card provider listed on the Apple Pay™ support page and a compatible Apple device. Using this official ApplePay Demo page Apple.com will help confirm if Apple Pay should be available.

For Google Pay, the button only shows up when there is a saved payment method in the browser or device being used. Customers need to have a payment method from a supported bank or payment card provider saved to their Google Pay supported browsers. More details and support at Google Pay Help

Cash App Pay

↑ Back to top

WooCommerce Square also adds a Cash App Pay payment method to your WooCommerce store. Cash App Pay allows you to accept payments directly on your store, with customers being able to pay using their Cash App account.

Please note that Cash App Pay is currently supported only in the United States and only using the US Dollar currency.


To configure the Cash App Pay payment gateway, navigate to WooCommerce > Settings > Payment > Cash App Pay (Square). You can customize the following settings:

  • Enable/Disable: Enable to allow customers to use this gateway at checkout.
  • Title:  Determine how the gateway should be labeled for customers at checkout and on the order received page.
  • Description: The text shown under the title during checkout. Limited HTML is allowed.
  • Cash App Pay Button Theme: Changes the theme of the Cash App Pay button. Options include Dark and Light.
  • Cash App Pay Button Shape: Changes the shape of the Cash App Pay button. Options include Semiround and Round.
  • Debug Mode: Enable this option when there are problems processing transactions. You can choose to log API requests directly on the checkout page, save them to the WooCommerce > Status > Logs page, or both.

Once the Cash App Pay payment method is configured, it will be listed among the available payment methods on the checkout and order pay page and customers will be able to pay using their Cash App account.

Important note: The Cash App payments method can only seen on the checkout page and not on the cart and product pages like other digital wallets.

Important note: Cash App Pay cannot be stored as a “stored payment method” against a customer’s account, so a new Cash App transaction will be required with every order. Certain product types that use tokenization for future charges cannot currently be purchased with Cash App Pay, such as subscription products (created via the Woo Subscriptions extension) and Pre-Orders “Charge Upon Release” products (created via the WooCommerce Pre-Orders extension). When these products are in the cart, the Cash App Pay payment method will not be shown.

Gift Cards

↑ Back to top

You can receive payments with Square Gift Cards and sell Square Gift Cards by enabling the Gift Cards option in the Square payments settings under WooCommerce > Settings > Payments > Square > Gift Card Settings:

  1. Adds capability to split the payments between a Square Gift Card and a Credit Card.
  2. If the Gift Card has insufficient funds, the customer can either opt to use a different gift card, or pay the remaining total using a credit card through the Square payment method.
  3. For refunds done for orders made using split payments (Gift + Credit Card), the refund will be first done to the Gift Card and then the credit card.
  4. You can sell e-gift cards on their site by registering a WooCommerce product as a Square gift card.
  5. Customers can purchase a new gift card on your website which will be delivered to them via email.
  6. Customers can add funds to an existing gift card by providing the GAN (Gift card account number).

Receiving Payment with Square Gift Cards

↑ Back to top

Customers can avail a Gift Card to make a purchase on your website. A customer can complete the payment entirely with a Gift Card if it has sufficient funds. In a scenario where it has insufficient funds, the customer will be shown the Credit Card option under the Square payment method to pay for the remaining balance.

For example, if the order total is $30 and the Gift Card has a balance of $5, the customer can split the payment and pay the remaining $25 with a credit card.

Please note that when splitting the payment, all other payment methods except Square will be hidden.

Important note: Certain product types that use tokenization for future charges cannot currently be purchased with Square Gift Cards, such as subscription products (created via the Woo Subscriptions extension) and Pre-Orders “Charge Upon Release” products (created via the WooCommerce Pre-Orders extension). When these products are in the Cart, the Gift Card payment method will not be shown.

Selling Square Gift Cards

↑ Back to top
Setting up a gift card product
  1. Create a new simple or variable product
  2. Mark the product as a gift card by enabling the Square gift card checkbox
  3. Enter an amount for the gift card and click publish
  4. The gift card product is now ready for purchase

Note: To ensure that the website’s performance is not negatively affected by multiple API calls, a customer is limited to purchasing only 1 gift card per order.

Gift card orders

For orders related to the purchase or reloading of a gift card, merchants can see the gift card-related details such as the amount, GAN (Gift card account number), etc. under the Order notes section.

Purchasing a gift card

By visiting the gift card product page, customers can purchase a gift card by filling out the form, which the recipient will receive via email.
Note: Only the Square payment method can be used to purchase a gift card.

Adding value to a gift card

Customers who already possess a gift card can add additional funds to the gift card by entering their GAN (Gift card account number).

Email notification for the gift card recipient

Enable the Square gift card sent email notification under WooCommerce > Settings > Email, so that the recipient receives their gift card via email.

WooCommerce Analytics

The purchase of a Gift Card product is included in the calculation of gross sales but excluded from the net sales to align with the information displayed within the Square dashboard.

You can find out more about the Gift Cards feature in the payments section of the Frequently Asked Questions page.

Gateway Features

↑ Back to top

You and your customers can take advantage of the following features when your site uses WooCommerce Square.

Capture Charges

↑ Back to top

If the gateway’s Transaction Type setting is set to “Authorization”, you can manually capture these payments from the WooCommerce > Orders page.

  • An authorized transaction can be captured for up to 6 days; after 6 days, you must ask the customer to re-authorize the transaction to capture payment. This is a restriction for all Square transactions.
  • A captured amount cannot differ from the authorized amount. This is a restriction on the Square side, as they do not allow partial captures.

Click here to read more about capturing charges.

Automatic Refunds

↑ Back to top

You can process refunds directly in WooCommerce without going through your Square account. Click here to learn more about issuing automatic refunds in WooCommerce.

Void Transactions

↑ Back to top

You can void transactions directly in WooCommerce in the following circumstances:

  • If your Transaction Type setting is set to “Authorization”, you can void when the transaction has been authorized but not yet captured.
  • If your Transaction Type setting is set to “Capture”, you can void when the transaction has not yet been settled.

We recommend voiding / revoking authorizations within WooCommerce for WooCommerce orders rather than revoking an authorization in Square. Otherwise, WooCommerce will continue to consider this transaction as valid for capture.

If a transaction can no longer be voided, you should refund the order instead. Click here to read more about voiding transactions.

Enhanced Checkout Form

↑ Back to top

Square supports an enhanced checkout form to improve your customers’ checkout experience on both desktop and mobile devices. Click here for more information about the enhanced checkout form.

Customer Profiles (Saved Payment Methods)

↑ Back to top

When enabled in the payment gateway settings, customers can save payment methods during checkout or from the My Account area, which supports quicker checkouts and the use of plugins like Subscriptions and Pre-Orders. Click here to learn more about managing saved payment methods.

Detailed Decline Messages

↑ Back to top

When enabled in the payment gateway settings, Square will attempt to provide a more detailed “payment declined” message to help your customers understand why the transaction was declined. Click here to read more about detailed decline messages.

Customer Token Editor

↑ Back to top

When enabled in the payment gateway settings, you can manually add or update the payment method tokens on your site to resolve any synchronization issues. Click here for more information about the customer token editor.

Troubleshooting

↑ Back to top

Please refer to the Troubleshooting guide.

Frequently Asked Questions

↑ Back to top

Please refer to the Frequently Asked Questions guide.