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 will cease 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. Login at https://connect.squareup.com/apps to view the apps you’ve connected to your account.
3. Click + to create a New Application for your Zen Cart store. Give it a name, such as “WebPay”.
4. Version 1.0.1 of Square Web Payments requires API Version 2022-02-16. Ensure you have selected the correct version and click Save.
5. Click on the application icon that was just created (named “WebPay” or whatever name you used).
6. The environment will be Sandbox by default. Click “Production”.
7. Copy and Paste the Production Application ID into your Square WebPay configuration Application ID field in Zen Cart admin.
8. 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.)
9. 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.
10. 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.

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.