VibeFox Square for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 7.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

Store currency: the currency of your Square location: USD, CAD, AUD, JPY, GBP or EUR. For other currencies the payment method is hidden at checkout. Square supports sellers in the US, Canada, Australia, Japan, the UK, Ireland, France and Spain.

Square account: you need an application in the Square Developer Dashboard. From it you copy the Application ID and the Access Token (Credentials page) and the Location ID (Locations page). Sandbox and Production have separate values. No webhook is needed: the plugin gets the payment result directly from Square's answer.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_square_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Square > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Keep Sandbox Mode on and enter the sandbox Application ID, Access Token and Location ID (see Configuration). Save: the plugin checks the credentials with Square.

6. Turn on Enable/Disable and test a payment with the test cards from Square's sandbox testing guide. Then untick Sandbox Mode, enter the production credentials and save again.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Square. Above the fields the page shows Square Gateway is currently in SANDBOX mode. No real charges will be made. while sandbox mode is on. It warns you when Square is enabled but the Application ID, Access Token or Location ID of the selected mode is missing (the payment method is then hidden at checkout), and when Square cannot process the store currency. In the list of payment methods, Square shows a Test mode badge while sandbox mode is on.

When you save, the plugin checks the credentials of the selected mode with Square. You see an error if Square rejects the Access Token, if the Location ID is not found for this token, if the credentials could not be checked, or if the location currency differs from the store currency. Square can only charge in the location currency: the plugin remembers the currency of the checked location and hides the payment method at checkout for any other currency, and the settings page keeps showing the warning. It also warns you if a sandbox Application ID is used in live mode or the other way round.

General

Enable/Disable: Enable Square Payment Gateway turns the payment method on or off. Default: off.

Title: the payment method title that the customer sees during checkout. Default: Credit / debit card.

Description: the payment method description that the customer sees during checkout. Default: Pay securely with your credit or debit card via Square.

Square account

Open the Square Developer Dashboard, choose your application and copy the Application ID and Access token from the Credentials page (Sandbox and Production have separate values) and the Location ID from the Locations page. The location currency must match your store currency. The page shows only the credential fields of the selected mode: sandbox fields while Sandbox Mode is on, live fields while it is off.

Sandbox Mode: Enable sandbox (test) mode. Payments go to the Square sandbox and no real money is charged. Use Square test cards. Default: on.

Sandbox Application ID: your sandbox Square Application ID (starts with sandbox-sq0idb-).

Sandbox Access Token: your sandbox Square Access Token.

Sandbox Location ID: your sandbox Square Location ID.

Live Application ID: your production Square Application ID (starts with sq0idp-).

Live Access Token: your production Square Access Token.

Live Location ID: your production Square Location ID.

Advanced

Debug log: Log API requests and responses. Errors are always logged. Turn it on to also log every request, without card data or keys. Logs are in WooCommerce > Status > Logs, source wcp_square_gateway. Default: off.

Delete data on uninstall: Remove all plugin data when the plugin is deleted. Deletes the gateway settings and log files when you delete the plugin. Order payment data is kept. Default: off.

Checkout

The customer chooses the payment method (by default Credit / debit card) and enters the card in the Square card form shown under the description. In sandbox mode the checkout shows a sandbox notice. When the customer clicks Place order, the card is tokenized in the browser with buyer verification (3-D Secure / SCA): the amount, currency and billing contact are passed to Square, and the customer's bank may ask for a confirmation. Your server receives only a single-use token.

The plugin then charges the token through the Square Payments API for the order total in the order currency, with the order ID as the reference, a note Order # with the order number and your site name, and the billing e-mail. The payment is captured immediately. The order is marked paid only after Square confirms it: Square's answer must show a COMPLETED payment for exactly the order total, currency, order ID and location. Then the customer goes to the order received page. If the payment is not COMPLETED or any value differs, the order is put on hold with a note and the customer still goes to the order received page.

Only one payment attempt per order runs at a time. If the customer clicks twice or pays in two tabs, the second attempt sees This order is already being paid. Please wait a moment and check your e-mail before trying again. Requests are idempotent: the same order, token and amount never create a second payment.

If Square does not answer (network problem, timeout, server error), the request is retried once with the same idempotency key. If there is still no answer, the customer sees We could not get a confirmation from the payment provider. Please wait a minute and try again — if your card was already charged, the payment will be recognised and you will not be charged twice. The order note asks you to check the Square Dashboard. On the next attempt the plugin first looks for the earlier payment of this order at Square and completes the order with it instead of charging the card again.

When the bank declines the card, the customer sees a short message by Square's error code, for example Your card was declined. Please use another card or payment method., The card security code (CVV) is incorrect. Please check it and try again. or Your bank requires additional verification (3-D Secure). Please enter your card again and complete the verification. The technical reason goes to the order notes and the log. The customer can try again with another card, also later from the Pay for order page.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin takes card payments only, captured immediately. It has no saved cards or customer profiles, no WooCommerce Subscriptions or Pre-Orders, no Apple Pay, Google Pay, Cash App Pay, Afterpay, ACH or Square gift cards, no authorize-only payments, no Square webhooks and no product or inventory synchronisation with Square. Disputes are managed in the Square Dashboard.

Orders and refunds

Order statuses

Pending payment: the order was created and has not been paid yet, for example after a declined card or a lost answer from Square.

Processing: Square confirmed a COMPLETED payment of the order total. This is the standard WooCommerce status after payment (orders with only virtual downloadable products become Completed). The order note shows the Square payment ID, the card brand with the last 4 digits and the mode (sandbox or live). The transaction ID is the Square payment ID, and on the order screen it links to the payment in the Square Dashboard.

On hold: Square answered with a payment that is not COMPLETED, or with a different amount, currency, reference or location. The note Square payment needs review shows the payment ID, the status and the amounts. Verify capture, amount and currency in the Square Dashboard before fulfilment.

The plugin stores the Square payment ID, the card brand and last 4 digits, the environment and the location on the order. Card numbers are never stored.

Refunds

Open the order, click Refund, enter the amount and click Refund via Credit / debit card (the button shows your Title). Full and partial refunds are supported. The refund is sent to the environment (sandbox or production) and the location the payment was made in, so the Access Token of that mode must be set. Refund requests are idempotent and are retried once if Square does not answer. A refund that Square accepts (status PENDING or COMPLETED) is added to the order notes with the Square refund ID. If Square rejects it, WooCommerce shows the error and no refund is recorded.

Square completes refunds on its side. A refund that Square rejects later is not reported back to WooCommerce, and refunds made in the Square Dashboard do not appear in WooCommerce.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Square. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Square is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: paid orders stay paid, and refunds work.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

Square does not appear at checkout: check that the license is active, Enable/Disable is on and the Application ID, Access Token and Location ID of the current mode are filled in. Check that the store currency (or the order currency on the Pay for order page) is USD, CAD, AUD, JPY, GBP or EUR and equals the currency of your Square location. The settings page shows a warning for each of these problems.

The card form does not load: the customer sees The card form could not be loaded. Please reload the page or choose another payment method. Check that the Application ID and Location ID belong to the selected mode (sandbox IDs start with sandbox-). If the customer clicks too early, The card form is still loading. Please wait a moment and try again. is shown.

Payments are declined although the card is fine: the location currency must equal the store currency. Save the settings to see the result of the credentials check; after a successful check the method is hidden for other currencies.

Square rejected the Access Token of the selected mode: the token belongs to the other mode or is wrong. Copy it again from the Credentials page of your application and check Sandbox Mode.

The Location ID was not found for this Access Token: copy the Location ID from the Locations page of the same application and mode.

The customer saw We could not get a confirmation from the payment provider: Square did not answer. Read the order note and check the payments of this location in the Square Dashboard (reference = order ID). If the customer tries again, the plugin first looks for the earlier payment and completes the order with it instead of charging again.

The order is On hold: read the note Square payment needs review. The payment was not COMPLETED or its amount, currency or location differed from the order. Check it in the Square Dashboard, then fulfil the order or refund the payment.

Refund fails with a message about the mode: the payment was made in sandbox or live mode, and the Access Token of that mode is not set. Enter it and try again.

Other errors: turn on Debug log and look at WooCommerce > Status > Logs, source wcp_square_gateway.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings and the log files are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes, Square payment IDs and transaction IDs.

Square is a trademark of its respective owner. This plugin is not affiliated with or endorsed by Square.