VibeFox Square for Adobe Commerce — Помощь

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL and JSON extensions.

Currency: the checkout 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.

HTTPS: the Square card form needs a storefront served over HTTPS.

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

Installation

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-square-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/SquarePayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_SquarePayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox Square Gateway. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Keep Sandbox Mode at Yes and enter the sandbox Application ID, Access Token and Location ID (see Configuration). Set Enable to Yes and click Save Config: the module checks the credentials with Square. Test a payment with the test cards from Square's sandbox testing guide. Then set Sandbox Mode to No, enter the live credentials and save again.

The module adds the Credit / debit card payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables for the Square payment attempts and refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Square Gateway, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Delete Settings on Uninstall is read from the Default Config only. Save Config saves the whole page.

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Enter a title for the payment method (up to 128 characters).); a Sort Order that is not a whole number; a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater (use a dot as the decimal separator, for example 9.99).

At the top of the group the page always shows Square location currency must match the checkout currency. Supported: USD, CAD, AUD, JPY, GBP, EUR. While Enable is Yes it also shows Missing Square credentials for the selected environment. The method is hidden. when the Application ID, Access Token or Location ID of the selected environment is empty, and SANDBOX mode: no real money is charged. while sandbox mode is on.

When you save with all three credentials of the selected environment filled in, the module checks them with Square. The settings are saved in any case, and a warning is shown when something is wrong: Square Application ID does not match the selected environment. (a sandbox Application ID in live mode or the other way round), Square credentials could not be verified. Check Access Token and Location ID., Square credentials could not be checked. Settings were saved. or Square location currency is … the store currency is … The method is hidden for other checkout currencies. Square can only charge in the location currency: the module remembers the currency of the checked location and hides the payment method for checkouts in any other currency.

Enable: shows or hides Square at checkout. It is shown only when the Application ID, Access Token and Location ID of the selected environment are set. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Credit / debit card. Required, at most 128 characters.

Description: the text shown under the payment method when the customer selects it at checkout, above the card form. Default: Pay securely with your credit or debit card via Square.

Sandbox Mode: payments go to the Square sandbox and no real money is charged. Use Square test cards. Default: Yes. While it is on, customers see SANDBOX MODE — no real payment. Do not ship test orders. under the payment method. Set it to No to take real payments.

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 page shows only the credential fields of the selected environment: sandbox fields while Sandbox Mode is Yes, live fields while it is No. Both sets stay saved.

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

Sandbox Access Token: your sandbox Square Access Token.

Sandbox Location ID: your sandbox Square Location ID.

Live Application ID: your production Square Application ID.

Live Access Token: your production Square Access Token.

Live Location ID: your production Square Location ID.

Spaces around the credentials are removed. Magento stores the access tokens encrypted and shows only a mask (******) after saving: A mask keeps the saved secret. Empty field deletes it. Leave the mask as it is to keep the saved token, type a new value to change it. To delete a saved token, clear the field and click Save Config. The customer's browser receives only the Application ID and the Location ID, never the access token.

Debug Logging: errors and warnings are always logged. Set it to Yes to also log every request and response, without keys, card data or e-mail addresses, to var/log/wc_sqg_debug.log.php in the Magento folder. The file cannot be opened from the web. When it grows over 5 MB, it is moved to an old copy and a new file is started. Default: No.

Delete Settings on Uninstall: when Yes, uninstalling the module with its data deletes the gateway settings and the log (see Uninstall). The license key is always removed. The Square payments and refunds of orders always stay, so old orders can still be refunded. Default: No.

Payment from Applicable Countries: All Allowed Countries offers Square for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer Square only for billing addresses in these countries.

Minimum Order Total: offer Square only from this order total, in the base currency of your store. Empty or 0 means no minimum.

Maximum Order Total: offer Square only up to this order total, in the base currency. Empty or 0 means no maximum.

Sort Order: the position among the payment methods at checkout. A whole number.

Log: the last row of the group (Default Config) shows the size and the latest entries of the log. Click Clear log to empty it.

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. The billing address is required. When the customer clicks Place Order, the card is tokenized in the browser with buyer verification (3-D Secure / SCA): the order total, the currency and the billing address are passed to Square, and the customer's bank may ask for a confirmation. If the card details are incomplete or the verification fails, the customer stays at checkout with the message from the card form, and no order is placed. Your store receives only a single-use token.

Magento then places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module charges the token through the Square Payments API for the order total in the order currency (whole yen for JPY), with the order ID as the reference, the 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 reference and location. Magento then creates the invoice with the Square payment ID as the transaction ID, the order goes to Processing, the order e-mail is sent and the customer sees the standard order success page.

If the payment is not COMPLETED, any value differs, or the cart was already paid with another order, the order is put On Hold without an invoice, and the customer sees a page with Your Square payment requires review. This is not a payment confirmation. Do not pay again; contact us or check your e-mail. and the order number.

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 and check your e-mail. Requests are idempotent: the same cart, card 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 module looks for the payment of this order at Square at once. If it finds it, the order is completed with it. If no payment is found, the customer stays at checkout with We could not get payment confirmation. Wait a minute and try again; a previous charge will be looked up first. and can click Place Order again for the same order: the earlier payment is looked up first. If Square cannot be reached for the lookup either, the order is put On Hold without an invoice, and the customer sees the review page above.

When the bank declines the card, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart 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 customer can try again with another card. The technical reason goes to the order notes and the log.

If the card form cannot be loaded, the customer sees The secure card form could not be loaded. Please reload or choose another payment method. If the customer clicks Place Order before the form is ready, Please enter your billing address and wait for the secure card form. is shown.

An order that stays in Pending Payment, for example when the customer leaves the checkout, is cancelled by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings), or you can cancel it yourself.

The module works with the standard Magento checkout. It 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. Square is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed, but Square has not confirmed a payment yet (the charge is running, or Square's answer was lost and the customer can try again). There is no invoice.

Processing: Square confirmed a COMPLETED payment of the order total. The invoice is created with the Square payment ID as the transaction ID, and a note shows Square payment completed. Payment ID: and the ID.

On Hold: Square answered with a payment that is not COMPLETED (for example APPROVED), or with a different amount, currency, reference or location, or the cart was already paid with another order, or Square's answer was lost and could not be checked. No invoice is created. The note Square payment needs review shows the Square status, the payment ID and the amount Square charged. Verify the payment in the Square Dashboard before fulfilment.

Canceled: the card was declined (the note Square payment refused shows Square's error codes), or the order was cancelled in Magento.

Closed: the payment was fully refunded with a credit memo.

The notes are order comments that the customer does not see.

Square payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and Square payment ID, Square environment (sandbox or production), Square actual amount (the amount and currency Square charged), Square card (brand and last 4 digits), Square receipt (the link to the Square receipt) and, after a refund, Square refund status. Card numbers are never stored. The customer sees only the payment method title.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through Square. Full and partial refunds are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Square.

The refund is made in the currency of the payment, up to the amount Square charged minus the refunds already accepted. It is sent to the environment (sandbox or production) and the location the payment was made in, so the Access Token of that environment must be set. A refund that Square accepts (status PENDING or COMPLETED) is recorded with the Square refund ID as the transaction ID. PENDING means Square accepted the refund, not that the bank has already paid it out. A full refund closes the order. If Square does not accept the refund, Magento shows the error, for example Square did not confirm the refund. Check Square Dashboard before retrying., and the credit memo is not created.

For JPY, Magento keeps totals with two decimals (for example 1357.40 after tax or a currency rate), while Square charged whole yen (1357). The module sends each credit memo in whole yen so that partial refunds add up to the charge, and the credit memo that refunds the rest of the order refunds exactly what is left of the Square payment. A full credit memo therefore refunds exactly what the customer paid.

If an earlier refund request got no clear answer from Square, further online refunds of the order are blocked with A prior Square refund is unconfirmed. Reconcile it before retrying. to avoid refunding twice. Check the refund in the Square Dashboard and finish it there, then create a credit memo with Refund Offline.

Refunds made in the Square Dashboard do not appear in Magento. Create a credit memo with Refund Offline if needed.

Refund of an order On Hold

An order On Hold has no invoice, so it cannot be refunded with a credit memo. When Square has captured money for it, the order page shows the block Square captured payment review with the amount Square captured. Enter Refund amount (in the payment currency) and click Submit Square Dashboard Refund. The refund is sent through the Square API, up to the captured amount, and the order gets a note Square Dashboard refund submitted with the amount, the refund ID and the status. No invoice or credit memo is created. Use it only after checking the payment in the Square Dashboard. The block is shown to Admin users whose role allows credit memos. Submitting the same form twice does not send a second refund.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Square Gateway is the first row of the VibeFox Square Gateway group in Stores > Configuration > Sales > Payment Methods, 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: magento-payment-square and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. 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 card is not charged and the customer sees This payment method is not available. Please choose another one. The Magento storefront does not know that you are logged in to the Admin, 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. 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: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Square does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the Application ID, Access Token and Location ID of the current environment are filled in. Check that the checkout currency is USD, CAD, AUD, JPY, GBP or EUR and equals the currency of your Square location. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total.

The payment went through, but the order stays Pending Payment: the module has no webhook; the result comes from Square's answer to the charge. When the answer was lost, the customer saw We could not get payment confirmation. Check the payments of this location in the Square Dashboard (reference = order ID). If the customer clicks Place Order again in the same checkout, the module first looks for the earlier payment and completes the order with it instead of charging again. Otherwise check the payment in the Square Dashboard and refund it there or complete the order manually.

The payment method disappeared after saving: the currency of the Square location differs from the checkout 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 credentials could not be verified: the Access Token belongs to the other environment or is wrong, or the Location ID belongs to another application. Copy them again from the Credentials and Locations pages of the same application and check Sandbox Mode.

The card form does not load: check that the Application ID and Location ID belong to the selected environment (sandbox IDs start with sandbox-) and that the storefront uses HTTPS. The customer sees Square credentials could not initialize the secure card form. or The secure card form could not be loaded.

The customer saw Payment could not be confirmed. Do not pay again: an error occurred while the payment was being processed. Check the order and the payment in the Square Dashboard and read the log.

The order is On Hold: read the order notes (see Order statuses). Check the payment in the Square Dashboard, then fulfil the order or refund the payment with Submit Square Dashboard Refund or in the Square Dashboard.

Refund fails with The original Square access token is unavailable: the payment was made in sandbox or live mode, and the Access Token of that environment is not set. Enter it and try again.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice (On Hold) cannot be refunded with a credit memo; use the Square captured payment review block.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Other errors: set Debug Logging to Yes and look at the Log field on the settings page.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_SquarePayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_SquarePayment to remove the data, then bin/magento module:disable Vibefox_SquarePayment, delete the folder app/code/Vibefox/SquarePayment and run bin/magento setup:upgrade.

The license key, the license status and the remembered location currency are always removed. If Delete Settings on Uninstall is Yes, the gateway settings and the log are removed too. If it is No, the settings are kept for a re-install. The Square payments and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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