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.

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

Status, Commission Rate (%), Converting Currency, Accepted Amount Range and the country lists work the same way in every gateway. See 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

Required Privileges

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

Related Articles

• Payment Modules
• Invoice Detail Overview
• Subscriptions
• Module Management