Stripe is one of the two card processors DojoMesh can use to store cards on file, run recurring billing, take one-time card payments in the member portal and issue refunds. Connecting it takes two keys from your Stripe Dashboard, one settings page in DojoMesh, and an optional webhook that keeps refunds in sync.
Before you start
You will need:
- A Stripe account for your academy that has been activated. A brand-new account can run test payments straight away, but Stripe will not let it take real money until you have completed its activation form with your business details and bank account.
- An admin login to DojoMesh for your academy, at https://your-academy.dojomesh.com/platform/.
- About fifteen minutes. There is nothing to install.
DojoMesh talks to Stripe directly using your own account. Payments land in your Stripe balance, pay out to your bank on Stripe's normal schedule, and appear in your Stripe Dashboard with the member's name attached. DojoMesh does not add a percentage on top; you pay Stripe's normal processing fee to Stripe.
DojoMesh runs one card processor per academy. If you are switching from Square, cards your members saved through Square will not carry over. See Switching from Square at the end of this guide before you change anything.
Sign in to Stripe and choose Test or Live
Go to dashboard.stripe.com and sign in. If you run more than one business in Stripe, use the account switcher in the top-left corner to pick the academy.
Stripe keeps two completely separate worlds inside every account:
| Mode | What it does | Choose it when |
|---|---|---|
| Test | Pretend payments. Nothing is charged and no money moves. Uses Stripe's test card numbers. Keys begin pk_test_ and sk_test_. | You want to click through the whole flow first and see how it feels before real members are involved. Works even before your account is activated. |
| Live | Real payments. Cards are really charged and the money lands in your Stripe balance. Keys begin pk_live_ and sk_live_. | Your account is activated and you are ready to bill members now. |
You switch between them with the Test mode toggle in the top-right corner of the Dashboard. Newer Stripe accounts call the test side a Sandbox instead and offer it from the same corner; the keys it gives you still begin pk_test_ and sk_test_, and everything in this guide applies the same way.
Whichever you pick, you must select the matching Mode inside DojoMesh in step 3. DojoMesh reads the prefix on your keys and will refuse to save a test key with the other key from live, but it cannot tell if you meant to be in a different mode altogether.
Do a quick Test run first (steps 2 to 5), then repeat steps 2 to 4 with live keys. The section Going live after testing covers the switch.
Copy your API keys
- Click Developers. Depending on your account's layout it is either in the bottom-left corner of the sidebar or in the top-right of the page.
- Open the API keys tab.
- Under Standard keys you will see two rows.
| Value | How to copy it | What it looks like |
|---|---|---|
| Publishable key | Shown in full. Click it to copy. | pk_test_… or pk_live_… |
| Secret key | Hidden. Click Reveal test key or Reveal live key, then click the key to copy it. Stripe may ask for your password first. | sk_test_… or sk_live_… |
Copy each one somewhere safe for a moment, such as a private note, and delete it once you have pasted it into DojoMesh.
Anyone holding it can charge cards and issue refunds on your Stripe account. Never email it, paste it into a chat, or include it in a screenshot when asking for help. DojoMesh support will never ask you to send it. The publishable key is safe: it only lets a browser show the card entry form, and it cannot move money on its own.
On newer accounts, revealing a live secret key shows it a single time. If you lose it, you do not need to panic: go back to API keys, click the three-dot menu on the secret key row, and choose Roll key to get a new one. Rolling the key stops the old one working, so paste the new one into DojoMesh straight away.
Enter the keys in DojoMesh
Now switch to your DojoMesh admin panel.
- Sign in at https://your-academy.dojomesh.com/platform/. If you use your own domain, sign in there instead; the pages are the same.
- In the top menu open SettingsGym Settings.
- Scroll to the Payment Methods card.
- Tick Stripe Credit Card. A set of Stripe fields appears underneath.
- Fill in the fields using the table below. Leave Webhook Signing Secret empty for now; step 4 comes back for it.
- Just below the Stripe section, set Card Processing Gateway to Stripe. This is the switch that tells DojoMesh to use Stripe for cards on file, recurring billing and online checkout. New accounts default to Square, so this step is not optional.
- Click Save Settings at the bottom of the page.
| DojoMesh field | What to enter |
|---|---|
| Mode | Test (Testing) or Live (Production). Must match the mode your keys came from in step 1. |
| Publishable Key | The pk_… value from step 2. |
| Secret Key | The sk_… value from step 2. Paste it once and do not retype it by hand. |
| Webhook Signing Secret | Leave blank until step 4. |
DojoMesh checks the keys as you save. It will refuse to save, and tell you why, if either key is blank, if a key does not start with the expected prefix, or if one key is a test key and the other is a live key. It also refuses if you pick Stripe as the gateway without ticking the Stripe box, so do both together.
Some browser password managers try to fill the Secret Key field with a saved password. If DojoMesh says the key "looks invalid", clear the field, paste the key again, and save before anything else touches the page.
Add the webhook
A webhook is a way for Stripe to tell DojoMesh when something happens on Stripe's side. DojoMesh uses it for two things: keeping a payment's record correct when you refund it from the Stripe Dashboard instead of from DojoMesh, and logging recurring charges that fail after the fact. Payments work without it, but recurring billing is more reliable with it, so we recommend setting it up.
First, get your webhook address. It is printed under the Webhook Signing Secret field in Gym Settings and looks like this:
https://your-academy.dojomesh.com/platform/stripe_tenant_webhook.php
Copy it exactly as shown on your own settings page, since it contains your academy's address. Then, back in Stripe:
- Make sure you are still in the same mode as your keys. Webhooks are per mode: a test-mode webhook does nothing for live payments and the other way round.
- Click Developers, then the Webhooks tab. On newer accounts this is called Event destinations.
- Click Add endpoint or Add destination. If asked where events should go, choose Webhook endpoint.
- Paste your webhook address into Endpoint URL.
- Under events to send, search for and tick these three:
- charge.refunded
- charge.refund.updated
- payment_intent.payment_failed
- Click Add endpoint to save it. Stripe opens the new endpoint's page.
- Find Signing secret and click Reveal. Copy the value. It begins whsec_.
- Return to DojoMesh Gym Settings, paste it into Webhook Signing Secret, and click Save Settings.
Ticking other events as well does no harm. DojoMesh ignores anything it does not recognise.
The signing secret is how DojoMesh proves a message really came from Stripe and not from someone who found the address. Until it is saved, DojoMesh refuses every webhook delivery, and Stripe will show those attempts as failed on the endpoint's page. That is expected, and it clears up as soon as the secret is in place.
Run a test payment
Saving the settings does not contact Stripe. The first real check is adding a card, because that uses both keys: the publishable key loads the card form and the secret key saves the card to a customer in your Stripe account.
- In the top menu open FinancialCards on File.
- Click Add Card and choose a member. For a first test use your own member record or a staff member, not a real student.
- Enter a card and save it.
- Back on Cards on File, charge that card a small amount, for example one dollar.
- Open your Stripe Dashboard, go to Payments, and confirm the charge is there. Open Customers and you will see the member too.
If you are in Test mode
Real card numbers are rejected in Test mode. Use Stripe's test cards instead. Any future expiry date, any three-digit CVC and any postal code will do.
| Card number | What it does |
|---|---|
| 4242 4242 4242 4242 | Always succeeds. Use this for the normal walkthrough. |
| 4000 0000 0000 9995 | Always declines. Useful for seeing what a failed charge looks like in DojoMesh. |
| 4000 0025 0000 3155 | Asks for extra authentication. See the note on card authentication below. |
Test payments appear in the Stripe Dashboard while the Test mode toggle is on, and vanish from view when you switch it off. They never touched real money.
If you are in Live mode
Use a real card that you own. Charge one dollar, confirm it shows in your Stripe Dashboard, then refund it from the payment's row in FinancialManage Payments. That single round trip proves charging and refunding both work before any member is involved.
If you set up the webhook in step 4, try the reverse as well: refund a second one-dollar charge from the Stripe Dashboard instead, then reload Manage Payments in DojoMesh. Within a few seconds the payment should show as refunded there too. If it does not, check the troubleshooting table.
Going live after testing
When you are done in Test mode and ready to bill real members, you need to replace everything in the Stripe section of Gym Settings, not just the Mode dropdown.
- Make sure your Stripe account is activated. Stripe will not issue live keys until it is.
- Switch the Test mode toggle off in the Stripe Dashboard.
- Copy the live Publishable key and Secret key (step 2).
- Add a live webhook endpoint exactly as in step 4 and copy its signing secret. The test-mode endpoint you already made will not fire for live payments.
- In DojoMesh Gym Settings, change Mode to Live (Production), paste the three new values over the old ones, and save.
- Run the one-dollar charge and refund from step 5 with a real card.
Cards saved while in Test mode exist only in Stripe's test world. After switching to Live they will not charge. Delete them from Cards on File and add real cards fresh. Members can add their own card from the portal, or you can email them a secure card-update link with the Send Card Links button at the top of Cards on File.
Troubleshooting
| What you see | What it usually means |
|---|---|
| Gym Settings will not save and says a key "looks invalid" | The key was pasted incompletely, or a password manager replaced it. Publishable keys start pk_, secret keys sk_. Clear the field and paste again. |
| "Your Stripe keys are mismatched" | One key is from Test mode and the other from Live. Go back to the API keys page with the toggle in the right position and copy both again. |
| "Stripe is selected as the card gateway but Stripe payments are not enabled" | The Stripe Credit Card box is unticked. Tick it, then save. |
| Cards on File still shows the Square page, or says Square is not configured | Card Processing Gateway is still set to Square. Change it to Stripe and save. |
| The card entry form on Add Card never appears, or is blank | The publishable key is wrong or does not match the Mode. A browser ad-blocker that blocks js.stripe.com causes the same symptom; try a private window. |
| Card form appears but saving the card or charging fails with an "invalid API key" or authentication error | The secret key is wrong, was copied incompletely, belongs to the other mode, or has been rolled in Stripe. Reveal it again on the API keys page and paste it fresh. |
| Charge fails saying the card "requires authentication" | The member's bank wants them to approve the charge themselves. See the note on card authentication below. |
| Error mentioning currency | Your academy's currency in DojoMesh must be one your Stripe account can settle. Most accounts can take several currencies but pay out in one. Check the currency setting in Gym Settings and, if in doubt, Stripe's Settings page for your account. |
| Card declined in Test mode | Real card numbers are always declined in Test mode. Use the test cards in step 5. |
| A refund made in the Stripe Dashboard does not show in DojoMesh | The webhook is missing, is in the wrong mode, or its signing secret was not saved. On the endpoint's page in Stripe, recent deliveries will show whether DojoMesh accepted them. You can also refund from DojoMesh's Manage Payments page instead, which needs no webhook. |
| Stripe shows the webhook as failing with a 400 or 503 error | 400 means the signing secret in DojoMesh does not match this endpoint. 503 means no secret has been saved yet. Reveal the secret on the endpoint's page, paste it into Gym Settings, and save. |
| Everything worked for months and suddenly every charge fails | Someone rolled the secret key in the Stripe Dashboard, which stops the old one instantly, or Stripe has paused the account and emailed you about it. Paste the current key into Gym Settings, and check your Stripe inbox. |
Keeping your secret key safe
- The secret key and webhook signing secret are stored with your academy's settings and used only on DojoMesh's servers when talking to Stripe. They are never sent to a member's browser and never shown on the member portal. The publishable key is sent to the browser, which is what it is for.
- Anyone who can open Gym Settings in your academy can see the Stripe fields. Only give admin access to people who should be able to see that page.
- If you think the secret key has leaked, roll it from the API keys page in Stripe and paste the new one into DojoMesh straight away. The old key stops working the moment you roll it, so do both steps together.
- Do not put either key in a screenshot, a support email, a shared document, or a group chat.
Common questions
Does DojoMesh take a cut of card payments?
No. Payments go straight from the member's card to your Stripe account. You pay Stripe's standard processing rate to Stripe, and your flat monthly DojoMesh subscription is the only thing you pay us.
Switching from Square
Cards saved through Square live in Square and cannot be moved to Stripe. When you change the Card Processing Gateway to Stripe, existing Square cards on file stop being usable, and any recurring plans that charge them will fail at their next billing date until the member has a Stripe card saved. The safe order is: set up Stripe and test it, then email every member with a card on file a card-update link using the Send Card Links button at the top of Cards on File, then switch the gateway once most cards are in. Ask us if you want a hand planning it.
What does "requires authentication" mean?
Some banks, especially outside North America, insist the cardholder approves a charge in their banking app before it goes through. Stripe calls this 3D Secure. A charge you run from the admin panel cannot do that, because the member is not there. When it happens, ask the member to make the payment themselves from the portal, or to re-save their card there, which gives the bank its chance to approve future charges. The test card ending in 3155 lets you see this in Test mode.
Do I have to set up the webhook?
No, but we recommend it. Without it, charging, saving cards, recurring billing and refunds made from inside DojoMesh all still work. What you lose is DojoMesh noticing refunds you make from the Stripe Dashboard, and a record of recurring charges that fail after Stripe first accepted them.
Can I use a restricted key instead of the secret key?
Yes. DojoMesh accepts keys beginning rk_. If you create one, give it write access to Customers, Payment Methods, Payment Intents and Refunds, and read access to Charges. If any of those are missing, the matching feature will fail with a permissions error. Most academies use the standard secret key.
I already have customers and cards in Stripe from another system. Can I reuse them?
Yes. On Cards on File there is an Import Existing Stripe Cards section, folded up behind a Show/Hide button, that links a member to a customer and card already in your Stripe account, so nobody has to re-enter card details. You will need the customer's ID from your Stripe Dashboard, which begins cus_.
Can I use Square and Stripe at the same time?
You can enter credentials for both, but only one can be the Card Processing Gateway, and that one handles all cards on file, recurring billing and online checkout. Cash, Interac e-Transfer and cheque are unaffected by this choice.
Do the keys expire?
No. They stay valid until you roll them in the Stripe Dashboard or close the account. You will not need to repeat this setup on a schedule.
Will members see any of this?
Members see a normal card entry form in the portal, styled to your academy. They never see your Stripe keys or the Stripe Dashboard. Members can also turn on automatic payments for themselves from the portal once they have a card saved.