Connecting Stripe

Updated 11 November 2026

Overview

This article walks through connecting Stripe. Stripe collects money from the shopper's card when an exchange or a Shop Now cart costs more than the credit on the return, when a handling fee is above the return's credit, on an Instant Exchange, and when your team collects a price difference on a manual return. If none of those apply to your store, you do not need it.

Use the menu on the left to quickly navigate this article.

Before you start

• A Stripe account with its secret key and publishable key to hand. Use test keys while you try things out.

The Stripe page

In the admin, go to Tools > Integrations > Stripe.

The same page opens from Connect Stripe for payments on the Home checklist.

• Secret key: from your Stripe dashboard, starting sk_test_ or sk_live_. It stays on the server and is used only to create payments and refunds. It is never sent to the shopper's browser.
• Publishable key: the matching public key, starting pk_test_ or pk_live_. The shopper's browser loads it so Stripe's own card form can collect card details in the portal.
• Webhook signing secret: optional. Needed only if you have set up a Stripe webhook that points at /api/webhooks/stripe. Find it in the Stripe dashboard under Developers > Webhooks.

Click Save Changes. Once a secret key is saved, the status reads Connected with your Stripe business name when Stripe accepts the key, or Saved (verifying) while it is being checked. The Test mode or Live mode tag shows which kind of key is saved. If Stripe rejects the key, a banner reads Stripe rejected this secret: followed by Stripe's reason. The Open Stripe Dashboard button in the header opens your Stripe API keys page.

Important: A charge made on a live key is real money, and so is the refund of it. Stripe's own fees apply. Switch both keys to live before you go live, not before.

Screenshot

Tools > Integrations > Stripe, the status pill reading Connected with the Test mode tag, the three key fields and the Save Changes button

Disconnect Stripe

Disconnect at the foot of the page clears every saved Stripe key after a confirmation. A return that carries a card charge cannot be rejected or cancelled while Stripe is off. The reject or cancel is refused and a banner reads The shopper's X card charge has not been refunded. Reconnect Stripe, or refund it in Stripe manually. To finish, reconnect Stripe, click Refund Charge and then reject or cancel again. Or refund the charge in Stripe by hand and click Close Return, which records the refund and rejects or cancels the return. See Held returns.

While Stripe is off or disconnected, a manual return with a difference to collect shows Collecting a payment needs an active Stripe connection on this store. in its payment box. See Manual returns.

What the shopper sees

When an exchange costs more than the item being returned and the policy collects the difference, the shopper pays the difference by card on the review step. On Shop Now, the shopper pays any amount above the credit at submit. On an Instant Exchange, the shopper enters a card once; the difference is paid as on any exchange and the card is saved for the ship-by deadline.

If the return is later cancelled, rejected or expires, or the replacement turns out to be out of stock, the charge is refunded to the same card. If your team switches an exchange or Shop Now with a card charge to a refund or store credit before processing, the card charge always goes back to the card; only the returned goods follow the new outcome. A shopper cannot make that switch on their own: where a card charge stands, their change is refused, the outcome stays as filed and the return waits for your team.

With Stripe disconnected, the paid outcomes are still offered, but the review step reads Payments are temporarily unavailable. Please contact support to complete this return. and the shopper cannot submit.

FAQ

Do I need Stripe for plain refunds and store credit? No. Refunds and store credit go through Shopify. Stripe is only for money the shopper pays you on a return.

Why is the Instant Exchange card greyed out on my policy? It needs Stripe. The card reads Connect Stripe to offer Instant Exchange. until Stripe is connected, switched on and has a publishable key saved.

The page says Credentials cannot be read. ReturnZen cannot read the saved key. Save the key again; no charge goes through until you do.

Please reach out to support@returnzen.app with any additional questions.