If your academy uses Square and has a Square Terminal at the front desk, DojoMesh can send an invoice straight to it. You click one button on the invoice, the amount appears on the reader, the customer taps their card, and the invoice is marked paid for you. This guide covers pairing the reader once and then taking payments day to day.
Before you start
You will need:
- Square already connected to DojoMesh, with Card Processing Gateway set to Square and Environment set to Production (Live). If you have not done that yet, follow Connect Square to DojoMesh first.
- A Square Terminal, the all-in-one reader with its own screen, switched on and connected to wifi. It must belong to the same Square account you connected to DojoMesh.
- Nothing to switch on. Card readers appear by themselves as soon as your Square connection is complete, so there is nothing to request and no waiting on us. If you do not see the card described in step 1, it is almost always the first item on this list: open Settings, Gym Settings, Payment Methods and check that Square is ticked, the gateway is Square, and your Application ID, Access Token and Location are all filled in. If that all looks right and the card is still missing, contact us.
- About ten minutes for the one-time pairing. After that, taking a payment is three clicks.
DojoMesh tells your reader how much to charge and waits for Square to confirm the payment. The money lands in your Square balance like any other Square sale, under the same location as your other DojoMesh card payments. The invoice itself stays in DojoMesh. Nothing is created in Square Invoices, and DojoMesh does not add a fee on top of Square's normal in-person rate.
Once a reader is signed in with a DojoMesh pairing code, it waits for payments sent from DojoMesh. You cannot key in a sale on the reader itself while it is signed in that way. If you also use the same reader for walk-up sales through Square's own app, see Managing your readers for how to switch back and forth, or consider keeping a second reader for that.
Open Card Readers in Gym Settings
- Sign in to your DojoMesh admin panel.
- In the top menu open SettingsGym Settings.
- Scroll to the Card Readers (Square Terminal) card, just below Payment Methods.
The card lists every reader you have paired, with the name you gave it and when it was last used. On a new setup the list is empty.
It only appears when Square is your card gateway, all of your Square credentials are filled in, and in-person payments have been enabled for your academy. Academies on Stripe do not have this feature. The Troubleshooting table lists each cause.
Get a pairing code
- Click Pair a Reader.
- Give the reader a name your staff will recognise, such as Front desk. If you have more than one reader, this is the name they will pick from when taking a payment.
- Click Get Pairing Code. DojoMesh shows a short code in large type with a countdown.
The code is good for five minutes and works once. Leave this window open and pick up the reader.
Enter the code on the reader
- On the Square Terminal, go to the sign-in screen. If the reader is currently signed in to Square's own app, sign out first from its settings menu.
- Tap Sign in, then choose Use a device code.
- Type the code from DojoMesh and confirm.
Within a few seconds the pairing window in DojoMesh changes to Paired and the reader appears in your list. The reader now shows a waiting screen. That is normal: it is waiting for DojoMesh to send it a payment.
Nothing is lost. Click Get Pairing Code again for a fresh one. An expired or mistyped code never pairs anything.
Take a payment on an invoice
On the Create Invoice form, use Create & Collect on Reader instead of Create Invoice. The invoice is saved and the reader window opens straight away — carry on from step 3 below. Nothing is charged until you press Send to Reader.
For an invoice you already created, open it and use the Collect on Card Reader button at the top of the page, beside Email Invoice and Mark as Paid. Both buttons appear once you have paired a reader.
You can also take payment for any unpaid invoice from the invoice list:
- In the top menu open FinancialManage Invoices. If the sale does not have an invoice yet, create one first with Create Invoice.
- Find the unpaid invoice and click the Take Payment on Terminal button in its row. It sits beside Mark as Paid and only appears on invoices that are still unpaid.
- Check the customer name and amount, choose the reader if you have more than one (with a single reader its name is simply shown), and click Send to Reader.
- Hand the reader to the customer. They tap, insert or swipe as usual.
- When Square confirms the payment, the window shows Paid and the invoice row updates. You are done.
The reader always charges the full invoice total. Marking the invoice paid this way does everything Mark as Paid does: it records the payment against the member, extends a membership if the invoice has one, and takes sold items out of stock.
| The window says | What is happening |
|---|---|
| Sending to reader | DojoMesh is passing the amount to Square. Usually a second or two. |
| Waiting for the reader | Square has the payment and is passing it to the reader. If this lasts more than a few seconds, check the reader is on and connected. |
| Waiting for customer | The amount is on the reader. A countdown shows how long is left; the reader gives up after five minutes. |
| Paid | Square confirmed the payment and the invoice is marked paid. |
| Cancelled, no charge was made | You or the customer cancelled. The invoice is still unpaid and you can try again. |
| Timed out, no charge was made | Nobody presented a card within five minutes. Try again when the customer is ready. |
| Payment taken but needs attention | Rare. The card was charged but DojoMesh could not apply it to the invoice. See the next section. |
If the invoice includes a membership and the member already has an active recurring payment, DojoMesh warns you before anything is sent to the reader, because charging them at the counter as well could bill them twice. Continue only if you really are taking this payment by hand.
Run a one-dollar test
Before using the reader with a real member, prove the whole round trip with your own card.
- Create an invoice for yourself or a staff member with a single custom line of one dollar.
- Take the payment on the reader as in step 4 and wait for Paid.
- Confirm the sale appears in your Square Dashboard.
- Refund it in your Square Dashboard, then use Reverse Payment on the invoice in DojoMesh and void it. See Refunds below.
If all four steps work, you have proven the whole round trip: charging, the sale reaching Square, and undoing it.
When something goes wrong at the counter
The customer changes their mind
They can press cancel on the reader, or you can click Cancel Payment in DojoMesh. The window shows Cancelling for a moment while Square confirms. If the customer tapped their card at the same instant, the payment wins and the window will show Paid instead. DojoMesh always reports what Square says actually happened.
The card is declined
The reader tells the customer and asks for another card. Nothing changes in DojoMesh; the window keeps waiting. If they have no other card, cancel and take payment another way.
The reader is off, asleep or off wifi
The window stays on Waiting and, after about fifteen seconds, suggests checking the reader. Wake it or reconnect it and the amount appears. If you cannot get it online, click Cancel Payment.
You closed the window, or your computer lost its connection
The payment does not depend on your browser. If the customer pays, DojoMesh still marks the invoice paid on its own, normally within a minute. While a payment is in progress the reader button on that invoice turns yellow, and clicking it reopens the same payment rather than starting a second one.
"Payment taken but needs attention"
This means the customer's card was charged, but the invoice could not be marked paid. The usual cause is that the invoice changed while the reader was waiting: someone marked it paid by cash, edited it, voided it, or the customer paid it online at the same moment. DojoMesh records the payment against the member so the money is not lost, shows a notice on Manage Invoices until it is dealt with, and lets us know as well.
To sort it out, decide whether the customer has now paid twice. If they have, refund the flagged payment in your Square Dashboard (see Refunds). Either way, click the notice on Manage Invoices and choose Mark as handled once it is sorted out.
While a reader is waiting on an invoice, leave that invoice alone. Do not mark it paid, edit it or void it until the window has finished.
Refunds
Refunds for reader payments are made in Square, not in DojoMesh. For security reasons DojoMesh does not send money back to a card once a live payment has been made, so a refund always needs someone to log in to your Square account.
- Log in to your Square Dashboard and open Transactions. Find the payment (its note reads "DojoMesh invoice" followed by the invoice number) and click Refund. The money goes back to the customer's card. The customer does not need to be present and you do not need the reader.
- In DojoMesh, open FinancialManage Invoices and click Reverse Payment on the invoice. This removes the payment from your reports, puts any products back in stock and moves a membership due date back. The invoice returns to unpaid.
- Void the invoice if the sale is not going ahead, so that it cannot be charged again by mistake.
Reverse Payment only changes your DojoMesh records. When you reverse an invoice that was paid on the reader, DojoMesh reminds you, before and after, that the card still needs to be refunded in Square. Do both steps, or the customer stays charged.
Within the hour of a refund in Square, DojoMesh notices that the money has gone back while the invoice here is still marked paid, and lists it under reader payments that need attention on Manage Invoices, with a link to the invoice. Nothing is changed for you — the reminder simply stays until you run Reverse Payment or mark it as handled.
Managing your readers
- Rename a reader from the Card Readers card at any time. The name is only for your staff.
- More than one reader: pair each one the same way. Staff choose which reader to use each time they take a payment. A reader can only handle one payment at a time.
- Unpair a reader you no longer use by clicking Unpair beside it, then sign the reader out from its own settings menu. Past payments taken on it are kept.
- Replaced or reset a reader? Unpair the old entry and pair the new device from step 2.
- Using the reader for walk-up Square sales again: sign the reader out, then sign in with your normal Square login. To return it to DojoMesh, sign out and pair it again with a new code.
Troubleshooting
| What you see | What it usually means |
|---|---|
| No Card Readers card in Gym Settings, and no reader button on invoices | One of: Card Processing Gateway is not set to Square; a Square credential is blank or the Square Credit Card box is unticked; or in-person payments have not been enabled for your academy yet. Academies using Stripe do not have this feature. |
| The payment window says no reader is paired | Pair a reader first, from step 2. Readers are paired per Square environment, so a reader paired while testing in Sandbox does not carry over to Production. |
| The pairing code is rejected by the reader | The code expired (five minutes), was mistyped, or the reader belongs to a different Square account from the one connected to DojoMesh. Get a new code and check which Square account the reader is registered to. |
| Pairing fails with an authorization error | The Access Token in Gym Settings is wrong or has been replaced in Square. Re-paste it as described in the Square setup guide. |
| "This reader is busy" | Another payment is still open on that reader. Finish or cancel it first, or pick a different reader. |
| The window stays on Waiting and nothing shows on the reader | The reader is off, asleep or off wifi, or it has been signed out of DojoMesh pairing. Wake it and check its connection. If it shows Square's normal sign-in or sales screen, pair it again. |
| The payment worked for a while and now every attempt fails immediately | The reader was signed out or reset, or the Square Access Token was replaced. Re-pair the reader, and check the token in Gym Settings. |
| The customer paid but the invoice still shows unpaid | Wait a minute and refresh; DojoMesh confirms every payment with Square in the background even if your browser missed it. If it still shows unpaid after a few minutes, look for a needs attention notice on Manage Invoices and contact us. Do not charge the customer again. |
| No reader button on a particular invoice | The invoice is already paid or void, or its total is below the smallest amount Square will charge. |
Common questions
Does DojoMesh take a cut of in-person payments?
No. You pay Square's normal in-person processing rate to Square, and nothing extra to DojoMesh.
Which Square hardware works?
The Square Terminal, the standalone reader with its own touchscreen. The small Square Reader that pairs with a phone, and Square Stand, cannot receive payments from other software and will not work for this.
We use Stripe. Can we do this?
Not at the moment. In-person reader payments are available to academies whose card gateway is Square.
Can the customer pay part of an invoice on the reader?
No. The reader always charges the full invoice total. If someone is paying in parts, create a separate invoice for each part.
Can customers add a tip?
No. Tipping is switched off for payments sent from DojoMesh, so the amount on the reader always matches the invoice.
Do customers get a receipt?
The reader offers its usual Square receipt after the payment. You can also send a DojoMesh receipt from the invoice or the payment, the same as for any other payment.
Will these payments show up in my Square Dashboard?
Yes, alongside your other sales, under the same location as your other DojoMesh card payments. Each one carries a note with the DojoMesh invoice number so you can match them up.
Do I have to set anything up in the Square Developer Dashboard?
No. If Square is already connected to DojoMesh, the same credentials cover the reader. There is nothing new to create or copy.
Can two staff members charge the same invoice by accident?
No. An invoice can only have one reader payment open at a time. A second click, a second tab or a second staff member joins the payment already in progress instead of starting another.
What happens if our internet drops halfway through?
If the reader loses its connection before the customer pays, nothing is charged and the payment times out. If your computer loses its connection after the amount reached the reader, the customer can still pay and DojoMesh marks the invoice paid as soon as it hears from Square.