> ## Documentation Index
> Fetch the complete documentation index at: https://docs.florists.digital/llms.txt
> Use this file to discover all available pages before exploring further.
# Stripe
> Connect Stripe to take card payments by payment link or hosted card entry, with refunds handled from the order screen.
**Stripe** lets staff send a customer a payment link or take a card over the phone through a Stripe-hosted form, and refunds run from the order screen without opening Stripe.
**This page covers features gated by Admin-tier permissions** — typically Settings access. Admins have these by default; your administrator can adjust who has them in [Settings > Team](/settings/team).
This page is the full setup tutorial. For how Stripe compares to Dojo and Paymentsense, see [Payment integrations](/settings/integrations/payments).
## What it does
Stripe gives you two ways to take a card, both hosted by Stripe, so your shop never holds card details.
* **Payment Link.** Generate a one-shot link tied to a specific order and send it to the customer. The link can only be paid once; once it's been used, it expires automatically. You can cancel an outstanding link from the order if you sent it in error.
* **Hosted card entry.** Open a Stripe-hosted card form inside your dashboard while you're on the phone to the customer. The form runs in the browser and posts the result back to the order.
At least one of these flows must be enabled when you connect Stripe. You can have both on at the same time.
Refunds work both ways. A refund started from the order screen calls Stripe directly and updates the order's ledger. Refunds you start in the Stripe dashboard, asynchronous refunds that settle later, and funds movements from a disputed charge are all reconciled back into the order so the totals line up either way.
**Stripe hosted card entry is a MOTO payment.** Because staff key in card details the customer reads out, Stripe processes it as a mail order / telephone order (MOTO) transaction — card-not-present, out of scope for online authentication, with the fees and chargeback rules that go with that. Stripe gates MOTO behind an account-level switch that only Stripe support can turn on, so hosted card entry won't work until that's done: see [MOTO and hosted card entry](#moto-and-hosted-card-entry). Stripe Terminal hardware isn't part of this integration, and Stripe at the till isn't supported today.
## Before you start
* You need a **Stripe account** with payments activated. Sign up at [stripe.com](https://stripe.com) if you don't have one — activation involves verifying your business details with Stripe and can take a day or two.
* If you're turning on **hosted card entry**, ask Stripe support to enable **MOTO payments** on your account first — see [MOTO and hosted card entry](#moto-and-hosted-card-entry). Payment links don't need this.
* Keep two browser tabs open: **Digital Florists** (Settings > Integrations > Stripe) and the **Stripe Dashboard**. You'll be copying values between them.
## Setting it up
In the Stripe Dashboard, make sure the mode toggle in the top corner is set to **Live**, then go to **Developers** > **API keys**.
Copy two keys:
* The **Publishable key** (starts `pk_live_`). It's visible without any extra clicks.
* A **Secret key** (starts `sk_live_`), revealed with the **Reveal** button. Or use a restricted key (`rk_live_`) instead — the safer option, see [Using a restricted key](#using-a-restricted-key).
Stripe only shows a revealed live secret key once, so paste it straight into Digital Florists rather than parking it somewhere.
In **Settings** > **Integrations**, open the **Stripe** integration and fill in the fields below. You don't pick Test or Live here — Digital Florists works that out from the keys you paste.
| Field | What goes in it |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Enable payment links** | Tick to let staff send Stripe payment links from an order. On by default. |
| **Enable hosted card entry** | Tick to let staff open the Stripe-hosted card form on an order. Off by default. Needs [MOTO enabled on your Stripe account](#moto-and-hosted-card-entry) before it will take a payment. |
| **Publishable key** | The `pk_` key from step 1. |
| **Secret or Restricted key** | The `sk_` or `rk_` key from step 1. |
| **Webhook secret** | Leave this **blank** — Digital Florists creates the webhook for you when you save (step 3). Only fill it in if you're setting the webhook up by hand. |
At least one of the two flow toggles has to be on, and all your keys have to be the same mode — Digital Florists reads Test or Live from the key prefixes, so it won't accept a mix of `pk_test_` and `_live_` keys.
Save the integration. Digital Florists creates a webhook in your Stripe account, subscribes it to the [events below](#webhook-events), and stores its signing secret — automatically, with nothing to copy across. Two Stripe payment methods then appear for staff on the order screen: one for the payment link, one for the hosted card form.
Take a small real payment end to end (a pound or two on your own card) and check it lands on the order and shows as paid. Then refund it from the order screen to confirm the whole loop works. Test **each flow you've enabled** — a working payment link doesn't prove hosted card entry will work, because hosted card entry also needs [MOTO enabled on your Stripe account](#moto-and-hosted-card-entry).
**If the webhook can't be created automatically** — because the restricted key doesn't have **Webhook Endpoints** write access, or your shop doesn't have a web address set up yet — Digital Florists tells you so you can create it by hand. In the Stripe Dashboard, open **Workbench** > **Webhooks** > **Create an event destination**, listen to events on **your account**, select the [events below](#webhook-events), and set the destination to the **webhook URL** shown on your Stripe configuration screen in Digital Florists. Then reveal the endpoint's signing secret (starts `whsec_`) and paste it into the **Webhook secret** field. Stripe shows the signing secret only once, and each mode (Test/Live) has its own.
**Want to trial it without real money first?** Set everything up with your Stripe **test** keys (`pk_test_` and `sk_test_` or `rk_test_`) instead — Digital Florists detects test mode automatically, and you can pay with Stripe's test card `4242 4242 4242 4242` (any future expiry, any CVC). When you're happy, swap in your live keys and save again.
## Using a restricted key
A restricted key (starts `rk_test_` or `rk_live_`) is a Stripe key scoped to only the permissions it needs, so it's the safer choice for the **Secret or Restricted key** field. If the key ever leaked, it couldn't be used to touch the rest of your Stripe account.
Create one in the Stripe Dashboard under **Developers** > **API keys** > **Create restricted key**, and grant these permissions (on the restricted-key screen, **Write** automatically includes **Read** for the same resource):
* **Payment Intents** — **Write**, for taking a card over the phone.
* **Payment Links** — **Write**, for creating and cancelling payment links.
* **Charges and Refunds** — **Write**, for issuing refunds from the order screen and reading them back so they reconcile onto the right order. Stripe treats charges and refunds as one resource, so this covers both.
* **Webhook Endpoints** — **Write**, so Digital Florists can create and maintain your webhook automatically when you save. If you'd rather not grant this, leave it off — you'll be prompted to create the webhook by hand and paste its signing secret instead (see the note in step 3 above).
If the restricted-key screen feels like too much, a standard secret key works exactly the same — restricted is recommended, not required.
## Webhook events
Digital Florists subscribes your webhook to these events automatically. They're listed here so you can check the endpoint in Stripe, or select them yourself if you're creating the webhook by hand. They're how Stripe tells Digital Florists a payment landed, failed, or was refunded or disputed:
| Group | Events |
| ------------ | ---------------------------------------------------------------------------------------------------------------------- |
| **Payments** | `payment_intent.succeeded`, `payment_intent.payment_failed`, `payment_intent.canceled` |
| **Checkout** | `checkout.session.completed`, `checkout.session.async_payment_succeeded`, `checkout.session.async_payment_failed` |
| **Refunds** | `refund.created`, `refund.updated`, `refund.failed`, `charge.refunded`, `charge.refund.updated` |
| **Disputes** | `charge.dispute.created`, `charge.dispute.closed`, `charge.dispute.funds_withdrawn`, `charge.dispute.funds_reinstated` |
Missing events are the most common cause of a payment that went through on Stripe but never updated the order. If in doubt, re-open the endpoint in Stripe's Webhooks tab and check all of the above are selected.
## Disputes and chargebacks
When a customer disputes a Stripe charge, the order is flagged for review and the payment moves into a **Disputed** state. Stripe holds the funds while the dispute is open, and that movement is recorded against the order's ledger.
If the dispute is resolved in your favour, the funds are reinstated. If it's lost, the withdrawal stays recorded against the order as a refund so the order and Stripe agree.
These updates arrive through the four `charge.dispute.*` events listed under [Webhook events](#webhook-events), so the order only stays in step with Stripe while that subscription is in place.
## Currency notes
Stripe handles most currencies, with a couple of edges worth knowing about.
* **Zero-decimal currencies** (Japanese yen, Korean won, and similar) are charged as whole units.
* **Three-decimal currencies** (Bahraini dinar, Kuwaiti dinar, and similar) aren't supported. The integration rejects them rather than risk charging the wrong amount.
* The minimum charge Digital Florists will send to Stripe is **£0.10** (or the equivalent). Stripe itself enforces a higher minimum on most currencies, typically around £0.30 in GBP.
## PCI compliance and MOTO
### Your PCI position with this integration
Both Stripe flows (the payment link page and the hosted card form) are hosted by Stripe, so card numbers never pass through your shop's systems. That keeps you in the simplest PCI compliance band, with Stripe doing the heavy lifting.
Confirm your status once a year in the Stripe Dashboard under **Settings** > **Compliance and documents** > **My PCI compliance** — [dashboard.stripe.com/settings/compliance/documents](https://dashboard.stripe.com/settings/compliance/documents). Stripe shows there whether it needs anything from you, and the **Stripe documents** tab on the same screen holds Stripe's own PCI Attestation of Compliance and responsibility matrix if your acquirer or insurer ever asks for them.
### MOTO and hosted card entry
MOTO (mail order / telephone order) is the card-scheme category for payments where you key in a card the customer reads out, and it's exactly what hosted card entry does. Stripe keeps MOTO switched **off** by default until you ask support to enable it, because MOTO payments skip the online authentication step (3-D Secure) that normally protects card-not-present charges.
Until Stripe enables it, hosted card entry fails at the "Prepare card payment" step with:
> Telephone payments (MOTO) are not enabled on your Stripe account. Ask Stripe support to enable mail order and telephone order payments, then try again.
Payment links are unaffected — they authenticate the customer directly, so they work with or without MOTO.
When you contact Stripe support, be precise about what you're asking for, because Stripe has more than one thing called MOTO:
* Ask for **MOTO to be enabled for card payments taken through the Payment Intents API** (sometimes described as MOTO for the API or for Stripe Elements).
* **MOTO for Stripe Terminal** (keying a card into a Stripe card reader) is a **separate enablement** and does not switch on API MOTO. If Stripe says "MOTO is already enabled" but hosted card entry still shows the message above, this mismatch is the usual reason.
* Enablement is **per Stripe account**. If your business has more than one Stripe account, it must be enabled on the account whose API keys are pasted into Digital Florists — check the account name shown in the top-left of the Stripe Dashboard matches the account you set up here. The failed attempts are visible in that account's **Workbench** > **Logs**, which is a quick way to confirm you're looking at the right one.
Stripe may ask for compliance documentation as part of the request — typically a **Self-Assessment Questionnaire (SAQ)** for your shop, or an **Attestation of Compliance (AoC)** covering your shop or your software vendor, uploaded under [Settings > Compliance and documents](https://dashboard.stripe.com/settings/compliance/documents). Digital Florists is the software vendor in Stripe's questions, so [get in touch with us](/get-started/getting-help) when you start the request and we'll work through it with you rather than leave you translating it alone.
## Caveats worth knowing
* **The Stripe API version is pinned.** Upgrading the API version in your Stripe dashboard won't change how Digital Florists talks to Stripe; the integration tracks a fixed version that's updated through our releases.
* **Failed refunds are flagged for review.** If Stripe rejects a refund after the fact (rare), the order is flagged on the dashboard with a note to action so you can decide what to do next.
## Common questions
Stripe is rejecting the payment because MOTO isn't switched on for the account your API keys belong to. Working payment links don't rule this out — links prove the keys are valid, not that MOTO is enabled. Two things to check with Stripe support:
1. **The right kind of MOTO.** Ask for MOTO on **card payments through the API** (Payment Intents). MOTO for Stripe Terminal card readers is a separate switch and doesn't help here.
2. **The right account.** Enablement is per Stripe account. Confirm the account name in the top-left of the Stripe Dashboard matches the account whose keys you pasted into Digital Florists — the rejected attempts appear in that account's **Workbench** > **Logs** if you're looking at the right one.
Once Stripe confirms it's enabled, try the payment again — nothing needs changing in Digital Florists. See [MOTO and hosted card entry](#moto-and-hosted-card-entry) for the full picture.
Almost always a webhook problem. Check three things: the webhook URL in Stripe matches the one shown on your Stripe configuration screen in Digital Florists, the [events above](#webhook-events) are all selected on the endpoint, and the **Webhook secret** field holds the signing secret for the endpoint in the **same mode** (Test and Live secrets are different). Stripe's Webhooks tab shows each delivery attempt and the response it got, which usually points straight at the issue.
All your keys have to be the same mode — test keys (`pk_test_` with `sk_test_` or `rk_test_`) or live keys (the `_live_` versions). Digital Florists detects which from the keys, but it won't accept a mix of test and live. Mixing one of each is the usual culprit.
It reconciles. The refund webhook brings the change back into Digital Florists and the order's ledger updates to match. Refunding from the order screen is still the tidier habit, because it records who issued the refund and why.
Not today. Stripe in Digital Florists covers payment links and the hosted card form for phone and online orders. For in-person card payments at the counter, use your existing card terminal and record the payment against the order, or see [Payment integrations](/settings/integrations/payments) to compare the processors that support an in-person terminal.
## What's next?
How Stripe compares with Dojo and Paymentsense, and what each one needs.
Issuing refunds from the order screen, and how they route back to the card.
Tracing a Stripe payment back to its order during reconciliation.
How the Stripe payment methods appear to staff on the order screen.