JoomInvoice - Square Payment Setup Guide

This guide walks you through setting up Square payments in JoomInvoice so your customers can pay invoices online. The plugin uses Square Hosted Checkout (Payment Links): customers click a button, pay securely on a Square-hosted page, and are redirected back to your site — no card data ever touches your server.

Prerequisites

Before you begin, ensure you have:

• Square Account: Create a free account at squareup.com if you don't have one
• Square Developer App: Create one at developer.squareup.com
• JoomInvoice Component: Installed and working on your Joomla site
• SSL Certificate: Your site must use HTTPS (required by Square)
• Square Payment Plugin: The "JoomInvoice - Payment - Square" plugin must be installed

Step 1: Get Your Square Credentials

1. Log in to the Square Developer Dashboard
2. Open your Application (or create one)
3. Use the Sandbox / Production switch at the top to choose the environment you are configuring
4. From the left menu, open Credentials and copy the Access Token
5. From the left menu, open Locations and copy the Location ID of the business location that should receive the payments

You will have two sets of values:

Security Note: Never share your Access Token publicly. Keep it confidential.

Step 2: Enable the Square Plugin

1. In Joomla Administrator, go to Extensions → Plugins
2. Search for "square" or "JoomInvoice - Payment - Square"
3. Click on the plugin name to open its settings
4. Set Status to Enabled

Step 3: Configure Plugin Settings

In the plugin configuration, set the following options:

Mode

• Sandbox: Use for development and testing (recommended to start)
• Production: Use for real payments

Credentials

For Sandbox Mode:

• Sandbox Access Token: Enter your sandbox access token
• Sandbox Location ID: Enter your sandbox location ID

For Production Mode:

• Access Token: Enter your production access token
• Location ID: Enter your production location ID

Webhooks (Optional but Recommended)

• Enable Webhooks: Set to "Yes" for more reliable payment tracking
• Webhook Signature Key: Enter the signature key from Square (see Step 4)

Additional Options

• Tab title: The label of the payment tab (default: "Square")
• Description text: The message shown above the payment button (default: "Click on the button to pay with Square")
• Require shipping address: Set to "Yes" to ask the buyer for a shipping address on the Square checkout page

Click Save & Close when done.

Important: Currency must match your Square location

Square only accepts payments in the currency of your Square account's country. For example, a US Square account (sandbox or production) accepts only USD; a Eurozone account accepts only EUR.

The invoice's currency must match your Square location's currency. Otherwise Square rejects the request when the checkout link is created, and the buyer sees an error instead of the pay button.

• Check your location's currency in the Square Developer Dashboard under Locations.
• Set the invoice's currency (or the component's default currency) to match.

Step 4: Set Up Webhooks (Recommended)

Webhooks provide reliable payment confirmation, especially if a customer closes their browser after paying.

Create the Webhook in Square

1. Go to the Square Developer Dashboard → your App → Webhooks → Subscriptions
2. Click Add Endpoint
3. Enter your Notification URL:

https://www.yourwebsite.com/index.php?option=com_joominvoice&task=process_payment&ptype=payment_square&paction=webhook

Important: Replace www.yourwebsite.com with your actual domain. This URL must match your site's canonical URL exactly (it is part of the signature).

4. Under Events, subscribe to:

   • payment.updated

5. Save the subscription

Get the Signature Key

1. Open the webhook subscription you just created
2. Copy the Signature Key
3. Paste it into the Webhook Signature Key field in the plugin settings and save

Webhook URL Requirements

• Use HTTPS (required by Square)
• Ensure www vs non-www matches your site's canonical URL exactly
• Do not add trailing slashes or extra parameters
• The URL must be publicly accessible

Step 5: Test Your Setup

Use Sandbox Mode First

1. Ensure the plugin is set to Sandbox mode with your sandbox credentials.
2. Create a test invoice in the currency of your Square sandbox location (see Important: Currency), and add a payment to it.
3. View the invoice on the frontend, open the Square payment tab, and click the pay button.
4. Because Square's hosted checkout uses Payment Links, the sandbox opens the Checkout API Sandbox Testing Panel (a simulator) rather than a card form. Click through:
   • Overview (shows the created order and checkout link) -> Next
   • Test Payment -> Test Payment (simulates a successful card payment)
   • Checkout Complete -> you are redirected back to JoomInvoice

In Production, your real customers instead see Square's normal hosted card-entry checkout page - there is no testing panel.

Verify the Payment Flow

1. After the simulated payment you are redirected back to JoomInvoice.
2. Check that the payment shows as Paid in JoomInvoice -> Payments.
3. Verify the order/payment appears in your Square sandbox dashboard.

Step 6: Go Live

Once testing is complete:

1. In the plugin settings, change Mode from "Sandbox" to "Production"
2. Enter your Production Access Token and Location ID
3. If using webhooks, create a separate webhook subscription in the Production environment using the same Notification URL, and copy its Signature Key into the plugin
4. Save the plugin settings
5. Test with a small real transaction to confirm everything works

Troubleshooting

Payment Not Marked as Paid

Without Webhooks:

• The payment is recorded when the customer returns to your site after paying
• If they close the browser before returning, the payment won't be recorded
• Solution: Enable webhooks for reliable payment tracking

With Webhooks:

• Check that the Notification URL is correct and publicly accessible
• Verify the Signature Key matches in both Square and the plugin
• Check the Square Developer Dashboard → Webhooks for delivery errors

"Square payment is not configured" Message

• The Access Token or Location ID for the active mode is empty
• Double-check you pasted the Sandbox values when in Sandbox mode (and Production values when in Production mode)

"Your checkout session has expired" Warning

• The checkout session has expired or was already used
• Ask the customer to start the payment again from the invoice page

Invalid Signature / Webhook Rejected

• The Signature Key may be incorrect — copy it again from Square and update the plugin
• The Notification URL configured in Square must match your site's canonical URL exactly (www vs non-www, HTTPS)
• Make sure there are no extra spaces when pasting

Security Best Practices

1. Always use HTTPS — Square requires secure connections
2. Keep your Access Token secret — never expose it in frontend code or public repositories
3. Use webhooks — they provide reliable payment confirmation
4. Test thoroughly — always test in Sandbox mode before going live
5. Monitor payments — regularly check your Square dashboard for suspicious activity