Connect Stripe and request payments

Goal#

Take payment from clients through your practice's own Stripe account: connect it once, describe what you sell as Offers, send a client a payment request, and follow each Payment to Paid. Coaching Toolkit never holds the money or a Stripe key; your practice stays the merchant, with its own payouts and disputes.

Prerequisites#

• A Stripe account (or one you create while connecting).
• Admin of the practice to connect Stripe. Every Coach creates and changes their own Offers; an Admin can change any Coach's. Any Coach can request a payment from a client assigned to them.

1. Connect Stripe (Admin, in the app)#

Connecting is an OAuth hand-off a person completes in a browser:

1. In the app (web), open Settings, Payments, Client payments, Connect with Stripe.
2. Sign in to Stripe and approve the connection. Stripe sends you back to the Payments page in Settings, where the app finishes the connection as you and shows a message: connected, denied, or failed.

The Stripe link is valid for 15 minutes. Only the Admin who started the connection can finish it, once. The app reports one outcome: connected, already connected, invalid (an expired or used link, or one another Admin or practice started) or failed.

An Admin reads the state on the Payments page in Settings (every Coach sees whether payments are connected and their status):

Status	Meaning
Pending	Stripe still needs details from you; finish them in Stripe
Active	charges are enabled; payment requests work
Restricted	details are in but Stripe has paused charges; see your Stripe dashboard
Disconnected	not connected

After changing something in Stripe, use Refresh on the Payments page to read it again. Disconnect removes the connection: open payment requests are cancelled first.

2. Create Offers#

An Offer is what you sell: a name, an optional description, one price for the whole Offer (or none, for a free one), and one to ten items. An item is a kind of session with a length and a count: a single session is one item of one, a programme might be 1 × intake, 30 minutes, then 5 × session, 60 minutes. A booking of the Offer is for its first item's session; the items cannot be booked on their own. Each Offer is yours: it shows on your booking pages and landing pages, not on a colleague's. A priced Offer is mirrored as a Product and Price in the practice's Stripe account, and its payments go to the practice.

In Booking, Offers, add an Offer with:

Field	Meaning
Name	up to 120 characters
Description	optional, up to 2000 characters
Price	in the currency's smallest unit behind the scenes (12000 = 120.00 EUR); 50 or more; leave out price and currency for a free Offer
Currency	three letters, such as EUR or GBP
Items	one to ten, in order; each has a name (up to 120 characters), a kind (coaching, mentor coaching or supervision), a length of 5 to 600 minutes and a count of 1 to 500. A booking takes the first item's length and kind
How it is paid	Online (the default): through Stripe Checkout. By other means: the client pays you directly (bank transfer, cash, an invoice); no Stripe account needed
Payment instructions	optional, up to 2000 characters; for an Offer paid by other means, what the client reads on the booking confirmation, the manage page, the portal and the mails (bank details, "cash at the session")
Payment needed to join	whether the client must have paid before joining the call; off by default

An Offer paid by other means is never set up in Stripe, and it has no pay-only link. A booking of it leaves a Pending payment with your instructions; mark it as paid once the money is in (section 4). Switching an Offer from Online to other means stops it being payable in Stripe.

The Offers list shows your active Offers; an Admin sees the practice's, grouped by Coach. An Offer paid online shows its pay-only link once its Coach has a public profile; a free Offer or one paid by other means has none, and a landing page cannot use one as a pay-only link (link it to the booking page instead). You can change one (price and currency are changed together) or archive it; payments already made keep pointing at it.

How many active Offers each Coach can have depends on the practice's package: Free 1, Starter 3, Growth 5, Studio 10. Items do not count towards it. Archived Offers do not count; archive one to make room. After a move to a smaller package, your oldest Offers stay active and the newer ones past the limit are marked Inactive on your package: you can still edit or archive them, but they are not shown on any page, cannot be booked and cannot be paid for until the practice upgrades or you archive another Offer.

3. Request a payment from a client#

Open the client, Payments, Request payment. Pick one of your priced Offers, and optionally tie the payment to one of the client's sessions. The new payment is Pending, and you get:

• the Stripe Checkout link for the client;
• whether the request was mailed to the client. When the client has no email address it is not mailed; send the link yourself.

The link is payable for 24 hours (Stripe's limit). After that the payment stays Pending: the client's portal and the booking's manage page show a fresh link to pay. After paying, the client lands in their portal.

For an Offer paid by other means there is no Stripe link: the request mail carries your payment instructions, and the payment stays Pending until you mark it as paid. Request payment is there without a Stripe account as long as the practice has an active priced Offer paid by other means.

To withdraw an open request, cancel it on the client's Payments list. The link stops working at once; the client is not told.

4. Money received outside Stripe#

Open the client, Payments:

• Mark as paid on a Pending or Failed payment, or on a held card that could not be charged when you approved the booking: pick how the money came in (bank transfer, cash or other) and add a note if you like. A Stripe link the payment still had stops working first, and a card hold is released, so the client cannot pay twice. A payment that is Processing is Stripe's to settle and cannot be marked.
• Record a payment for money that never had a request: the amount, the currency, how it came in, optionally the session or the purchase it pays for, and a note. It is Paid at once. A payment for a purchase covers every session drawn from it.

A group's payments work the same way from the group's Sessions and payment (see Charge a group under Sessions): a payment from a billing contact has no client and belongs to the group's purchase.

Both keep who marked or recorded the payment and the note; the note is for your records and is never shown to the client. Recording needs a package with client payments (Growth or Studio).

What each status means#

Stripe tells Coaching Toolkit what happens through its Connect webhooks; you see the result as the payment's status:

Status	What happened
Pending	requested, not paid yet (for an Offer paid by other means: until you mark it as paid)
Processing	the client chose a slow method (such as a bank debit) and Stripe is still settling it; it becomes Paid or Failed (Cancelled if the Stripe account is disconnected meanwhile)
Paid	the client paid, through Stripe or as you marked or recorded it
Failed	the payment attempt failed; the client can try again
Cancelled	you withdrew it, the booking it was for was declined, withdrawn or cancelled, or the Stripe account was disconnected
Refunded	refunded in full in Stripe (a partial refund leaves it Paid)
Disputed	the client disputed the charge; answer it in your Stripe dashboard
DisputeLost	the dispute was decided against you
Authorised	a booking that waits for your approval: the card is held, not charged yet
Released	that hold was cancelled (you declined the booking or it expired); nothing was charged

A won dispute returns to Paid; an Authorised payment becomes Paid when you approve its booking. The client card raises an alert for a disputed payment, for a request still unpaid after seven days, and for a held card that could not be charged on approval.

A session's payment tag#

Each session shows where it stands on payment, from the newest payment that covers it: its own, or the payment for the purchase it counts toward. A withdrawn request or a released hold does not count.

Tag	Covering payment
Not required	none, or only cancelled and released ones; also a session from sessions you granted
Owed	Pending
Processing	Processing, or a card held for a booking waiting for your approval
Paid	Paid, or Disputed while the dispute is open
Failed	Failed or DisputeLost
Refunded	Refunded

Unpaid under Sessions lists the sessions that are Owed, Processing or Failed. The client sees the same tag in the portal and on the booking's manage page and confirmation.

Payment needed to join#

When an Offer has Payment needed to join on, the client cannot join the call of a session that is Owed, Processing or Failed: the portal and the manage page say the session must be paid first, and Join is refused until it is. The rule follows the session's Offer: the one it was booked for, or the Offer of the purchase it counts toward, so a session from a paid-for purchase is let in. A session with no payment request, a Paid one and a Refunded one are let in. You are never held back.

To let a client in anyway, open the session and choose Allow joining unpaid. It applies to that session only and you can take it back (Require payment to join); both are kept in the client's history. Taking it back does not end a call the client is already in; their next join is refused while the session is unpaid.

Mails to you about payments#

The client's coach gets a mail with a button to the client's payments:

• Payment received: a payment became Paid. No mail when you marked it as paid or recorded it yourself, and none when a won dispute returns it to Paid.
• Payment failed: a payment failed, a card held for a booking could not be charged when you approved it, a charge was disputed, or a dispute was lost. Failed, uncharged and disputed payments also show under Payment problems on Today, on every plan.

Both are on by default. Switch either off in Settings, Account, under Mails to you.

Verify it worked#

Open the client, Payments. The request is listed as Pending with its Offer and amount. Once the client pays it reads Paid. While the request is open the list shows its Stripe link and when it expires; once paid it shows the payment date.

Failure cases#

What you see	Why
Not allowed	not an Admin (connecting), not the Offer's Coach or an Admin (changing an Offer), or not the client's Coach or an Admin (requests)
Offer limit reached	you have as many active Offers as the package allows; archive one or upgrade
Offer inactive	the Offer is past your package's limit; it cannot be requested
Not found	an unknown or archived Offer, or a session that is not this client's
Already connected	the practice is connected already
Payments not connected	no connected account, or it cannot take charges yet
Offer has no price	the Offer is free; pick a priced one
Client has ended	the client is Ended
Payment no longer open	cancelling or marking as paid a payment that is no longer Pending or Failed
Payment method not allowed	Stripe named as the method of money received outside Stripe
Not on your package	recording a payment without client payments in the package
Stripe rejected the request	Stripe refused it; nothing was saved
Stripe unavailable	Stripe did not answer; try again
Payments not set up	payments are not set up on this deployment