VibeFox Square for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

Currency: the cart currency must be 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 module 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 the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox Square Gateway in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

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

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

On install the module creates the order status Square payment on hold. PrestaShop allows a new payment module for the currencies, the countries active at install time and the customer groups. Check them, and tick countries you add later, in Payment > Preferences.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Square Gateway > Configure. Each section has its own Save button, which saves the whole page. 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), when Square cannot process the default currency of your shop, and when the currency of your Square location differs from it.

When you save, the module checks the credentials of the selected mode with Square. The settings are saved in any case. You see a warning 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 shop currency. Square can only charge in the location currency: the module remembers the currency of the checked location and hides the payment method for carts in any other currency. It also warns you if a sandbox Application ID is used in live mode or the other way round.

Square

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. It is also the payment method name stored in the order. Default: Credit / debit card. Required.

Description: the payment method description that the customer sees during checkout. Default: Pay securely with your credit or debit card via Square. In sandbox mode (SANDBOX MODE) is added to it.

Square account

Open the Square Developer Dashboard (the section links to it), 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 shop 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. Both sets stay saved.

Sandbox 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.

Saved access tokens are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

Clear saved secrets: tick an access token and click Save to remove it. An empty field keeps the saved value.

Advanced

Debug log: errors and warnings are always logged. Turn it on to also log every request and response, without card data or keys, to logs/wc_sqg_debug.log.php in the module folder. The file cannot be opened from the web. Default: off.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Delete data on uninstall: when on, uninstalling the module removes the gateway settings and the log files. The Square payments and refunds of orders and the order status Square payment on hold are always kept. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Credit / debit card) and enters the card in the Square card form shown under the description. When the customer places the order, the card is tokenized in the browser with buyer verification (3-D Secure / SCA): the cart total, the currency and the billing address are passed to Square, and the customer's bank may ask for a confirmation. Your shop receives only a single-use token.

The module then charges the token through the Square Payments API for the cart total in the cart currency, with the cart ID as the reference, a note Cart # with the cart number and your shop name, and the customer's 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 cart total, currency, cart ID and location. The order is then created with Payment accepted, and the customer sees the standard order confirmation page with Your card payment has been received. and a link to the Square receipt. If the payment is not COMPLETED or any value differs, the order is created in Square payment on hold and the page shows Your card payment has been received and is being reviewed. We will update your order as soon as the review is complete.

Only one payment attempt per cart 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 cart, card token and amount never create a second payment, and a cart that already has an order is never charged again.

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 module looks for the payment of this cart at Square at once. If it finds it, the order is created with it. If no payment is found, the customer stays at checkout with 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 next attempt first looks for the earlier payment again. If Square cannot be reached for the lookup either, the order is created in Square payment on hold without a payment, with a note that the card may have been charged, and the confirmation page shows We could not get a confirmation of your card payment from Square. Please check your e-mail and card statement before paying again, or contact us.

When the bank declines the card, no order is created and the customer stays at checkout with 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 cart is kept, and the customer can try again with another card. The technical reason goes to the log.

The module takes card payments only, captured immediately. It has no saved cards or customer profiles, no subscriptions, 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

No order yet: the card was declined, or Square's answer was lost and no payment was found. Only the cart exists.

Payment accepted: Square confirmed a COMPLETED payment of the cart total. The payment is recorded with the Square payment ID as the transaction ID, and a note shows the payment ID, the card brand with the last 4 digits and the mode (sandbox or live).

Square payment on hold: Square answered with a payment that is not COMPLETED (for example APPROVED), or with a different amount, currency, reference or location. The note Square payment needs review shows the payment ID, the status and the amounts. A COMPLETED payment is recorded on the order with the amount Square charged. This status is also used when the cart changed during the payment, and when Square's answer was lost and could not be checked (no payment is recorded then). Verify the payment in the Square Dashboard before fulfilment.

Refunded: the payment was fully refunded through the module.

If a second payment arrives for a cart that already has an order, the order is not changed. A note asks you to check it and refund the duplicate in the Square Dashboard.

Square block

The order page shows a Square block with the Square payment ID (linked to the payment in the Square Dashboard), the Square status, the card brand and last 4 digits, Paid / order / refunded amounts, the environment and location, a link to the Square receipt, a Sandbox badge for sandbox payments, the refund history and the Square notes of the order. Card numbers are never stored.

Refunds

In the Square block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via Square. Confirm the question Refund this amount through Square? This cannot be undone. Full and partial refunds are supported. You need the right to edit orders. Refunds are made in the amount and currency Square charged, so after an amount mismatch you can refund up to what the customer actually paid, not the order total. 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 refund history and the notes with the Square refund ID. If Square rejects it, the block shows the error and no refund is recorded. A full refund sets the order to Refunded. A partial refund does not change the status.

The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through Square. Square completes refunds on its side: a refund that Square rejects later is not reported back, and refunds made in the Square Dashboard do not appear in PrestaShop.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Square Gateway is the first block on Modules > Module Manager > VibeFox Square Gateway > Configure, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this shop. Below them are the line Product: presta-payment-square and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop 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. The PrestaShop storefront does not know that you are logged in to the back office, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected: paid orders stay paid, and refunds work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

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 cart currency 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. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group.

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.

The payment method disappeared after saving: the currency of the Square location differs from the cart currency. Enter the Location ID of a Square location in your shop currency and save again: the method is shown again after a successful check.

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 and no payment was found yet. Check the payments of this location in the Square Dashboard (reference = cart ID). If the customer tries again, the module first looks for the earlier payment and creates the order with it instead of charging again.

The customer saw Your payment was received, but the order could not be completed automatically: the card was charged, but PrestaShop could not create the order (for example, the module was disabled at that moment). Read the log, then create the order manually or refund the payment in the Square Dashboard.

The order is Square payment on hold: read the notes in the Square block (see Order statuses). Check the payment 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 the Log field on the module page.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Square Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the gateway settings and the log files are removed. If it is off, all settings are kept for a later re-install. The Square payments and refunds of orders and the order status Square payment on hold are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes, Square payment IDs and transaction IDs.

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