Two rules
- Never show a shopper a method that will fail. Every method carries the currencies and countries Stripe accepts it in. At checkout a method is offered only when the store currency and the customer's billing country fit. A method offered outside its limits does not fail politely — it fails at the last step, after everything has been typed.
- Never charge twice. Every write to Stripe carries an idempotency key, and a retry reuses it. A payment intent already attached to an order is reused rather than replaced. A settled intent is never changed. And every webhook event is claimed by its id before it is applied.
One method, one gateway
Each of the 37 methods is one row in a catalog. The plugin builds one WooCommerce payment gateway per row, with the id gmstripe_{method} (for example gmstripe_card, gmstripe_ideal). They all share the keys, capture mode and saving setting from WooCommerce → Stripe.
A card payment
- On the checkout the card form is Stripe's Payment Element, served from
js.stripe.cominside Stripe's own iframe. Card details never reach your server. - When the shopper places the order, Stripe.js turns the card into a payment-method id, and only that id is posted.
- The plugin creates a Payment Intent for the order — or reuses the one already on it, if nothing that matters has changed — and confirms it.
- Stripe answers with a status, and the order follows:
| Stripe status | Order |
|---|---|
succeeded |
Paid (WooCommerce's normal status, usually Processing, or the one chosen in Order status after payment) |
requires_capture |
On hold — authorised, awaiting capture |
processing |
On hold — Stripe is still processing this payment. It will complete automatically. |
requires_action |
Pending payment — the shopper must authenticate or finish elsewhere |
| failed | The checkout shows That payment was not completed. Please try again. |
3-D Secure
When the bank asks for authentication, the challenge opens in the page. The client secret Stripe needs for that is never put into the address bar: the page asks for it over a nonce-checked request (wc-ajax=gmstripe_intent_secret), so it is not kept in browser history or leaked to another site. When the shopper finishes, the page reports back (gmstripe_complete_payment) and the order is updated.
While an intent is waiting for a challenge, Stripe refuses changes to its capture method and statement descriptor, so the plugin leaves those two out of any update rather than having the whole update fail.
Redirect methods
iDEAL, Bancontact, Klarna, TWINT and the other redirect methods send the shopper to their bank or provider and back. On return the plugin reads the intent and updates the order. If the shopper never comes back, the payment_intent.succeeded (or …payment_failed) webhook settles it — which is why the webhook matters.
Vouchers
OXXO, Boleto, Konbini and Multibanco give the shopper a voucher to pay at a shop or ATM. The order goes On hold — Waiting for the shopper to pay the voucher Stripe issued — and the reference, the link to the hosted voucher and the expiry are stored on the order. They are shown twice: on the order-received page (Finish paying for this order) and in the order email, which the shopper will still have next week. When they pay, the webhook completes the order.
Bank debits
SEPA, BECS and ACH carry a mandate. SEPA and BECS mandates carry a short reference built from the order. ACH uses instant bank verification through Stripe Financial Connections, so the shopper signs into their bank inside the checkout instead of waiting for test deposits. Debits take days to settle; the order stays On hold until the webhook confirms them.
Express checkout: Apple Pay and Google Pay
On classic product pages, the classic cart and the top of the classic checkout, the buttons are Stripe's Express Checkout Element:
- On a product page, the button carries that product, so pressing it buys what is on the screen.
- The amount charged is always calculated on the server from the cart. The wallet sheet may show a placeholder total, and nothing the browser sends can set a price.
- As the shopper changes address or shipping in the sheet, the plugin quotes shipping (
gmstripe_express_address,gmstripe_express_rate). - When they authorise, the order is built from the cart with the addresses from the wallet, and paid (
gmstripe_express_checkout). WooCommerce's order attribution is stamped on it as for a normal checkout. - Required checkout fields the wallet cannot fill are checked first, exactly as WooCommerce's own checkout does: shipping fields count only when the cart needs shipping, so a cart of virtual or downloadable products is never refused over a shipping field.
On the Cart and Checkout blocks, the buttons are registered in the blocks' own express area. In version 1.0.0, after the shopper confirms in the wallet sheet there, the button takes them to the checkout page rather than completing the order itself.
The [gmstripe_express_buttons] shortcode places the buttons on any page.
Saved methods
When Let shoppers save payment methods is on, a signed-in shopper can save a reusable method at checkout, or add one in My Account → Payment methods. Adding one there goes through a Stripe Setup Intent, so the card is authenticated and the mandate recorded — a card saved without that is declined the first time it is charged off-session.
Each shopper gets a Stripe Customer per mode; the ids are on their WordPress user profile under Stripe, where an administrator can change them. If Stripe cannot be reached while saved methods are being synced, nothing is deleted — an unreachable Stripe is "no answer", not "no cards".
Subscriptions and pre-orders
With WooCommerce Subscriptions active, every method that can be reused declares subscription support. Renewals are charged off-session against the saved method, with nobody at the keyboard; if the bank insists on authentication anyway, the renewal is left for the shopper to pay. WooCommerce Pre-Orders are charged the same way when the product is released.
Capture and void
With Authorise now, capture later, the order's Order actions menu offers Capture the Stripe authorisation and Void the Stripe authorisation. Capturing notes Captured the Stripe authorisation.; voiding cancels the order.
Refunds
WooCommerce's Refund button refunds through Stripe, in full or in part, and notes Refunded … through Stripe (refund re_…). A refund made in the Stripe Dashboard reaches the order through the charge.refunded webhook as an order note — Stripe reports … refunded against this order. Record it in WooCommerce if it was not refunded from here. No WooCommerce refund is created for it automatically, because one created at the same moment as an admin's own would be recorded — and restocked — twice.
Test and live orders
The mode a payment was taken in is stored on the order (_gmstripe_mode). Every later operation — refund, capture, void — uses that mode's keys, so a test order refunded after you go live still goes to your test account.
Webhooks
Stripe posts events to /wp-json/gatemi-stripe/v1/webhook. For each one:
- If no signing secret is set for the current mode, it is refused (401).
- The
Stripe-Signatureheader is verified against the signing secret, with a five-minute tolerance. A bad signature is refused (401). - The event id is claimed (an option
gmstripe_seen_{id}). The claim is oneINSERT IGNOREon the options table's unique key, so when Stripe delivers the same event twice at the same moment only one delivery wins. A copy that was already claimed is answered Already processed. and not applied again. Claims are swept daily (gmstripe_purge_webhook_claims) after three days, longer than Stripe's retry schedule. - An event for the other mode (a test event on a live store) is ignored.
- The event is applied:
| Event | What happens |
|---|---|
payment_intent.succeeded |
An unpaid order is marked paid |
payment_intent.payment_failed |
An unpaid order is marked failed, with Stripe's reason |
payment_intent.canceled |
An unpaid order is cancelled |
payment_intent.requires_action |
A voucher issued to a shopper whose browser never came back is stored |
charge.pending |
An unpaid order goes On hold — accepted, waiting to clear |
charge.refunded |
An order note with the total refunded at Stripe |
charge.dispute.created |
The order goes On hold; its previous status is remembered |
charge.dispute.closed |
Won: the order goes back where it was. Lost: the order is marked Failed |
review.opened |
A Radar review puts the order On hold; its previous status is remembered |
review.closed |
Approved: the order goes back where it was. Otherwise an order note |
Then gmstripe_webhook_{event_type} fires for every verified event.
Money
Amounts are sent in Stripe's minor units. Zero-decimal currencies are sent as they are; three-decimal currencies (BHD, KWD, OMR and others) are rounded to multiples of ten, the only form Stripe accepts.
Level 3 data — the order's line items — is sent on card payments when the store's base country is the US and the order is in USD, which earns a lower interchange rate on US commercial cards.
On the order screen and the overview
Every order paid by Stripe gets a Stripe payment panel: the payment intent, the mode, whether funds are captured or only authorised, Stripe's fee and the net in your payout currency, where it was placed from (checkout, Checkout block, express button, subscription renewal or pre-order release), and any voucher.
WooCommerce → Stripe overview summarises the last 30 days from your own orders: paid through Stripe, Stripe fees, net, orders awaiting capture, and a breakdown by payment method.
Moving from another Stripe plugin
Orders and subscriptions are bound to the gateway id of the plugin that took them. This plugin answers to the ids of WooCommerce's own Stripe gateway, WooCommerce Payments, Payment Plugins for Stripe and FunnelKit's Stripe gateway (stripe, stripe_sepa, woocommerce_payments, stripe_cc, fkwcs_stripe and so on), and reads their stored intent ids, so past orders can be refunded and live subscriptions keep renewing after a switch. The cards themselves stay at Stripe, under your account.
This is done by translating the id when an order is read — no order is rewritten, so deactivating this plugin puts everything back as it was. It adopts nothing while one of those plugins is still active. Use the same Stripe account's keys.
Other plugins
Integrations load only when their plugin is present: CheckoutWC, CartFlows and FunnelKit checkouts (so the plugin knows their pages take payment); Product Add-Ons, TM Extra Product Options and Advanced Product Fields (the express button is removed from a product with priced add-ons, because it would buy the base product without them); and German Market / Germanized (express buttons are switched off, because German law requires a confirmation step a wallet button skips). These integrations are written from those plugins' public hooks and have not been tested against them yet.
