They fill in their addresses, choose delivery and, if you offer more than one payment method, choose Stripe (you can rename it, see Troubleshooting).

When they confirm the order, they are taken to a payment page hosted by Stripe. It lists their items, delivery, tax and total, and offers the ways to pay that you have turned on in Stripe. If their bank asks for extra security checks (3D Secure), Stripe shows them on this page.

After paying, they return to your order confirmation page and the order is recorded with its payment. Stripe also sends updates to your storefront through a webhook, which keeps the order's payment status up to date: for example payments that are confirmed later, and refunds made in Stripe.

Depending on your capture mode, the payment is taken straight away or authorised now and taken later. You can capture, void and refund from the order in Sales > Orders.

Go to dashboard.stripe.com/register and create an account. Use an email address that the person who looks after your company's finances can access: Stripe sends payment notifications and account messages there.

In the Stripe Dashboard, open the API keys page (dashboard.stripe.com/apikeys). A toggle on the page switches between sandbox mode and live mode, and each mode has its own keys.

Each mode has a publishable key and a secret key. Sandbox keys start pk_test_ and sk_test_; live keys start pk_live_ and sk_live_. Keep the secret key private: never send it by email or in a support ticket.

Copy the key with the copy button or by revealing it. Stripe only lets you reveal some live secret keys, so if all you can see is a shortened (masked) key, create a new one rather than copying the masked text.

To take real payments, complete Stripe's account activation (business details, bank account and identity checks). Live keys only take payments once Stripe has activated your account.

In your admin area, go to Configuration > Payment Methods. Stripe is in the list (system name Payments.Stripe). The ticks show what it supports: capture, refund, partial refund and void.

Click Configure on the Stripe row. The blue panel at the top repeats the setup steps and shows your storefront's own webhook address.

Paste your sandbox keys into Test public api key and Test secret api key, and tick Enable Test Mode. With test mode on, your storefront uses the test keys.

Your live keys go in Production public api key and Production secret api key. They are used when Enable Test Mode is not ticked.

Click Save at the bottom of the page.

Back in Configuration > Payment Methods, click Edit on the Stripe row, tick Is active and click Update. Stripe now shows at checkout, as long as the keys for the current mode are filled in.

On the Stripe settings page, the blue panel shows your webhook address. It ends in Stripe/Webhook.

In the Stripe Dashboard, open Workbench > Webhooks and click Add destination.

When Stripe asks where the events come from, choose Your account. Don't choose Connected accounts: that is for Stripe Connect platforms.

Under Payload style, choose Snapshot, not Thin: your storefront reads Snapshot events. Leave the API version on the version Stripe suggests.

Select these events: payment_intent.succeeded, payment_intent.payment_failed, payment_intent.canceled, charge.refunded, and the two checkout.session events for async payments: async payment succeeded and async payment failed.

Click Continue, choose Webhook endpoint and click Continue again.

Give the destination a name you will recognise, paste your webhook address into Endpoint URL and click Create destination.

The new destination opens with an Active badge. Under Signing secret, reveal the secret (it starts whsec_) and copy it. With a signing secret, your storefront checks that each event really came from Stripe.

Paste the secret into Webhook signing secret on your Stripe settings page and click Save.

Sandbox and live mode have separate webhooks and separate signing secrets, but your Stripe settings page has one Webhook signing secret field. When you go live, add the same destination in live mode and replace the sandbox secret with the live one.

Capture Mode is the first setting on the Stripe settings page. There are four options.

Stripe authorises the payment, the order is created when your shopper returns, and the payment is captured straight away, even if the order still needs approval. The order is marked Paid.

Stripe authorises the payment and the order is created with payment status Authorised. Your shopper sees Payment was authorized instead of the usual confirmation, and the payment shows as Uncaptured in Stripe. You take the money later with Capture on the order.

Until you capture, the payment shows Uncaptured: authorised, but not yet captured.

As Manually, but the payment is captured when the order is marked as shipped.

The order is created first, then your shopper pays and the money is taken in one step. If your shopper leaves the Stripe page without paying, they see Your order has been placed but needs payment: the order stays on your storefront unpaid, and they can pay for it later from the order in My Account with Complete payment.

Bacs Direct Debit, SEPA Direct Debit and other bank payment methods (such as iDEAL, Bancontact or Pay by Bank) can't be authorised first and captured later, so Stripe does not offer them with the other three modes. If you want them, choose Default.

On your storefront, add a product with a price to the basket and check out with Stripe. By default, a basket worth nothing (for example after a 100% discount) skips the payment step.

On the Stripe page, use 4242 4242 4242 4242 with any future expiry date (for example 12/34) and any three-digit security code.

4000 0000 0000 0002 is always declined: Stripe shows the error on its page and your shopper can try another card. With On Order Placement, Manually or On Shipped, no order is created for a declined attempt. 4000 0000 0000 3220 asks for a 3D Secure check: Stripe shows a test page where you can complete or fail it.

Click Complete on the test page to approve it. In live mode your shopper verifies with their bank instead, for example in their banking app.

In Sales > Orders, open the order. Its payment status and the order notes show what Stripe reported.

In the Stripe Dashboard (still in sandbox mode), open Payments to see the test payment. Test payments only show while the Dashboard is in sandbox mode.

Open the payment in Stripe to see each step, for example a declined card, the 3D Secure check, the authorisation and the capture.

In Stripe, open your webhook destination and look at its deliveries. Each event should show as delivered.

In Stripe, switch the API keys page to live mode and copy the live publishable and secret keys (pk_live_, sk_live_).

On the Stripe settings page, paste them into Production public api key and Production secret api key. Check that neither contains test.

In Stripe live mode, add the same webhook destination and events as in the sandbox, and paste the live signing secret into Webhook signing secret, replacing the sandbox one.

In the Stripe Dashboard in live mode, check that the payment methods you want are turned on.

Untick Enable Test Mode and click Save.

Place a low-value order with a real card, check it in Sales > Orders and in Stripe, then refund it from the order.

Your shopper sees their items (with each product's short description, unless you turn that off), any checkout attributes, a tax line, delivery and the total, and the ways to pay you have turned on in Stripe. Wallets such as Apple Pay and Google Pay only appear on devices that support them.

The page uses the email address from your shopper's account. A shopper with no valid email address on their account doesn't see Stripe at checkout.

With Use Stripe successful payments ticked (the default), Stripe emails its own receipt to the shopper's billing email address (Stripe doesn't send these for sandbox payments). Your storefront's own order emails are sent as usual.

With Default capture mode, the order is already placed and stays unpaid. Your shopper can pay later from the order in My Account with Complete payment. With the other capture modes, no order is created until Stripe authorises the payment, and the shopper goes back to their basket.

Go to Sales > Orders and open the order. The payment status shows whether it is Authorised, Paid, Refunded, Partially refunded or Voided.

On an order with payment status Authorised, click Capture to take the full authorised amount. The order becomes Paid, the Order paid emails are sent, and Stripe shows the payment as captured. Capture always takes the full amount.

The order notes show the Stripe capture, and in Stripe the payment moves from Uncaptured to Succeeded.

Click Void to cancel an authorised payment you don't want to take; Stripe releases the hold on the shopper's card. Void (Offline) only marks the order as voided and sends nothing to Stripe.

Click Refund to refund the full amount, or Partial refund and enter an amount. The refund is sent to Stripe, which returns the money to your shopper's card, and the order is marked Refunded (or Partially refunded). Refund (Offline) and Partial refund (Offline) only mark the order as refunded: they send nothing to Stripe, so use them only for money you have already returned another way.

In the Stripe Dashboard the payment shows Refunded. Stripe notes that it may take a few days for the money to reach your shopper's bank account.

If you refund a payment in the Stripe Dashboard instead, the order is updated to Refunded or Partially refunded, through the charge.refunded webhook.

Each action adds an order note with what Stripe returned, which is the first place to look if something didn't work.

Every payment carries four metadata values: customer-id, transaction-id, storefront-id and storefront-name.

On the Stripe settings page, click Expand custom metadata, then Add metadata row. Enter a Stripe Metadata Key (for example order_id) and a Stripe Metadata Value.

Values can use placeholders, written between percent signs, such as %OrderId% or %CustomerName%, and you can mix them with your own text. The panel links to the full list of placeholders.

With every capture mode except Default, the order doesn't exist yet when your shopper starts paying. Tick Update metadata with order details (on storefronts that already took orders before this option arrived, it starts unticked) so the order values are added to the payment in Stripe as soon as the order is created, including the charge that Stripe's payout and reconciliation reports read.

Up to 50 metadata entries, keys up to 40 characters and values up to 500 characters. Longer values are cut short.

Click Save, place a test order and open the payment in the Stripe Dashboard to check the metadata.

On by default: each item on the Stripe page shows the product's short description. Untick it to show only the product name (Stripe shows text only, so formatting in a description shows as plain text).

Tick it to leave out checkout attributes and delivery that cost nothing.

Optional text that Stripe adds after the statement descriptor prefix set in your Stripe account, so your shoppers recognise the payment on their card statement. Card payments only, up to 13 characters, at least one letter, and not < > \ ' " *.

Ticked: Stripe sends its own receipt email. Unticked: your storefront doesn't ask Stripe to send one, and the receipt settings in your Stripe Dashboard decide.

The tax line on the Stripe page is labelled VAT by default. To change it (for example to Tax), go to Configuration > Languages, open the string resources for each language you use, find the resource whose name starts with Plugins.Stripe and whose value is VAT, and change the value. The delivery line has its own wording, a resource whose value is {0} (incl. {1} VAT): change the word VAT there too. Then clear the cache.

In Configuration > Payment Methods, click Usage rules on the Stripe row (see Usage Rules on Payment and Delivery). With no rules, Stripe is available to everyone.

Choose a Requirement type, for example by customer roles, departments, shipping country, checkout attributes or what is in the basket. By default, Stripe is only offered when every rule is met (the order setting Allow single usage rule match for payment method changes this so that one rule is enough).

For a customer-role rule, enter the customer role system names separated by commas. The customer must have all of the listed roles. Tick Restricts usage to do the opposite: hide Stripe from those customers.

If Stripe is a customer's only payment method and your checkout skips the payment method choice, they go straight to Stripe after confirming the order.