Integrate Square with Paymattic

Square is a globally recognized payment gateway that you can integrate with Paymattic. This article will guide you through configuring Square in your WordPress Site with the Paymattic plugin.

Prerequisites

To get access to the Square payment gateway, you need the Paymattic Pro Plugin.

Configuring Square Payment Method

Follow these steps to configure the Square payment gateway through Paymattic:

Step 1: Access Square Settings

1. Go to Payment Gateway from the Paymattic Navbar
2. Click the Square tab from the left sidebar
3. The Square Settings page will open, showing the Payment Mode, Test/Live Access Key, Test/Live Location Id, and Test/Live Webhook Signature Key fields, along with the Webhook URL and the recommended Webhook Events you will subscribe to in Square later on.

Step 2: Choose Payment Mode

1. Select Payment Mode: Choose between Test (for test payments) and Live (for real payments). Both options follow the same configuration process. For this example, we will use Test Mode.

2. Next, you need to obtain the Access Key, Location ID, and Webhook Signature Key from your Square Account for the selected mode.

Step 3: Get Square Credentials

To learn how to get an Access Token and Location ID from your Square account, follow the steps below.

NOTE

To get the credentials for configuration, you need to create an app in your Square account. The following steps will guide you on how to do this.

1. First, log in to your Square Developer Dashboard, go to the Account section from the navigation bar.

2. Click the Developer Dashboard tab.

3. Under the Applications tab click on the Plus Icon to create a new application

4. Configure your application:
   • Enter a Name for your application
   • Click Next

7. Set application permissions:
   • Check the Accept Payments box
   • Click Next

8. Complete setup:
   • Select your desired audience option
   • Click Complete

Get Access Token and Location ID

1. Get Access Token:
   • Find the Sandbox Access Token under Credentials
   • Copy the token

2. Get Location ID:
   • Go to the Locations tab in the left sidebar
   • Copy your Location ID

Configuring Webhooks in Square

Important

To ensure your Square dashboard and Paymattic dashboard stay synchronized and fully functional for all payment types (recurring), you must configure Square Webhooks.

Step 1: Add the Webhook Subscription in Square

1. Click on the Webhooks section from the left sidebar, then open the Subscriptions tab.

2. Click the Add Subscription button.

3. Configure the webhook:
   • Give it a Name
   • Paste the Webhook URL you copied from the Square Settings page in Paymattic (Step 1 above)
   • Confirm your API version
   • Select the recommended events

Webhook Events

The recommended events and their purposes:

1. invoice.created

   • Triggers when an invoice is created
   • Occurs after order placement or subscription billing cycle start

2. invoice.payment_made

   • Triggers on successful payment completion
   • Covers both partial and full payments

3. payment.updated

   • Triggers when payment status changes
   • Includes completions, declines, and refunds

4. subscription.created

   • Triggers when a customer subscribes to a plan

5. subscription.updated

   • Triggers when subscription details change
   • Covers status changes (paused/resumed/canceled)
   • Includes billing cycle or pricing updates

4. Click Save to complete the webhook configuration

Step 2: Copy the Webhook Signature Key

After saving, Square generates a Signature Key for that subscription. Paymattic uses this key to verify that incoming webhook requests genuinely come from Square, so it must be configured for webhooks to work.

1. From the Webhook subscriptions list, click on the subscription you just created to open its details.
2. Copy the Signature Key.

Step 3: Configure in Paymattic

1. Go back to your WordPress dashboard and navigate to Paymattic → Payment Gateway, then click the Square tab.

2. Paste the copied Access Token into the Access Key field.

3. Paste the copied Location ID into the Location ID field.

4. Paste the copied Signature Key into the Webhook Signature Key field.

5. Finally, press the Save Settings button.

Your Square account will now be integrated with Paymattic for your WordPress Site.

Per-Mode Signature Keys

Square generates a separate Signature Key for each webhook subscription. If you configure webhooks for both Test and Live mode, make sure you copy each mode's Signature Key into the Signature Key field under its matching mode in Paymattic. Mixing up the keys will cause webhook signature verification to fail, and your payment/subscription statuses will stop syncing.

Using Square in Forms

Once you've completed the setup, you can add Square to your forms:

1. For existing forms: Add it to any Payment Form

2. For new forms:

   • Create a Form from Scratch
   • Use Form Templates

3. Learn more about adding payment methods

Note

The Square payment method will not function unless you complete the configuration process properly.