Set Up Stripe Payments
Taking cards in Easy Digital Downloads usually means one gateway for checkout, another setup for wallet buttons and a separate add-on for recurring payments. When a renewal fails, you end up digging through more than one log to find out why.
The Stripe module is a Stripe gateway built into Stackless. It runs the Stripe Payment Element at checkout, saves cards for signed-in customers, shows Apple Pay, Google Pay and Link buttons, refunds from the EDD order screen and charges subscription renewals off-session.
Turn On the Gateway
Setup lives in two places:
- Switch on the Stripe module under Stackless → Dashboard.
- Add your keys under Stackless → Settings → Stripe.
- Go to Downloads → Settings → Payments and switch on Stripe (Stackless) under Active Gateways. Save.
The Payments tab also gets a Stripe (Stackless) section. It only holds an Open Stripe settings button that takes you back to the Stackless screen, where everything else lives.
Stripe stays hidden at checkout until the selected mode has both a publishable key and a secret key. EDD’s own Stripe gateway is a separate gateway with its own keys, customers and webhooks, so both can be switched on at once.
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 and no real money moves. Checkout shows a note with the test card number.
- Test publishable key, Test secret key and Test webhook signing secret
- Live publishable key, Live secret key and Live webhook signing secret
This switch is separate from EDD’s Enable Test Mode. 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 to finish activation in the Stripe Dashboard.
Connect the Webhook
The webhook URL is https://yoursite.com/wp-json/stackless-edd/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_updatedPaste each endpoint’s signing secret into the matching field. It starts with whsec_. Without it, bank debits, refunds made in the Stripe Dashboard, disputes and removed cards won’t sync.
Every delivery is signature-checked and handled once. Events from other sites on the same Stripe account are ignored.
The Status panel below the settings shows whether the gateway is enabled at checkout and which test and live accounts are verified. It also shows the webhook URL, the last signed webhook and the most recent events with their results.
Checkout Settings
- Title: the payment method name shoppers see. Default “Card and more”.
- Description: shown with the payment form. Default “Pay securely with your card, Apple Pay, Google Pay, Link or a local payment method.”
- Capture: Charge immediately (default), or Authorize only, capture when the order is marked Completed. Orders with subscriptions always charge immediately.
- Saved payment methods: lets signed-in customers save and reuse methods. On by default. Subscription orders always save the method for renewals.
- Statement descriptor suffix: up to 22 characters added after your account’s shortened descriptor on card statements. Letters are required, and
< > \ ' " *are removed. - Payment form style: Match my theme (colors, font, light or dark), Stripe default, Flat or Night (dark). Default is Match my theme.
How Authorize Only Works
An authorized order waits as On hold. Marking it Completed captures the payment. Moving it to Failed, Revoked or Abandoned releases the authorization. Authorizations expire after 7 days, so capture before then.
Express Checkout Buttons
The Express checkout section controls the Apple Pay, Google Pay and Link buttons:
- Show buttons on: Download pages and Checkout. Both are selected by default.
- Button label: Logo only, Buy with (default), Checkout with, Order with or Pay with.
Apple Pay also needs your domain added in Stripe → Settings → Payment method domains.
On a download page, the wallet buys only that download. The shopper’s cart is set aside and restored afterward. The buttons don’t show for free downloads with a single price or for prices below Stripe’s minimum charge.
Wallet purchases run through EDD’s normal purchase processing, so discounts, taxes, fees and required checkout fields still apply. Guests only see the buttons when EDD allows guest checkout, because a wallet can’t create an account.
Saved Payment Methods
Signed-in customers get a Payment methods tab on the customer account page. They can see saved methods, make one the default, delete one or add a new one. Deleting a method also detaches it in Stripe.
Saved test methods and saved live methods are kept apart, so a test card never shows on a live checkout.
Refunds and Disputes
Refund from the EDD order screen as usual, in full or in part. The refund form gets a Refund the charge in Stripe box, ticked by default. Stripe is called before EDD records the refund, so a refund Stripe declines stops there instead of leaving a refund that never reached the customer.
An order that was only authorized can be released in full, but it 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 amount, reason and dispute id. A Completed or Partially Refunded order is put on hold through EDD’s own dispute record, which pauses file access.
Subscription Renewals
Stripe renews subscriptions automatically. It supports several subscriptions in one order, free-trial signups with nothing due today, payment method changes, renewal amount changes 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 renewal 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 Downloads → Tools → Debug Log, tagged
stackless-edd-stripe_gateway. Errors are always logged. Keys and card data never are. - Stripe hides itself for currencies it doesn’t support and for totals below Stripe’s minimum charge, such as 0.50 for USD or EUR.
- Each order is refunded and captured in the mode it was paid in, even after you switch between test and live.
- On a site Stackless treats as a copy of the live store, such as a staging clone, saved payment methods aren’t charged for renewals.
- Stripe can’t be duplicated with Payment Gateway Tools. Its saved cards and customers belong to one Stripe account.