How Gatemi Stripe for WooCommerce Works

Two rules

  1. 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.
  2. 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

  1. On the checkout the card form is Stripe's Payment Element, served from js.stripe.com inside Stripe's own iframe. Card details never reach your server.
  2. When the shopper places the order, Stripe.js turns the card into a payment-method id, and only that id is posted.
  3. 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.
  4. 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:

  1. If no signing secret is set for the current mode, it is refused (401).
  2. The Stripe-Signature header is verified against the signing secret, with a five-minute tolerance. A bad signature is refused (401).
  3. The event id is claimed (an option gmstripe_seen_{id}). The claim is one INSERT IGNORE on 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.
  4. An event for the other mode (a test event on a live store) is ignored.
  5. 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.

Shopping Cart
Scroll to Top