VibeFox Square for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

PHP: 8.0 or later.

Currency: the order 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. JPY is charged in whole yen.

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 extension gets the payment result directly from Square's answer.

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

Installation

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package wcp_square_gateway-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_square_gateway.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_square_gateway-oc3-(version).ocmod.zip. The extension has no OCMOD modifications, so Extensions > Modifications does not need a refresh. Instead of the installer you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Square Gateway and click Install (the green + button). Your admin user needs the right to modify the payment extensions list.

3. Click Edit (the pencil button) to open the settings page. Paste your VibeFox license key into License key in the license block at the top of the 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 extension 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.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_square_gateway.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Square Gateway, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the Square credentials as in steps 3 to 5 for OpenCart 3. The settings page and its fields are the same in both versions.

A new install starts with the payment method turned off and sandbox mode on.

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox Square Gateway > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings 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 store, and when the currency of your Square location differs from it. Without the right to modify the extension the page shows the settings but cannot save them.

When you save, Title must not be empty (up to 128 characters), Sort Order must be a whole number (negative values are allowed), Total must be a number, 0 or greater, and the geo zone and order statuses must exist; otherwise nothing is saved. Then the extension checks the credentials of the selected mode with Square. The settings are saved in any case, and the warnings appear in a red block above the settings: Square rejected the Access Token, the Location ID was not found for this token, the credentials could not be checked, or the location currency differs from the store currency. Square can only charge in the location currency: the extension remembers the currency of the checked location and hides the payment method for orders 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 name customers see at checkout. It is also the payment method name stored in the order. Default: Credit / debit card. Required.

Description: the text shown to the customer at the Confirm Order step, above the card form. Default: Pay securely with your credit or debit card via Square.

Sort Order: the position of the card payment among the payment methods at checkout. Leave it empty or enter a whole number (negative values are allowed).

Geo Zone: offer the card form only for payment addresses in the selected geo zone. Default: All zones. Geo zones are set up in System > Localisation > Geo Zones.

Total: the checkout total, in the default currency of the store, that an order must reach before the payment method is offered. Leave it empty to offer it for any total.

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 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. Both sets stay saved.

Sandbox Mode: payments go to the Square sandbox and no real money is charged. Use Square test cards. Default: on. Refunds of an order always use the environment and location the order was paid in.

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. To remove a saved token, tick Clear the saved value on save under the field and click Save.

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). The order gets a status only after Square has answered the payment. Each field below lists your OpenCart order statuses.

Order Status After Payment: Square completed the payment for exactly the order amount and currency. Default: Processing.

On Hold (Review) Status: the payment needs your review (see Order statuses). Default: Pending, because OpenCart has no On hold status. You can create your own status in System > Localisation > Order Statuses and select it here.

Refunded Status: set after the payment is fully refunded from the order tab. Default: Refunded.

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 wc_sqg_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web, and at 5 MB it is moved to wc_sqg_debug.old.log.php. 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 extension removes the gateway settings and the log files. The Square payments and refunds of orders are always kept. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. Access tokens are not exported.

Import: paste previously exported JSON and click Import to restore the settings. Saved access tokens are kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default Credit / debit card). At the Confirm Order step the customer sees Credit / debit card (Square), your description, SANDBOX MODE — no real charges will be made. while sandbox mode is on, and the Square card form. OpenCart creates the order at this step, still without a status. When the customer clicks Confirm Order, the card is tokenized in the browser with buyer verification (3-D Secure / SCA): the order total, the currency and the payment address are passed to Square, and the customer's bank may ask for a confirmation. Your store receives only a single-use token. On OpenCart 4 the customer picks the payment method with the Choose button of the payment method block, in the window Payment method options. The Square card form then appears in the confirm block at the bottom of the checkout page, above Confirm Order.

The extension then charges the token through the Square Payments API for the order total in the order currency, with the order number as the reference, a note Order # with the order number and your store 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 order total, currency, order number and location. The order then gets Order Status After Payment the standard OpenCart way, with the usual order e-mails and stock update, and the customer sees the OpenCart order success page with Your card payment has been received. and a link View the receipt to the Square receipt. If the payment is not COMPLETED or any value differs, the order gets On Hold (Review) Status 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, and OpenCart 3 creates a new order every time the Confirm Order step is shown, so the extension tracks the cart: a cart that is already paid is never charged again, and the customer goes straight to the success page.

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 extension looks for the payment of this order at Square at once. If it finds it, the order gets its status from it. If no payment is found, the customer stays at the Confirm Order step 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 of the same cart first looks for the earlier payment again. If Square cannot be reached for the lookup either, the order gets On Hold (Review) Status without a payment, with a note that the card may have been charged, and the success 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, the order stays without a status and the customer stays at the Confirm Order step 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.

OpenCart 4 keeps one order for the checkout and updates it, so after a declined card the customer pays the same order again, and after a payment without an answer from Square the next attempt of that order first looks for the earlier payment. If the order of the checkout already has a status (it was paid or closed by the store) and the cart holds new products, the customer is sent back to the checkout and the new cart is paid with a new order.

The extension 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 status (missing order): the customer has not paid yet, the card was declined, or Square's answer was lost and no payment was found. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

Order Status After Payment (default Processing): Square confirmed a COMPLETED payment of the order total. A note shows the Square payment ID, the card brand with the last 4 digits and the mode (sandbox or live).

On Hold (Review) Status (default Pending): Square answered with a payment that is not COMPLETED (for example APPROVED or PENDING), or with a different amount, currency, reference or location. The note Square payment needs review shows the payment ID, the status and the amounts. This status is also used when the order changed during the payment, and when Square's answer was lost and could not be checked (no payment is recorded then, and the note asks you to check the payments of the location in the Square Dashboard with the order number as reference). Verify the payment in the Square Dashboard before fulfilment.

Refunded Status (default Refunded): the payment was fully refunded through the extension.

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

Notes are entries in the order History that the customer does not see.

VibeFox Square Gateway tab

In Sales > Orders open an order paid with Square. At the bottom of the order page, next to History and Additional, the VibeFox Square Gateway tab shows the Square Payment ID (linked to the payment in the Square Dashboard) with a Sandbox label for sandbox payments, the Square Status, the Card brand and last 4 digits, the amounts Paid / order / refunded, the Environment / location, the Square receipt link, the refund form, the refund history and the Square notes of the order. Card numbers are never stored. The tab is shown to users who have access to the extension.

Refunds

In the VibeFox Square Gateway tab enter the Amount (the amount not refunded yet is filled in), optionally a Reason (optional), 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 modify the extension (set in System > Users > User Groups). 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 tab shows the error and no refund is recorded. A full refund sets the order to Refunded Status without notifying the customer and without returning products to stock, like a manual status change. A partial refund does not change the status.

Product returns in Sales > Returns 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 OpenCart.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Square Gateway is the first block on Extensions > Extensions > Payments > VibeFox Square Gateway > Edit, 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 store. Below them are the line Product: opencart-payment-square and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin 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 store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. Removing the key from the store 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. An admin user who is logged in to the admin in the same browser still sees the payment method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the payment method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected: paid orders stay paid, and refunds work.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension 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 customer's 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. Also check that the payment address is in the selected Geo Zone and that the order reaches the Total set in the settings.

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 order currency. Enter the Location ID of a Square location in your store 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 = order number). If the customer tries again, the extension first looks for the earlier payment and uses 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 OpenCart could not set the order status. Read the log, then complete the order manually or refund the payment in the Square Dashboard.

The customer sees This payment method is not available for your order: the checkout no longer matches the order, the payment method was turned off meanwhile, or the order currency cannot be charged. The customer reloads the checkout or chooses another payment method.

Order is in the review status after payment: read the notes in the VibeFox Square Gateway tab (see Order statuses). Check the payment in the Square Dashboard, then fulfil the order or refund the payment.

No refund form in the tab: the tab says why: no Square payment took money for this order, no Square payment ID is recorded (the tab then names the location and the order number to look for in the Square Dashboard), the payment is fully refunded, or your user group has no right to modify the extension.

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 extension page.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Square Gateway. The license key and license status of this extension are always removed. OpenCart always removes its own settings of the extension: Enable/Disable, Sort Order, Geo Zone, Total and the order statuses of the Orders section, which return to their defaults on a re-install. The OpenCart event of the extension is removed too. If Delete data on uninstall is on, the other gateway settings (title, description, sandbox mode, credentials, logging) and the log files are removed. If it is off, they are kept for a later re-install. The Square payments and refunds of orders are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox Square Gateway in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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