Square WebPay

There are two Square modules for Zen Cart:

• A newer one, based on the Square Web Payments API, which is currently available as the Square Web Payments API plugin.
• An older one, based on the Square Payments Form library. This was built in to Zen Cart from 1.5.5 to 1.5.7. Please note this library has been deprecated by Square, and the older module ceased to work in late 2022. The Square Payments Form documentation is maintained for historical purposes.

Newer Module - Square Web Payments API

The newer Square module is available in the Plugins library as Square Web Payments API plugin.

• The top one (“Square”) is the old Square module.
• The bottom (“Square WebPay”) one is the new Square module.

Requirements

1. You must be using SSL on your website
2. You will need a Square account, already validated and connected with your bank. You may create a Square merchant account here.

Please note: do NOT remove the old Square files from your Zen Cart installation.

Installing Square Web Payments - first time

1. Install the Square Web Payments module files. Then to go to Admin > Modules > Payments > Square WebPay, and click Install.
2. Double check - did you just install the module “Square WebPay”? If you’re on the module “Square,” it will look very similar but won’t work.
3. Login at https://connect.squareup.com/apps to view the apps you’ve connected to your account.
4. Click + to create a New Application for your Zen Cart store. Give it a name, such as “WebPay”. You cannot delete the app or change its name once it is created, so choose carefully; if it’s for a test installation of your site, call it WebPay-Test or something like that.
5. Version 1.0.1 of Square Web Payments requires API Version 2022-02-16. Ensure you have selected the correct version and click Save.
6. Click on the application icon that was just created (named “WebPay” or whatever name you used).
7. The environment will be Sandbox by default. Click “Production”.
8. Copy and Paste the Production Application ID into your Square WebPay configuration Application ID field in Zen Cart admin.
9. Click on the OAuth tab. In the “Redirect URL” field, enter https://YOURSTORE.com/squareWebPay_handler.php and click Save at the bottom. (Ensure the URL you enter points to the correct directory or subdirectory on your server.)
10. Now click Show on the Production Application secret field. Copy and Paste the secret into your Square WebPay configuration Application Secret (OAuth) field in Zen Cart admin.
11. In your Zen Cart admin, do the following:

• Click Update to save the new Square WebPay config values.
• Click the green button in the Zen Cart admin sidebar that says “Click here to login and Authorize your account.” If everything is correct, the Sort Order LED for Square WebPay will go green.
• Click the Edit button one more time. This will fill in the Location ID field. Click Update.

9. If this isn’t working, check again to be sure you are editing the “Square WebPay” module not the old “Square” module - it’s easy to get the two mixed up.

Once you have installed and successfully tested Square Webpay, you will want to create a cron job to refresh the Square token.

Handling Refunds, Captures, Voids

Refunds

When viewing a transaction in your store Admin, if it was paid using Square within the last 120 days, you will be shown the option to Refund some or all of the payment. Simply enter the amount you wish to refund. Then check the box to confirm, and click Submit. You will see a status message confirming the refund has been issued.

NOTE: You SHOULD do all refunds via your store Admin. While you might be able to start a refund from your Square Dashboard, that will NOT automatically update your orders in Zen Cart to show the change in status. But if you do the refund from within your Zen Cart Admin, the refund will show in both places, as well as in the customer’s order-status-history, which is a more friendly experience for them.

Captures

If you’ve configured the module to “authorize only” instead of automatically capturing each “purchase”, then you will also see an option to Capture the previously-authorized transaction. CAPTURES MUST BE DONE WITHIN 6 DAYS, or they will be voided automatically, releasing the hold on those funds for the customer.

NOTE: Captures can ONLY be done via your store Admin. You will not see uncaptured (authorize-only) transactions in your Square Dashboard.

Voids

If you’ve configured the module to “authorize only”, then you will see a Void option. This can be used to cancel an Authorization and release the “hold” on those funds back to the customer.

NOTE: Voids can ONLY be done via your store Admin. You will not see authorize-only transactions in your Square Dashboard.

Reinstalling Square Web Payments

If your access token goes bad, you can get into a state where you have to delete and reinstall Square. Here’s what you need to do to configure the module once you have reinstalled it:

1. Login at https://connect.squareup.com/apps to view the apps you’ve connected to your account.
2. Click on the application icon that you created (probably named “WebPay” or whatever name you used).
3. Copy and Paste the Production Application ID into your Square WebPay configuration Application ID field in Zen Cart admin.
4. Click on the OAuth tab.
5. Now click Show on the Production Application secret field. Copy and Paste the secret into your Square WebPay configuration Application Secret (OAuth) in Zen Cart admin.
6. In your Zen Cart admin, do the following:

• Click Update to save the new Square WebPay config values.
• Click the green button in the Zen Cart admin sidebar that says “Click here to login and Authorize your account.” If everything is correct, the Sort Order LED for Square WebPay will go green.
• Click the Edit button one more time. This will fill in the Location ID field. Click Update.

Upgrading to Square Web Payments from Square Payments Form

1. Go to Admin > Modules > Payment > Square, click Edit, and set Enable Square Module to false, then click Update.
2. Login at https://connect.squareup.com/apps and rename your existing Square app to something like “OLD Webstore”.
3. Use the Installation instructions above.
4. Once you are certain Square Web Payments is working, Go to Admin > Modules > Payment > Square and click Remove.

Square Errors

If you get an error from Square (in particular, “The provided OAuth access token has expired”), see Square Error Messages.