Set Up Stripe Payments

Taking cards in WooCommerce often means one plugin for Stripe, another for Apple Pay buttons and a third for subscriptions, each with its own settings screen and webhook. When a renewal fails, you’re left checking three logs to find out why.

The Stripe module is a Stripe gateway built into Stackless. It runs the Stripe Payment Element on the block and classic checkout, saves cards, shows Apple Pay, Google Pay and Link buttons, refunds from the order screen, and charges subscription renewals off-session.

Turn On the Gateway

Setup lives in two places:

1. Switch on the Stripe module under Stackless → Dashboard.
2. Add your keys under Stackless → Settings → Stripe.
3. Tick Enable Stripe under WooCommerce → Settings → Payments → Stripe (Stackless).

The WooCommerce payments screen only holds the on/off switch, with an Open Stripe settings button that takes you to the rest.

Add Your API Keys

Copy keys from Stripe → Developers → API keys. The Stripe account section has:

• Test mode, on by default. Only Stripe test cards work.
• Test publishable key and Test secret key
• Test webhook signing secret
• Live publishable key, Live secret key and Live webhook signing secret

Secret keys can be standard (sk_) or restricted (rk_) keys. When you save, Stackless checks the keys with Stripe and shows the result. A wrong prefix, a missing half of a key pair or a key Stripe rejects shows an error. Live keys on an account that can’t take charges yet show a warning.

Stripe stays hidden at checkout until the selected mode has both keys.

Connect the Webhook

The webhook URL is https://yoursite.com/wp-json/stackless/v1/stripe/webhook, and the settings screen shows your exact URL. In Stripe → Developers → Webhooks, add an endpoint with this URL once for test mode and once for live mode. Subscribe to these events:

payment_intent.succeeded
payment_intent.payment_failed
payment_intent.processing
payment_intent.canceled
charge.refunded
charge.dispute.created
setup_intent.succeeded
setup_intent.setup_failed
payment_method.detached
payment_method.updated
payment_method.automatically_updated

Paste each endpoint’s signing secret into the matching field. Without it, bank debits, refunds made in the Stripe Dashboard, disputes and removed cards won’t sync.

The Status panel below the settings shows whether the gateway is enabled, the verified test and live accounts, the webhook URL, the last signed webhook and the most recent events with their results.

Checkout Settings

• Title: default “Card and more”.
• Description: shown under the title.
• Capture: Charge immediately, or Authorize only and capture when the order moves to Processing or Completed. Orders with subscriptions always charge immediately. Authorizations expire after 7 days, and cancelling the order releases them.
• Saved payment methods: lets signed-in customers save and reuse methods. Subscription orders always save the method.
• Statement descriptor suffix: up to 22 characters added after your account’s descriptor on card statements.
• Payment form style: Match my theme, Stripe default, Flat or Night (dark).

Saved test cards and saved live cards are kept apart, so a test card never shows on a live checkout. When a customer deletes a saved method in My Account, it’s detached in Stripe too.

Express Checkout Buttons

The Express checkout section controls Apple Pay, Google Pay and Link buttons:

• Show buttons on: Product pages, Cart and Checkout, all on by default.
• Button label: Logo only, Buy with, Checkout with, Order with or Pay with.

Apple Pay also needs your domain added in Stripe → Settings → Payment method domains. On a product page, the wallet buys only that product: the shopper’s cart is set aside and restored afterward. Express buttons only show when the shopper can finish without filling a form. When checkout requires an account, guests see them only if WooCommerce can create the account on its own (account creation at checkout on, with automatic username and password).

Refunds and Disputes

Refund from the WooCommerce order screen as usual, in full or in part. An order that was only authorized can be released in full, but needs capturing before a partial refund. Refunds made in the Stripe Dashboard are recorded on the order through the webhook. A dispute adds a note with the reason, and puts a Processing or Completed order on hold.

Subscription Renewals

Stripe renews subscriptions automatically. It supports several subscriptions in one order, free-trial signups with nothing due today, payment method changes from My Account and next-payment date changes.

On the renewal date, the saved method is charged off-session:

• If Stripe can’t be reached, the charge is retried up to 3 more times, 15, 30 and 45 minutes apart, with the same idempotency key so the customer is never charged twice.
• If the bank asks for 3D Secure, the order gets a note with a link where the customer can confirm and pay, and the failure goes through your retry schedule.
• Bank debits that are still processing stay pending until Stripe confirms them.

Renewals, Failed Payments and Retries covers what happens after a failure.

Good to Know

• Turn on Debug log under Advanced to write API calls and webhook results to WooCommerce → Status → Logs (stackless-stripe_gateway). Keys and card data are never logged.
• The official Stripe plugin can run alongside this one. They use different gateway IDs, saved cards and webhooks.
• Stripe hides itself for currencies it doesn’t support and for totals below Stripe’s minimum charge.