# Square Module

https://docs.wisecp.com/en/square-module

Take card payments through Square inside your checkout and let clients save a card for later payments.

## Reaching the Screen

Go to **Settings → Financial → Payment Gateways**, open **All Modules** and click the **Square** card: `{admin}/modules/payment?module=Square`

Adding the gateway to the method list clients see is covered in [Payment Modules](https://docs.wisecp.com/en/payment-modules).

## What Is on the Screen

One settings form: three Square credentials, the notification pair, two switches and the shared gateway settings every module carries.

Clients meet Square's own card fields inside the payment page, so they never leave your site. The card number goes straight to Square and your install keeps only a token.

The module keeps cards for later, charges a kept card on renewal, opens subscriptions and refunds a payment from the invoice screen. It does not accept a card number typed into your own form, and it offers no installments.

## Before You Configure It

- A Square account and an application in the Square Developer Console.
- Sandbox and production credentials are separate sets. Use one set at a time.
- The currency of the seller location you book payments against. Square settles in that currency.
- For kept cards and automatic renewal payments, this module chosen under **Card Storage Module** in **Initial Settings**.

## Fields

- **Application ID**: The application the card fields are loaded with. Required.
- **Location ID**: The seller location each payment is booked against. Required.
- **Access Token**: The server side token behind every charge, refund and subscription call. Required.
- **Webhook Signature Key**: The key that proves a notification really came from Square. Without it every notification is refused.
- **Webhook Notification URL**: The address you registered at Square, character for character. Square signs the address together with the message, so one different character fails every check.
- **Recurring Subscriptions**: Offers an automatic renewal option on the payment panel. Off by default. See Tasks before you turn it on.
- **Test Mode**: Sends every call to the Square sandbox. Off by default, so tick it while you test with sandbox credentials.

**Status**, **Commission Rate (%)**, **Converting Currency**, **Accepted Amount Range** and the country lists work the same way in every gateway. See [Payment Modules](https://docs.wisecp.com/en/payment-modules). **Update Subscription Fee** lets the system rewrite the recurring figure at Square when a renewal total changes; it is off by default. **Callback URL**, **Success URL** and **Failed URL** cannot be edited: copy them with the icon at the end of the field.

## Tasks

### Take the credentials from Square

1. Sign in to the Square Developer Console and open your application.
2. Open **Credentials** and pick the **Sandbox** or **Production** tab. Copy the application id and the access token from the same tab.
3. Open **Locations** and copy the id of the location you sell from.

### Enter the credentials

1. Open the module card and tick **Status**. The other fields stay locked until you do, and nothing else is saved while it is off.
2. Fill in **Application ID**, **Location ID** and **Access Token**. Tick **Test Mode** if the credentials are sandbox ones.
3. Click **Save Changes**. Clients who pick this method now see the Square card fields.
4. Pay a test invoice using sandbox credentials and a Square test card. Check both the provider transaction and the invoice's **Paid** status.

### Register the notification address

1. Copy the **Callback URL** from the module card with the icon at the end of the field.
2. In the Developer Console open **Webhooks → Subscriptions** and click **Add subscription**. Paste the address as the notification URL and subscribe to the `payment.updated` event.
3. Open the new subscription and copy its signature key from **Endpoint Details**.
4. Back on the module card, paste that key into **Webhook Signature Key** and the same address into **Webhook Notification URL**, then click **Save Changes**. Square can now report a payment that finishes later.

### Let clients keep their card

1. Go back to **Settings → Financial → Payment Gateways** and open **Initial Settings**.
2. Choose **Square** under **Card Storage Module** and click **Save Changes**.
3. Clients can now add a card from their account, pick a kept card while paying and turn on automatic payment.

### Offer subscriptions

1. Finish the card storage step first. A subscription bills a card kept on file, so it cannot work without it.
2. Tick **Recurring Subscriptions** on the module card and click **Save Changes**.
3. The module adds one reusable plan to your Square catalogue for each billing cycle it needs. The charged figure is set per subscription, never taken from the plan.
4. The payment panel offers a Square subscription for supported cycles; five-month terms are unavailable. Check later subscription charges against WISECP renewal invoices: they may not be recorded automatically in this version.

### What the client goes through

Card storage, automatic payment and subscription options require the account owner paying for their own account. Shared payment links do not offer them.

1. The client picks this method at checkout, on an invoice or when adding funds.
2. The card fields open in place. The client enters a card or picks one kept earlier. Two tick boxes offer to keep the card and to pay future invoices with it.
3. When subscriptions are on, the client also picks which renewing lines join one agreement. Picking a line keeps the card as well.
4. Square charges the card. The payment closes the invoice and the service is activated.

### Refund a payment

1. Open the paid invoice: `{admin}/invoices/detail?id={invoice}`
2. Under **Summary → Change Status**, select **Refunded** and **Refund via payment gateway**. Click **Update Status**.
3. Square returns the amount that was collected for that invoice.

## Things to Watch

> **The address has to match**
> 
> Square signs the URL with the message. An empty **Webhook Notification URL** uses the module's **Callback URL**. This address must match the URL registered at Square. A wrong URL or missing signature key prevents verification, so a later payment confirmation may leave its invoice open.

> **Subscriptions write to your Square catalogue**
> 
> Turning the option on lets this install add plans to the seller catalogue you also use elsewhere. Each cycle needs one plan, created once and reused. Removing those plans at Square stops new agreements from opening.

> **One environment at a time**
> 
> Sandbox and production have their own application ids, tokens, locations and notification subscriptions. Mixing a token from one with an id from the other fails every call. Test Mode arrives unticked, so tick it while you test.

## Required Privileges

**Payment Module Settings** (`MODULES_PAYMENT_SETTINGS`) is required. Invoice refunds also require `INVOICES_OPERATION`.

## Related Articles

- [Payment Modules](https://docs.wisecp.com/en/payment-modules)
- [Invoice Detail Overview](https://docs.wisecp.com/en/invoice-detail-overview)
- [Subscriptions](https://docs.wisecp.com/en/subscriptions)
- [Module Management](https://docs.wisecp.com/en/module-management)